Narrated collage explainer

The voiceover drives everything. Write the script, generate the voice, and each beat starts on the words it names. The example is examples/prismor/: a 50 s Prismor explainer with 16 beats that uses Prismor's real README GIFs and screenshots.

Workflow

1. Script (vo.txt): write 90–120 words, which is about 45–50 s. Use short sentences and name one idea per sentence. Every beat needs a phrase you can cue on. Claims must come from the product's own docs.
2. Voice: python3 scripts/collage.py voice --brief brief.json runs OpenAI TTS (vo.voice, vo.instructions), then Whisper for word timestamps. The script stays the source of truth for spelling; Whisper only supplies timing.
3. Beats: in brief.json, each beat has "at": "<cue phrase from the script>" and a type (below). A beat runs until the next beat's cue. Cards and overlays inside a beat can have their own "at" cues.
4. Media: prefer real material, meaning the product's own screenshots, played inside a window.
   • Terminal content goes in as native text (kind: terminal), not GIF crops, which cut lines off and go illegibly small inside a device. Retype the real transcript as short lines of ≤ 26 characters. The screen auto-sizes the font to fill its safe area and never clips.
   • Brand icons come from thesvg.org. python3 scripts/collage.py icons --brief … downloads every slug used by icons beats (the light-background variant when there is one), rasterises it with headless Chromium, and records source and licence in assets/icons/icons.json.
   • Generate only scenery (assets: hills, CRT, retro computer, archival photos) at low/medium quality. The logo slot is always the real logo.
5. Check: check prints the beat table, confirms the voice exists, and fails on any text overflow. Then review with still … t1 t2 and sheet.
6. Render: render muxes the voiceover automatically.

Beat types