product-demo-director

name	product-demo-director
description	Turn raw screen recordings + a shot list into a finished, narrated, before/after product-demo video — voiceover, music, kinetic captions, motion, and an AI judge loop. Use when producing an investor or sales demo video from product footage.

Product Demo Director

Give it raw footage and a JSON shot list; it directs the cut: ElevenLabs voiceover per shot, a music bed sized to the runtime, kinetic captions that match the narration, continuous push-ins and drift, a white-flash match-cut at the before→after pivot, then a Gemini judge that watches and hears the result and scores it so an improve loop can push it to ship quality.

The motion engine is a single props-driven Remotion composition, so one pipeline renders many cuts (teaser, walkthrough, race, full demo) from the same assets.

When to use

• Producing a before/after product demo from screen recordings (investor or sales).
• Re-cutting one set of footage into multiple lengths/formats.
• Any narrated, captioned, music-scored demo that needs to look directed, not screen-grabbed.

Not for: editing arbitrary cinematic footage, or anything where you don't control the shot list.

Setup (once)

cd engine && npm install && cd ..
python -m venv .venv && . .venv/bin/activate && pip install -r tools/requirements.txt
playwright install chromium          # only if you use tools/capture.py
export ELEVENLABS_API_KEY=...         # voiceover + music
export GEMINI_API_KEY=...             # judge (or GOOGLE_API_KEY)

Run the pipeline

A project is a folder with script.json + an assets/ dir of clips (and, ideally, a brand.json and a product.json). Two runnable examples: examples/promo/ (the original showcase) and examples/self/ (the skill demoing itself — brand-themed, brief-drafted, footage it captured). The first three steps below are the new front of the pipeline — onboard a brand, let the director capture the footage, and draft the script from the product brief — so you don't have to pre-record or hand-write anything:

# 0a. ONBOARD — auto-extract the brand (palette/font/logo) from the product site, confirm, write brand.json
python tools/onboard.py --project examples/self --url https://yourproduct.com   # or --template / --manual

# 0b. SHOOT — the director records the footage itself -> assets/<name>.mp4 (web app and/or terminal/CLI)
python tools/shoot.py --project examples/self                                    # reads shoot.json
#   (one-shot web:  python tools/shoot.py --url https://app.x.com --goal "tour it" --out assets/web.mp4)

# 0c. DRAFT — turn product.json + brand.json + the footage into a script.json (craft rules baked in)
python tools/script.py --project examples/self

# 1. voiceover  -> <project>/audio/s<n>.mp3 + manifest.json
python tools/vo.py    --project examples/self

# 2. music bed  -> <project>/music.mp3 (sized to the narrated runtime)
python tools/music.py --project examples/self

# 2b. (optional) regenerate the bespoke SFX palette (a model listens and keeps the best/cue)
python tools/sfx.py

# 3. assemble + render -> <project>/out/demo.mp4  (props.json now carries the brand theme)
python tools/build.py --project examples/self

# 4. judge (watches + hears) -> JSON scorecard
python tools/judge.py --video examples/self/out/demo.mp4 --fps 6 --context "what this demo is"
# (pin one --model when comparing cuts; the judge is noisy — read overall_model, judge 2-3x for a median)

Steps 0a-0c are optional conveniences: every example ships a committed brand.json/script.json, so the pipeline runs without any LLM key. brand.json is the brand source of truth — its palette, font, and logo flow into the engine theme (not just the CTA wordmark), so the whole cut adopts the brand. See docs/CAPTURE.md for autonomous shoot planning + terminal footage.

To iterate automatically, feed judge.py's specific_upgrades back into the script/engine and re-render (pairs well with github.com/crimeacs/auto-improve as the keep/revert gate).

Script schema

script.json (canonical example: examples/promo/script.json). Each shot is one of title | clip | split | stat | cta | score | bars | strip — score is an animated count-up to a number, bars is the rejected-takes-clear-a-PASS-line visual, strip pans a filmstrip of shots:

{
  "fps": 30,
  "music": "calm confident minimal corporate underscore, soft pulse, no drums",
  "brand": { "name": "Product Demo ", "accent": "Director" },
  "pronounce": { "Foresyn": "Foreseen" },
  "voice_settings": { "stability": 0.32, "style": 0.75, "similarity_boost": 0.85, "use_speaker_boost": true },
  "shots": [
    { "n": 1, "kind": "title", "title": "Your demo is a flat screen recording.", "durSec": 2.6, "vo": "..." },
    { "n": 2, "kind": "clip",  "src": "raw.mp4",      "inSec": 2, "chapter": "BEFORE", "scale": 1.0, "vo": "..." },
    { "n": 3, "kind": "clip",  "src": "raw.mp4",      "chapter": "AFTER", "flash": true, "scale": 1.2, "vo": "..." },
    { "n": 4, "kind": "split", "srcL": "raw.mp4", "labelL": "Raw", "srcR": "directed.mp4", "labelR": "Directed", "durSec": 4, "vo": "..." },
    { "n": 5, "kind": "stat",  "title": "Scored 92 / 100.", "durSec": 2.5, "vo": "..." },
    { "n": 6, "kind": "cta",   "title": "the demo your product deserves", "durSec": 3, "vo": "..." }
  ]
}

Notes:

• When a shot has vo, the on-screen caption defaults to that exact line (subtitles match the narration). Override with an explicit caption.
• accent on a shot fires a palette sound on that beat (click, data_tick, success_chime, confirm_cash, pivot_boom); the pivot also gets a riser + boom automatically.
• flash: true (or chapter: "AFTER") marks the pivot — the white-flash match-cut, the riser before it, and the impact on the reveal all key off it.
• pronounce rewrites spellings for the TTS audio only; captions keep the real spelling.
• brand.name + brand.accent render the CTA wordmark (accent tail colored).

Craft rules

The methodology — each rule was a real mistake first — lives in docs/EDITING.md (the edit) and docs/CAPTURE.md (capturing live-app footage). Read them before authoring a script. Highlights:

• Subtitles are the narration. Caption == the spoken line on every narrated shot.
• Kill dead air. Keep narration near-continuous on fast cuts; music-only > ~5s reads as dead.
• Show the work. Open from the real entry point; feature one click-to-evidence beat.
• Redact identifiers, never the value. Hide client marks; keep the proof sharp and legible.
• Be honest. Only verified numbers; no capability the product doesn't have.

Credit

Built at Foresyn. MIT licensed.