Remotion explainer video
Remotion renders a React component once per frame in headless Chromium and encodes the frames with ffmpeg.
Anything a web page can draw is available, including type, SVG, gradients, shadows and layout, and every frame
is deterministic. That makes it the strongest choice for a crisp motion-graphics look with real typography and
code. The cost is render speed, about 4 to 9 frames per second, so long renders run in the background in
resumable segments. The starter project in assets/template/ already contains:
- a full kit: graph subject, input decoder, question card with countdown, code panel, DP table, complexity ladder, recursion tree, comic bursts, chapter stings, captions and camera
- a director pattern: one file that cues the persistent subject and the camera by line id
- the 71-second mini film, as working demo scenes
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 Remotion.
$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 remotion --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
test -d source || cp -r $SKILL/assets/template source # the starter project
test -d source/node_modules || (cd source && npm ci --no-audit --no-fund) # pinned versions, ~20 s
python3 $S/voice.py --project . --emit source/src/timing.json
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
source/ is a Remotion project that already plays the mini film. Keep src/kit/ (components), src/lib/
(clock and motion) and src/Film.tsx (layer order). A new film replaces only src/scenes/:
scenes/data.ts: the film's facts. The subject's layout (MAP: nodes and weighted edges), where it sits in each chapter (PLACE), the raw input text with tagged entries (INPUT), and the compiled code (CPP,CODE_LINE).scenes/director.ts: the persistent subject and the camera, cue by cue.graphAt(fr)decides what lights up,placeAt(fr)where the subject sits,cameraAt(fr)the push-ins and pull-backs.- One file per chapter (
Problem.tsx,Brute.tsx,Intuition.tsx,Approaches.tsx,Code.tsx). Each exports a...Worldpart, which moves with the camera, and a...Hudpart in screen space for cards, bursts and chips.scenes/index.tsxlists them.
If the brief names a theme (references/themes.md), emit it before the stills:
python3 $S/theme.py emit <id> --format ts --out source/src/kit/theme.ts (guide section 10 has the role mapping).
Every frame number comes from a line id: f('p3') (the voice starts p3), f('p3', 0.4),
fPhrase('p4', 'seven hundred'), fSaid('q1'), fThink('q1'), fStart/fEnd, chapterStart(n), sec(0.5)
for durations. Never type a frame number or a second count. An unknown id or phrase throws, so a script edit
that breaks a cue fails loudly. Plan one visible change per line before coding. references/remotion-guide.md
has the kit catalogue and recipes: decode, route, reject, think countdown, DP row, code walkthrough, camera.
Render review stills. The first run bundles the project (~20 s), then two stills render at a time, 3 to 10 s each:
node $S/render_remotion.mjs --project . --stills lines # one still per line -> stills/
node $S/render_remotion.mjs --project . --stills 15.9,55.4 # plus the busiest moments, in seconds
A scene error prints a stack trace naming the file and line. TypeScript type errors do NOT stop a render, so a misspelt prop silently does nothing: check the stills.
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. Fix and re-render stills until it does. Then measure
text size and contrast; the visuals gate needs 0 failing texts (the kit's SIZE and C already meet the bar,
see references/remotion-guide.md section 4):
python3 $S/legibility.py --project . # red boxes in stills/legibility/: fix, re-shoot the stills, re-run
python3 $S/vstate.py attest visuals "Looked at N stills: <what you checked, what you fixed>"
python3 $S/vstate.py advance
Phase 5: render
Benchmark first: it renders 3 s from the middle of the film and prints the speed and the full-film estimate.
For N, use the CPU core count up to 4 (nproc), or 2 when other heavy jobs share the machine.
node $S/render_remotion.mjs --project . --bench 3 --concurrency N
Then run the full render in the background with a log, so a job cap or a lost shell never loses work:
mkdir -p build && nohup node $S/render_remotion.mjs --project . --concurrency N --max-minutes 100 > build/render.log 2>&1 &
tail -3 build/render.log # poll every few minutes: each segment prints its fps and the ETA
It renders 30-second frame ranges into build/segments/. The ranges are recorded in manifest.json and
finished ones are skipped. It then concatenates them losslessly into build/silent.mp4: H.264 yuv420p,
tv-range bt709, no audio.
- Done: the log prints
silent render: build/silent.mp4 ... <frames> frames. - Budget reached: the log prints
Stopping cleanly(exit code 3), or the job was killed. Run the same command again; it continues from the first unfinished segment. - Speed measured here: 3.9 to 6.5 fps at concurrency 2 on a lightly loaded 4-core machine, and 1.8 to 2.3 fps under heavy load. The mini film (its earlier 62 s cut; now 71 s) takes 5 to 16 minutes; a 7.4-minute film took about 25 minutes at concurrency 4.
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
For NOTES.md:
- Versions: Remotion 4.0.533 (remotion, @remotion/cli, @remotion/renderer), React 19.3.0, Node 22, and the
Chromium headless shell. The exact list is in
$SKILL/tool.json. - Re-render: the plain command works anywhere, and on a laptop Remotion downloads its own browser:
cd source && npm ci && npx remotion render src/index.ts Film ../build/silent.mp4 --color-space=bt709. Then runmusic.py,mix.pyandqa.py. With this skill installed, use the resumablerender_remotion.mjsinstead.
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.
Remotion gotchas
Each gotcha gives the symptom, then the fix. Details are in the guide's Gotchas section.
- yuvj420p output. Remotion writes full-range
yuvj420peven with--pixel-format=yuv420p, which some players and the QA gate reject.--color-space=bt709fixes it at the source. The render script andremotion.config.tsboth set it, and the script re-encodes once if a concat still comes outyuvj420p. - Ligatures in code. With JetBrains Mono,
!=,<=,->and++turn into single glyphs. SetfontFeatureSettings: '"calt" 0, "liga" 0'. It isNO_LIGAinkit/tokens.ts, set on the root byFilm.tsxand again byCodePanel. Keep both. - Fonts. Never load fonts from Google Fonts: it is blocked here, and a late font renders the first frames
in a fallback.
- Import
@fontsource/*inkit/fonts.ts.useFontsReady()holds every frame withdelayRenderuntildocument.fonts.loadhas resolved for each face. - The npm subsets lack
→,∞and≤.RichTextdraws→as an SVG arrow; the font stacks fall back to DejaVu for the others.
- Import
- TypeScript is stripped, not checked.
- Remotion's bundler and Node 22 both strip TS types without type checking. A wrong prop name renders nothing, with no error.
- Node scripts can import
.tsdata files only with erasable syntax: noenum, no parameter properties, andimport typefor types. A JSON import needswith {type: 'json'}.
- Render time. A 7.4-minute film took about 25 minutes at concurrency 4. Always bench, render in the
background with
--max-minutes, and re-run to resume. Do not use concurrency above the number of cores: each worker is a Chromium tab. - Camera crops. A push-in above about 1.1 slides content near the frame edge off-screen. Put screen-anchored
info (chips, meters, receipts) in a
...Hudpart, and push gently or toward the content. <Sequence>resets the frame. Inside a<Sequence>,useCurrentFrame()counts from 0, which breaksf('id'). Use the kit's<Span from to>together withuseF(), which returns absolute frames.- Animated grain. Full-frame noise that changes every frame raised the bitrate to 33 Mbps and slowed
encoding. Keep the grain static (
Finish) and animate the light instead.
References
| File | Read when |
|---|---|
references/remotion-guide.md |
Building scenes and rendering with Remotion: 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 |