# Milestone 5 Demo Video Specification

Status: approved and ready for execution
Prepared: 2026-07-20 HKT
Parent plan: `docs/current/milestone_5_plan.md`

## Purpose

Produce a public, English, AI-narrated Chartsmith demonstration that is shorter
than three minutes and gives judges concrete evidence of:

1. a working product;
2. the communication gain from source chart to redesign;
3. the value of reconstruction, concept exploration, inspection, and repair;
4. meaningful Codex collaboration during Build Week; and
5. meaningful GPT-5.6 integration inside the product.

The video is a product demonstration, not a generative film. Real product state
and accepted run artifacts are the visual authority.

## User Authorization

The user authorizes Codex to install local tools, renderer packages, codecs, and
other dependencies required to produce a higher-quality demo.

This authorization covers:

- open-source or no-additional-cost local software;
- project-local Node or Python packages;
- browser capture helpers;
- deterministic video renderers;
- FFmpeg or equivalent encoding tools;
- caption, audio-normalization, and media-inspection utilities.

It does not authorize:

- a paid subscription;
- usage-billed external video or speech APIs;
- creation of a new external account;
- disclosure of credentials;
- uploading or publishing the video.

If high-quality narration requires a paid service, new credentials, or
usage-based spending, Codex must stop at that boundary and ask. Tool selection
within the authorized local boundary is a technical decision owned by Codex.

## Production Principle

Use generative media only where it cannot misrepresent product behavior:

- acceptable: title cards, separators, subtle textures, and non-data decorative
  transitions;
- required: real browser capture for product interaction and UI state;
- required: retained Chartsmith run artifacts for reconstruction, concepts,
  candidates, review, repair, and final output;
- prohibited: generated or fabricated Chartsmith screens;
- prohibited: simulated progress presented as a live run;
- prohibited: invented charts or repair findings presented as portfolio
  evidence.

The video should feel designed, but its evidence must remain auditable.

## Preferred Tooling Strategy

Codex will select the smallest reproducible stack that passes the quality
contract.

Preferred roles:

- **capture:** Playwright or the in-app browser for repeatable product frames,
  with OS-level recording only when motion cannot be reconstructed cleanly;
- **graphics:** existing Chartsmith assets plus built-in image generation for
  non-evidentiary title and transition material;
- **timeline and motion:** a deterministic code-defined renderer such as
  Remotion, or an equivalent local composition pipeline;
- **encoding and inspection:** FFmpeg/ffprobe or an equivalent verified local
  encoder;
- **narration:** high-quality English text-to-speech within the approved
  no-additional-cost boundary;
- **captions:** generated from the final approved script, then burned in or
  supplied as a synchronized sidecar according to the upload path.

The repository must retain the script, timeline source, caption source, render
command, and QA report so the video is reproducible.

## Output Contract

- container: MP4;
- video codec: H.264;
- audio codec: AAC;
- frame size: 1920 x 1080;
- aspect ratio: 16:9;
- frame rate: 30 fps unless capture evidence supports another stable rate;
- target duration: 2:35 to 2:50;
- hard duration limit: 2:59;
- language: English;
- narration: calm, clear AI voice;
- captions: visible, synchronized, and inside safe margins;
- music: none by default;
- destination:
  `docs/current/assets/milestone5/video/chartsmith-build-week-demo.mp4`.

Working renders, frame sequences, and disposable captures belong under an
ignored `output/milestone5_video/` path. Only final submission media and the
small reproducibility/QA record should be tracked.

## Editorial Structure

### 0:00-0:20 — Why this exists

- A busy audience reads a chart before it reads an explanation.
- The user supplies one chart image, not raw data or design instructions.
- Show the strongest source-to-final comparison immediately.

### 0:20-0:55 — What Chartsmith changes

- Contrast naive source hierarchy with the authored final.
- Explain one concrete message made faster to perceive.
- Keep the final chart visually dominant.

### 0:55-1:35 — Why this is a system

- Show perceptual reconstruction.
- Show three materially different concepts.
- Show selection and first render.
- Show one real inspection finding and the repaired result.
- Make the consequence of the workflow visible rather than praising process
  complexity.

### 1:35-2:05 — Codex and GPT-5.6

- Show a brief genuine Codex collaboration artifact or task view.
- Explain how Codex helped clean the repository, design the new workflow,
  implement the product, run real cases, diagnose problems, and harden the
  system.
- Explain that GPT-5.6 performs reconstruction, concept judgment, rendered-image
  review, repair judgment, and final comparison inside bounded stages.

### 2:05-2:30 — Range and proof

- Show the ten-example contact sheet with readable grouped motion.
- State that the portfolio spans ten visual grammars and required 26 targeted
  repairs.
- Briefly show the fair direct-single-call comparison.

### 2:30-2:50 — Honest boundary and close

- Public showcase: complete accepted journeys available immediately.
- Genuine full workflow: available locally and not simulated in hosting.
- Close on: “One chart image. One stronger story.”

## Visual Direction

- Reuse the product's warm cream, near-black, coral, amber, violet, and deep
  teal language.
- Prefer editorial chart motion: crops, guided pans, comparison wipes, and
  annotation reveals.
- Keep transitions short and functional.
- Avoid generic AI imagery, robots, circuitry, excessive glow, or cinematic
  footage unrelated to the product.
- Do not show raw JSON, machine paths, logs, or unreadably small code.
- Maintain a clear focal point in every shot.

## Narration Direction

- First-person singular because the submission is solo.
- Plain English and short sentences.
- Confident but not exaggerated.
- Preserve the user's motivation: experience with a busy boss, belief in the
  power of visualization, and curiosity about how far image understanding can
  take rational design judgment.
- Do not imply exact data recovery, audited accuracy, or hosted live generation.
- Pronounce “Chartsmith,” “Codex,” and “GPT-5.6” consistently.

## Quality Assurance

The final render must pass:

### Truth and compliance

- every product screen is genuine;
- every numerical portfolio claim is supported by tracked evidence;
- pre-existing work and Build Week additions are not conflated;
- Codex and GPT-5.6 use are described specifically;
- hosted/local boundaries are explicit;
- duration is below three minutes.

### Visual

- no clipped UI, captions, charts, or titles;
- no visible cursor accidents or browser chrome unless intentional;
- no unreadable text at normal 1080p playback;
- no judder, broken transitions, stretched images, or inconsistent scaling;
- no defect in any featured Chartsmith output;
- captions remain within title-safe margins.

### Audio

- narration is intelligible on laptop speakers;
- pacing leaves enough time to understand each visual;
- no clipping, long silence, harsh edit, or inconsistent volume;
- narration and captions match;
- final loudness is normalized consistently.

### Technical

- MP4 opens from start to finish;
- H.264 video and AAC audio are present;
- resolution and frame rate match the contract;
- file size is practical for YouTube upload;
- duration is measured from the final encoded file;
- a representative frame contact sheet is reviewed before handoff.

## User Handoff

Codex will provide:

- final MP4 path;
- exact duration and technical metadata;
- narration script;
- caption file or source;
- frame contact sheet;
- QA summary;
- suggested YouTube title and description.

The user will:

1. review the final video;
2. upload it to YouTube as **Public**;
3. provide the public URL;
4. approve its use in the Devpost submission.
