Product Demo Video Recorder

Demo Video - film the real product, crisply

A demo is an argument: every beat on camera proves a claim, and the narration is written to the frame - describing what is actually on screen at that second.

Boundary - this recording has no substitute. The video-shotcraft motion library captures STILL screenshots and glides a fake camera over them; it CANNOT record interaction. Never let it stand in for a tutorial, walkthrough, or any real-product film. It decorates RENDERED scenes in motion-video; the live recording, the DOM motion, and the timestamp-synced script stay here, always. (Standing owner rule, 2026-07-23; see motion-video/references/shotcraft-bridge.md.)

The recording contract

This fires automatically on every demo film, whether or not the user asks for it. These are the rules an agent under time pressure skips first, which is exactly why they are not optional. Rules 1-4: references/storyboard.md. Rules 5-6: references/recording.md.

1. Film the product, not a poster - annotate, never substitute. Every frame is real browser state from the running app, changing because the driver acted on it.

   Annotation drawn over live state is standard practice: callouts, the drawn cursor, spotlight, the terminal panel. A film that explains itself on mute is doing its job. The test is whether the overlay is load-bearing: remove it, and does the frame still show the product doing the thing? If yes it is annotation, use it freely. If no it is a poster - a title card, slide interstitial, mocked screen, static hero image - and it stays banned.

   If a beat can't be staged, cut the beat or fix the app. Never substitute a picture of the claim for the claim. (Slides are legitimate in pitch-deck's deck take, stitched around the demo film, never inside it.) Motion and annotation: references/motion.md.

2. Show the whole journey, not just the money shot. The film covers entry -> setup -> the core loop -> the payoff. A viewer who has never seen the product must be able to follow how a real user gets from opening it to the result. Opening on the final feature reads as a mockup and answers none of "what is this, who uses it, how do you get there".

3. Every claim gets a frame. The storyboard runs both directions: each beat names what it proves, and each claim the narration will make names the beat that shows it. This binds hardest on agent actions - "the agent searched", "it updated memory", "it chose the cheaper route" all need visible on-screen evidence (the tool log, the memory panel, the route badge). A claim with no frame is cut from the narration or earns a beat that shows it. Invisible work is not proof.

4. Storyboard approved before capture - Gate 1 below. Blocking.

5. Smoke take inspected before the full capture - Gate 2 below. Blocking: any failed check means fix the staging and re-smoke, never start the full capture on a known-bad frame.

6. Timestamps derived from the delivered MP4 - Gate 3 below. Never from planned waits, never from the storyboard's estimated holds.

Steps

0. Preflight

Check the machine can do this before promising it: ffmpeg and Xvfb installed (apt-get install -y xvfb on Linux; this recipe is Linux-first - on macOS capture the retina display with ffmpeg -f avfoundation or the built-in screen recorder, same principles: physical pixels, controlled bitrate). Confirm the app runs with demo data and demo credentials, and that credentials stay OUT of the repo (scratchpad only).

1. Storyboard - GATE 1: approval before any capture

Write the visual storyboard before recording anything. One row per beat:

phase | screen | action | proof | narration | duration

Read references/storyboard.md for the format, the journey-coverage checklist, and the claim-to-frame audit. Then show it to the user and stop. Do not stage, do not smoke-test, do not record until they approve or amend it.

A blanket "just make it, I trust you" issued before the storyboard existed is not approval of it - the user has not seen the plan yet. Show the table and wait.

The harness enforces this too: a full take requires --storyboard <path>, and stamps its hash into the sidecar.

This gate is not politeness - it is the cheapest point to change the film. After capture, every edit re-shoots footage and re-syncs narration against new timestamps.

2. Stage the app

Deterministic demo data, seeded to make the beats true. Log in OFF camera. Kill anything that can interrupt the frame: notifications, password-manager bubbles (pre-write Chrome preferences - see recording.md), first-run dialogs. Never trigger JS alerts mid-take; they freeze the driver.

3. Smoke take - GATE 2: inspect before the full capture

Run record_template.py <name> --smoke. It records through the first beat that actually drives something - rendering beat 1 alone cannot catch a dead selector, which is half of what this gate is for - then extracts frames and prints a contact sheet. Read it as an image.

Checking: right app, right screen, right framing, text crisp at full scale, no cursor, no dialog or bubble in frame, chrome hidden, seeded data actually present. Full checklist in references/recording.md.

Any unchecked box means the take is not ready: fix the staging and re-smoke. Never start the full capture on a known-bad frame - that is the whole point of the gate.

A smoke take costs ~30 seconds and catches the failures that otherwise surface after a full take plus a written narration: wrong scale factor, unstaged data, a dead selector, a login bubble covering the money shot.

The harness enforces this: a full take refuses to run until a smoke take exists for that name. --no-smoke overrides it and is stamped into the sidecar - use it only when this app was already captured at this config.