demo-video-builder

Demo Video Builder

Turn one screen recording into a polished, narrated, privacy-clean demo video — fully scripted, no video editor.

Operating principles (read first)

• Use the real screen, never mock-ups. Every frame comes from the actual recording. Do not fabricate UI, type-ins, or numbers. If a number is spoken in VO, it must be visible on screen at that moment.
• Privacy is non-negotiable and easy to miss. Real recordings bake in leaks: address-bar URLs with tokens/tenancy IDs, personal bookmarks, browser-extension badges (e.g. Grammarly), usernames, avatars, and internal engineer/customer names typed into fields. Every shipped frame must be scrubbed. See references/privacy-scrubbing.md.
• Original framing by default. Keep each screen at its native scale; only cover the browser chrome. Reframe/crop only when asked. Use a gentle push-in zoom for readability, not a permanent crop.
• Sync VO to the action. Fit each beat's footage to its narration so words land on what's on screen.
• Cut the dead air. Remove "thinking…" / spinner / loading lags — they're the difference between a 3:30 slog and a tight 3:00.
• One source of truth. demo_config.py holds the beats and their narration. gen_vo.py and build.py both read it. Change the config, re-run — never hand-edit intermediate files.
• QA until clean. A demo isn't done until an adversarial pass finds no privacy leak, no VO-sync drift, and clean playback. Use the demo-qa-reviewer agent.

The pipeline (7 phases)

1. Map the recording into beats. Watch/scrub it; note the start/end seconds of each meaningful action (setup, question typed, answer rendered) and every lag to cut. → references/map-and-cut.md
2. Cut lags — a beat's spans list concatenates only the kept ranges; the gaps (thinking/loading) are dropped automatically. → references/map-and-cut.md
3. Scrub privacy — cover the browser chrome with a color-matched bar; drawbox-mask any residual leak (subtitle names, extension badges, usernames). Use time-gated masks when content scrolls mid-beat. → references/privacy-scrubbing.md
4. Frame & zoom — keep native scale (cover chrome, don't crop); add a slow push-in zoompan on dense answers for readability. → references/framing-and-zoom.md
5. Voiceover — write tight, domain-accurate narration per beat in demo_config.py; gen_vo.py renders one MP3 per beat with edge-tts. → references/voiceover-and-sync.md
6. Assemble & sync — build.py time-fits each beat's footage to its VO (freeze-hold if footage is short), overlays the VO, and concatenates with the opener/outro. → references/voiceover-and-sync.md
7. QA — decode integrity, silence gaps, contact sheet, then the demo-qa-reviewer agent. Fix, rebuild. → references/qa-checklist.md