Revideo explainer video
Revideo (version 0.11.0, a Motion Canvas fork) draws the film as one continuous TypeScript scene: generator functions animate signals, and renderVideo renders it in headless Chromium and encodes it with FFmpeg. The starter project (assets/template/) is a complete 71-second demo film with a kit of reusable pieces: a persistent weighted graph under a camera, an input decoder, question cards with a countdown, a code panel, dry-run tables, a complexity ladder, chapter wipes, captions and comic bursts. A new film replaces two files, src/data.ts and the chapter functions in src/film.tsx; every beat in them waits for its narration line.
Every skill in this family makes the same thing: a finished, narrated MP4 with a natural voice, music and effects baked in, built through a state machine that survives interruptions and refuses to deliver anything that has not passed its checks. Only the drawing and rendering steps are specific to Revideo.
$SKILL below means this skill's base directory (the folder this file is in). $S is $SKILL/scripts.
Non-negotiables (and why)
- A video is an MP4 with the voice in it. Not an interactive page, not slides, not a silent render with "add your own narration". A person once had to ask three times for a video and kept getting click-through pages. Extras (a page, a GIF) come after the MP4, never instead of it.
- Natural voice, always tried. Kokoro runs offline everywhere (
$S/voice.pyinstalls it). Never tell the person a voice, or any capability, is impossible until the alternatives are tried and recorded withvstate.py limit ... --tried ... --tried .... A person was once told TTS was impossible when it was not, and read it as being treated as less deserving. Say plainly which limits come from the environment. - The picture follows the voice. Voice first, then animate against
timing.json. Never stretch audio to fit. - Hit the quality bar on the first attempt (
references/quality-bar.md): one persistent subject, every line changes something on screen, eased motion with camera movement, depth and light, music and effects. A second attempt costs the person a day and their trust. - Look at your frames. The visuals and QA phases need a written attestation of what you looked at. Open the stills and the contact sheet with the Read tool; describe what you saw and what you fixed.
- For a coding problem, use the five-part format (
references/dsa-five-part-format.md): decode the problem and every example, brute force, intuition through timed questions, every approach with time and space, final C++ with a dry run. Compile and run the code before writing a word of script.
Start or resume
python3 $S/vstate.py --project <project> status # always first; prints the next command
New project (keep it on local disk, not a synced folder, while rendering):
mkdir -p <project> && cd <project>
python3 $S/vstate.py init --tool revideo --slug <short-name> --format dsa-5part # or --format general
After an interruption (crash, context reset, the 2-hour job cap), run status and continue from the phase it
names. Finished work is never redone unless its inputs changed; the gates detect that by hash.
references/state-machine.md explains every phase and gate.
Phase 1: brief
Ask the person only what you cannot reasonably default (topic, and anything that changes the goal). Default
the rest and say which defaults you picked. Write brief.md with these sections, then vstate.py advance:
- Topic, Audience, Format (dsa-5part or general; target length), Persistent subject (the one thing every chapter acts on), Style (a recipe from quality-bar.md with colours and fonts), Facts (for code: the solution, the compile command, the program's real output for every example), Output (resolution, fps, where to deliver).
$SKILL/assets/examples/lc787/brief.md is a complete example.
Phase 2: script
Write script.json (references/script-format.md): chapters, and per line an id, chapter, scene, cap
(on screen, symbols welcome) and say (spoken, words only), think pauses after questions, optional sfx.
vstate.py advance checks it. Example: $SKILL/assets/examples/lc787/script.json (40 lines, ~6 min).
Phase 3: voice
[ -d source ] || cp -r "$SKILL/assets/template" source # the starter project (demo film + kit)
(cd source && [ -d node_modules ] || PUPPETEER_SKIP_DOWNLOAD=1 npm ci --no-audit --no-fund) # pinned 0.11.0, ~20 s
python3 $S/voice.py --project . --emit source/src/timing.ts
python3 $S/vstate.py advance
Kokoro af_heart by default (meta.voice/meta.speed in the script; references/voice-and-audio.md lists
voices, including Hindi ones). Changing a say re-voices only that line. The emitted timing file is stamped
with a hash; the visuals gate checks your scene code reads the current one.
Phase 4: visuals
Build the film in source/src/ (references/revideo-guide.md has the kit catalogue, timing API and recipes):
- Theme (only if the brief names one):
python3 $S/theme.py emit <id> --format ts --out source/src/theme-active.ts(references/revideo-guide.md, Themes; with no theme the stub there keeps the original palette). data.ts: the facts from brief.md (the subject's nodes and edges, the input as text, the code exactly as compiled, the dry-run rows, the approaches with time and space).film.tsx: one generator per chapter. Every beat waits for its line:at(L.p3.voiceAt),at(cue('p4', 'seven')),when(t, task)insideall(...)for dense lines; never a bare number of seconds. Rearrange the stage only atCARD[n].coveredAt(the chapter wipe covers the frame). For the mini example (assets/examples/mini) the template's demo film is already complete: go straight to the stills.
(cd source && npx tsc --noEmit -p .) # typecheck; silent when fine
node $S/render_revideo.mjs --project . --stills lines --workers 2 # one PNG per line -> stills/
node $S/render_revideo.mjs --project . --stills chapters --workers 2 # one per chapter
Each still takes 15-30 s per worker (the scene re-runs from the start). The stills run ends with a list of
LATE cues (p2@7.62 +1.97s: an animation ran past the cue of line p2); fix every one, usually by scheduling the
beats with when() inside all() instead of one after another. For a quick moving look at a span:
node $S/render_revideo.mjs --project . --range 40,52 writes build/preview.mp4.
Then open every still (Read the PNGs). Check each against references/quality-bar.md ("The review pass"): text
inside the safe area, nothing overlapping or cut off, code glyphs correct, the frame shows what its line says,
and it would sit comfortably next to the reference films. Then measure every text in the stills:
python3 $S/legibility.py --project . # size and contrast of every text; marked copies in stills/legibility/
It fails any text under 26 px or under 4.5:1 contrast, at every size, with no 3:1 large-text exception; the visuals gate needs 0 failing texts. Fix and re-render stills until both the review and the measurement pass, then:
python3 $S/vstate.py attest visuals "Looked at N stills: <what you checked, what you fixed>"
python3 $S/vstate.py advance
Phase 5: render
node $S/render_revideo.mjs --project . --bench 3 # steady fps per worker and the ETA for the whole film
mkdir -p build && node $S/render_revideo.mjs --project . --workers 4 --max-minutes 100 > build/render.log 2>&1
Run the second command in the background and poll build/render.log (progress, fps and ETA every 20 s). Use
--workers 2 on a shared or small machine. It renders 20-second segments in child processes, records them in
build/segments/manifest.json, skips finished ones on a re-run, and concatenates them into build/silent.mp4
(H.264, yuv420p, CRF 18) with the exact length of the voice timing. Exit code 3 means the --max-minutes budget
ran out: run the same command again. Any change to source/src or the timing starts the segments over, so
finish the visuals first. Speed: about 1 frame/s per worker on a busy 4-CPU sandbox (the demo's earlier 62 s cut took 24 min
with 2 workers); a laptop with 6 workers is several times faster. Trust the --bench ETA over these numbers.
python3 $S/vstate.py advance # checks codec, size, fps, duration against the voice timing, segments
Phase 6: mix
python3 $S/music.py --project . # --mood calm|piano|pulse|none (default: script meta.music)
python3 $S/mix.py --project . # voice + ducked music + effects, loudness -16 LUFS, yuv420p
python3 $S/vstate.py advance
Phase 7: QA
python3 $S/qa.py --project .
It checks format, duration, loudness, voice sync for every line, black frames, frozen shots and single-frame
flicker, and writes qa/report.md, qa/contact-sheet.png and qa/stills/. Open the contact sheet and the
stills. If anything is wrong, vstate.py reopen visuals --reason "...", fix, and come back through render and
mix. When it is right:
python3 $S/vstate.py attest qa "Contact sheet and N stills: <what you saw>; report: <pass/warnings>"
python3 $S/vstate.py advance
Phase 8: deliver
python3 $S/vstate.py notes-md > NOTES.md # fill every (fill in): tool versions, style, re-render commands
python3 $S/package.py --project . --to <deliver folder> # a new or empty folder; it never empties one it did not make
python3 $S/vstate.py advance
python3 $S/vstate.py report # use this for the final message
The final message leads with the video (attach or link the MP4), then in a few lines: length, voice used, the
style, any limit and which part of it came from the environment, any warning, and that edge_voice_swap.py
re-voices it on a laptop (for example with en-IN-NeerjaNeural). Do not claim anything the report does not show.
Revideo gotchas
- Exporter: Revideo's default WebCodecs exporter fails headless ("Encoder creation error"); the render script
always passes
exporter: {name: '@revideo/core/ffmpeg', options: {format: 'mp4'}}, a local Chromium (CHROMIUM=/pathto override;/opt/pw-browsers/chromiumhere) and--no-sandbox. Install withPUPPETEER_SKIP_DOWNLOAD=1.@revideo/uimust be installed even headless. - Hangs: a scene exception makes
renderVideowait forever. The script renders each segment in a child process and kills it on a page error or after--stallseconds without progress; read thepage:line it prints. - Text bound to a signal (
text: () => ...) throws "The scene is not available in the current context". Update text fromonFrame()or usecounter(). - Ligatures: JetBrains Mono turns
!=,<=,++into single glyphs; every code or monoTxtneedsletterSpacing: 0.01(the kit'sCodePanel,mono()andlabel()set it). - Fonts come from
@fontsource(Google Fonts is blocked here) andproject.tsawaits each weight before frame 1; a new font needs the same two lines there. - Determinism: the scene function runs several times per render and on every worker; no
Math.random(), no wall-clock time, no side effects outside the scene (userng(seed)). - Speed: rendering is CPU-only here. A full-frame gradient or an image drawn scaled or at a fractional
offset costs 20-30 ms per frame; the same image drawn 1:1 at whole pixels ~5 ms. The kit bakes the backdrop,
light pool, vignette, caption scrim and grain into textures (
kit/textures.ts) and rounds their positions; do the same for any new full-frame layer, and avoidcompositeOperationblends and big shadow blurs. - File size: anything that changes every frame across the whole picture is noise to H.264. Grain re-jittered
each frame made the MP4 22 Mbit/s (165 MB a minute); static grain gives 3.3 Mbit/s. The kit's grain is static
(
GRAIN_HOLD = 0inkit/stage.ts); keep full-frame noise and flicker effects still. - Legibility (
legibility.pyfails the visuals gate): de-emphasise with colour (C.muted, the code panel's quiet colours), never with opacity under ~0.6; orange text isinkOf(C.acc). The vignette darkens only the backdrop and the caption scrim darkens everything under it, so a lower third goes inst.lower(above the scrim). - Layout squashes drawn shapes inside a
layout: trueRect; keep circles and lines outside layout nodes. - Scene file names must be unique by base name (
film.tsnext tofilm.tsxbreaks the?sceneimport). - Debug logs reach the terminal only as a single string argument (
console.log('TL|' + id); seemark()). - Digits in Bangers: its 7 reads as a 1, so a "700!" burst read "100!".
burst()sets any text with digits in Inter Display 800 italic; keep numbers that matter out of the comic font.
References
| File | Read when |
|---|---|
references/revideo-guide.md |
Building scenes and rendering with Revideo: setup, component catalogue, timing API, recipes |
references/quality-bar.md |
Before designing the style, and at every review |
references/dsa-five-part-format.md |
Any coding-problem explainer |
references/script-format.md |
Writing script.json; reading timing in scene code |
references/voice-and-audio.md |
Voices, languages, music moods, mix levels, blocked TTS |
references/state-machine.md |
Gates, resume, reopening a phase, long renders |
references/environment.md |
Paths, fonts, render speeds, the 2-hour cap, laptop differences |
references/lessons-learned.md |
Once per project: why each rule exists |