/video-explainer
Inputs: projects/$0/ with an approved BRIEF.md, SHOTBOOK.md, narration.json and timeline.json cues.
Outputs: renders/<slug>_vN.mp4 (≥ v2), stems, review/<render>/qa_report.md + critic.md, an updated manifest/costs.
Load only
docs/motion-design.md(tokens, choreography, determinism, engine choice)docs/editing-and-compositing.md§ One timeline, § Audio- The project's chosen style file(s) in
styles/ - Editorial or factual:
docs/editorial-documentary.md. Technical:styles/technical-math.md docs/quality-assurance.mdbefore reviewing
Procedure
- Voice. Scratch first (free):
python tools/narrate.py $0 --provider kokoro. For production, audition Gemini (--audition --provider gemini): print the estimate, get the user's approval, then add--yes. If the user supplied their own recording, put it ataudio/narration.wavand write segments withnarrate.py --aligninstead. python tools/timeline.py $0: resolve every cue against the actual audio.- Scene code. Create
engine/src/projects/<slug>/Scene.tsx(copy the structure ofquestion-to-product/Scene.tsx) and register it inengine/src/projects/registry.ts. Rules:- World space plus one camera container; every state is a pure function of
tandcue() - Easing only from
EASE; randomness only viarnd(seed); fonts fromlib/fonts.ts - Maps: d3-geo + topojson-client + world-atlas (bundled, never fetched at render), with a source line
- Charts: SVG with honest axes, direct labels and a source line; numbers come from BRIEF §4
- Math: Manim CE renders to
assets/manim/*.mp4, composited with<OffthreadVideo> - Images: code-drawn first. Generated (
tools/image_gen.py, paid,--yes) only for illustration/cutouts, recorded in the manifest
- World space plus one camera container; every state is a pure function of
- Style-frame check.
python tools/render.py $0 --stills <cue times>→ look at them, fix layout or safe areas. - Sound. Add
sfxandmusicto timeline.json (peaks on cues, one riser→impact max), thenpython tools/sound_synth.py $0andpython tools/audio_mix.py $0. - Render v1:
python tools/render.py $0 --out <slug>_v1.mp4. - QA + critic: run
/video-review $0 renders/<slug>_v1.mp4. - Revise: fix all P0s and the P1s you agree with, re-render v2, and run review round 2. At most 3 rounds.
- Deliver: see
/video-renderfor platform cuts and the delivery note.
Quality gates
- No hard-coded seconds in scenes: only cues
- Every factual graphic carries a source line; the numbers match BRIEF §4
- qa_report shows no automatic issues; loudness −14 ±1 LUFS, TP ≤ −1 dBTP
- Critic P0 = 0; at least one revision round performed
- Report says what was measured vs what still needs a human listen
Shared parts (2026-11-06)
Build on engine/src/lib/parts.tsx (Svg, PartsDefs, Finish, Push, PartLabel, BigWord, Counter, Dust, Caption, ChatBubble, SAFE). Import them instead of re-writing captions, counters, labels, vignette or safe-area maths; a scene should be 200-400 lines. Add a new reusable piece to parts.tsx when a second project needs it.