product-demo

Product Demo

Turn the app in this repo into a scored, captioned, frame-perfect demo video using only node + playwright + ffmpeg. The pipeline is deterministic: the whole demo re-renders and re-scores from a clean checkout.

The pipeline, in order

Step	Recipe	Output
1. Script	01-script.md	scene table, VO lines with timecodes, rhythm grid
2. Standalone UI	02-standalone-ui.md	app components rendering from a static folder
3. Composition	03-composition.md	one React tree as a pure function of a clock
4. Record	04-record.md	PNG frames → visually lossless H.264 masters
5. Captions + VO	05-captions-vo.md	SRT/VTT sidecars, timecoded voiceover script
6. Sound	06-sound.md	sfx-cues.json, live preview player, auto-mixer
7. Music	07-music.md	EQ-carved, ducked bed starting at the drop
8. Assemble	08-assemble.md	intro + transition + stems → final export

Work the steps in order; each consumes the previous step's output. Steps 5-8 are optional for a silent draft, mandatory for a launch-quality film.

One starter prompt runs everything

When the user asks for a demo, orchestrate all eight steps yourself. Never hand the user a step list or tell them to come back with the next prompt. Instead, ask the user directly in conversation at exactly the moments you need something only they can give, and attach the artifact that makes the question answerable in seconds:

1. After step 1: show the scene table and voiceover script, ask for approval before writing any code. Retiming a script is cheap; retiming a rendered film is not.
2. After the smoke render: show the 4 spot frames, ask to proceed before the long full render.
3. At step 5: hand over the paste-ready tagged voiceover block (no sync notes in it) and ask for the generated audio file path.
4. At step 7: hand over the music-generator prompt you wrote and ask for the generated file path. Both asks can be batched with step 3's if the user prefers one trip to the tools.
5. After the scored preview: deliver a small cut for a listen before exporting final masters.

Between asks, proceed without checking in. If the user declines an optional asset (voice, music), ship without it rather than stalling.

Progress tracking (resumable runs)

Maintain demo/PROGRESS.md in the target repo: one line per step with status (todo / in progress / done) and the artifact paths produced. Read it FIRST in every session; a half-finished pipeline resumes from its last question instead of restarting. Update it after every step.

Decision rules

• User has no script or story → start at 01. Never start by writing code.
• User has a video that stutters → 04 only (frame-by-frame recording fixes it).
• User wants sound/SFX on an existing video → 06 (cue file + mixer), then 07 if music.
• User's demo "feels fake" → the honesty rules in 01 and 03 (real data, reconciling totals).
• User asks how long / what shape → 45-60s, one claim per scene, ~6 scenes, arc: problem → drop → magic → interaction → proof → brand.
• Voice clone sounds slow and flat → the fixes in 05.
• SFX land late or get buried → measured hit offsets + peak normalization in 06.

Non-negotiables (enforce these even if not asked)

1. Honest data. Fixtures must be real: real items, printed prices, totals that reconcile. Never invent rounder numbers.
2. Nothing fades. Everything stamps, slides, rips, or snaps. Fades read as apology. Easing lives in at most three shared helpers.
3. Never screen-record. Render frame-by-frame via the seek contract (04).
4. No sound beats a forced sound. ~10 cues per minute maximum, one per story turn, nothing repeated back-to-back.
5. Two masters. Captions burned + clean, from one composition via a window.__NO_CAPTIONS flag.
6. No flat black. Every dark scene sits on the product's own art or wallpaper, blurred and graded down; the first frame is the thumbnail. Flat black only where it is the product's real surface (03).

Templates

Working scripts in templates/: record.mjs (deterministic playwright frame renderer, resumable), mix-audio.mjs (cue-driven ffmpeg mixer; --vo for a retimed voiceover stem, --bgm for the bed), retime-vo.mjs (cuts a generated read at its silences and places each phrase on its authored timecode), sfx-cues.example.json (a real 10-cue score), package.json (the npm scripts). Copy them into a demo/ directory in the target repo and adapt paths; each recipe says when.

Complementary skills

If the target repo uses Remotion or ElevenLabs, install their official skills too; this skill covers the pipeline and taste, theirs cover their APIs:

npx skills add remotion-dev/skills
npx skills add elevenlabs/skills

What the user receives (besides the film)

Two paste-ready artifacts, so the human workload is exactly two paste jobs: a tagged voiceover block for the voice tool (05) and a style prompt for the music generator (07). Never make the user write either.

Reference outputs

Four demos prove the pipeline on unrelated products: the Vouch demo (54.3s, receipt splitting), an Excalidraw demo (35.5s, filmed on the real @excalidraw/excalidraw npm component, source in this repo under examples/excalidraw), Asakiri Studio (54s, a Tauri+React course editor, real components bundled with esbuild), and Colosseum (54s, a Qt/QML Windows media app, surfaces rebuilt from its tokens and its own screenshots; see the native-app path in 02). The Vouch repo github.com/Anshgrover23/vouch carries the full working demo/ directory, composition, vendored runtime, cue file, captions, as a reference implementation. The manual with every number and failure: https://anshgrover23.github.io/product-demo-playbook/