Code-driven explainer videos. A script and a voice-over go in; a word-synced, animated 9:16 Reel comes out.
I use this engine for How it actually works, a series of one-minute videos that explain everyday tech: where your password goes, what happens when you open a website, how a contactless card pays without a battery, and how end-to-end encryption hides your messages.
Every frame is drawn by code. Each sentence of the voice-over gets its own scene, and the animation inside a scene is timed to the individual words: the salt types itself out as the narrator says "salt", the counter races to a billion on "billions".
Complete: four episodes, about a minute each.
| # | Topic | Video |
|---|---|---|
| 01 | Where does your password go? Salting, hashing and why "forgot password" sends a link | Reel |
| 02 | What happens when you open a website? DNS, the handshake, a secret key that never travels, and how the page gets built | Reel |
| 03 | What happens when you tap your card? A battery-free chip powered by the reader, and a one-time code your bank checks | Reel |
| 04 | How can nobody read your messages? Public and private keys as a padlock, per-message keys, security codes, and the metadata catch | Reel |
Under a minute each, one look for the whole series (black + luminous green, Space Grotesk + Fira Code). Every language gets the same beats: where it came from, how it runs, its signature idea, hello world, where it is used.
| # | Topic | Video |
|---|---|---|
| 00 | How does code actually run? Ones and zeros, compilers, interpreters and virtual machines | Reel |
| 01 | C: straight to machine code, pointers, and the memory bugs behind 70 % of serious security holes | Reel |
| 02 | C++: classes on top of C, zero-cost abstractions and destructors | Reel |
| 03 | Java: bytecode for a computer that doesn't exist, the JVM, JIT and garbage collection | Reel |
| 04 | C#: the name joke, IL and the .NET runtime, and the async/await idea everyone copied | Reel |
| 05 | Python: named after Monty Python, indentation as syntax, bytecode + interpreter, and the C under AI | Reel |
| 06 | JavaScript: ten days in 1995, not Java, JIT in V8, the typeof null scar, and Node (opens on an AI-generated hook clip) |
Reel |
| 07 | TypeScript: the typo that ships, types next to values, erased by the compiler, and #1 on GitHub in 2025 | Reel |
| 08 | SQL | coming soon |
| 09 | HTML and CSS | coming soon |
| 10 | Go | coming soon |
| 11 | Rust | coming soon |
| 12 | Kotlin and Swift | coming soon |
| 13 | PHP | coming soon |
| 14 | Assembly | coming soon |
flowchart LR
S[script.md<br/>one line = one scene] --> V[Text to speech<br/>voice.mp3]
V --> W[Speech to text<br/>words.json with timestamps]
S --> T[build_timing.py<br/>timing.json]
W --> T
T --> P[player.html + episode.js<br/>seek(t) draws any frame]
P --> R[make.mjs<br/>Chrome DevTools Protocol<br/>captures 30 fps]
T --> B[soundbed.py<br/>music bed + whooshes]
R --> F[ffmpeg<br/>voice ducks the bed<br/>loudness -14 LUFS]
B --> F
V --> F
F --> M[reel.mp4<br/>1080x1920]
- Script.
script.mdholds the voice-over, one sentence per line. Each line becomes one scene. - Voice and timestamps. The script is voiced with text-to-speech, then transcribed again with speech-to-text to get the start and end of every word.
- Timing.
build_timing.pymatches the transcript to the script line by line (and fails loudly if a word is missing or different), producingtiming.json. - Deterministic player.
player.htmlloads an episode and exposesseek(t), which draws the frame at exactlytseconds: the SVG scene, the headline with its accent word, the chapter progress bar and karaoke captions. Nothing depends on wall-clock time, so a frame always looks the same however long it takes to draw. - Frame capture.
make.mjsserves the repository, opens the player in headless Chrome, and steps through time at 30 fps over the DevTools protocol, saving a screenshot per frame. Rendering speed doesn't matter, so audio and video can't drift. - Sound.
soundbed.pysynthesises a quiet four-chord pad and a whoosh before each scene in pure Python. ffmpeg mixes the voice on top with sidechain ducking, normalises loudness for Instagram (-14 LUFS) and encodes H.264 in limited-range BT.709. - Optional hook clip. With a
hook.json({"clip": "hook.mp4", "until": 3, "fade": 0.35}) in the episode, a video clip plays full screen for the first seconds. The player is captured a second time with a transparent background and no scene, so the header, headline and karaoke captions sit on top of the clip, then the clip crossfades into the animation. Clip, overlay and frames are combined in RGB so the colours match.
A scene gets its local time t and the start time of every spoken word w[k], and returns SVG. Helpers in engine/lib.js turn progress values into drawing, typing, popping and fading (simplified from episode 1):
{ // "First, it adds a few random characters. That's called a salt."
headline: 'Add a *salt*',
draw: ({ t, w }) => {
const n = Math.floor(SALT.length * seg(t, w[4], w[6] + 0.2)) // type the salt while "few random characters" is spoken
return text(x0, 330, PW, { size, cls: 't m' }) +
text(sx, 330, SALT.slice(0, n), { size, cls: 't m ac' }) +
text(sx + 115, 450, 'SALT', { size: 40, cls: 't ac', opacity: seg(t, w[10], w[10] + 0.3) }) // on the word "salt"
},
}Because every scene is a pure function, the test suite can render each one every 0.1 s and check that no NaN or undefined ever reaches the SVG.
Requirements: Node.js 22+, Python 3.9+, ffmpeg and Google Chrome (or Chromium). No npm packages.
git clone https://github.com/arslanagayev/explainer-engine.git
cd explainer-engine
node engine/make.mjs ep01-password # -> episodes/ep01-password/out/reel.mp4
node engine/make.mjs ep01-password --stills 3,20,27 # a few frames, for checking a scene
npm test # Node + Python testsTo preview with sound in a browser, serve the folder (for example python3 -m http.server) and open engine/player.html?ep=ep01-password&play, then click.
- Create
episodes/<name>/script.mdwith a## Voice-oversection, one sentence per line. - Generate
voice.mp3with any text-to-speech service, andwords.json({"words": [{"text", "start", "end"}]}) with any speech-to-text service that returns word timestamps. - Write
episode.js: a theme (colours and fonts), chapters and one scene per line. - Optionally add
hook.mp4andhook.jsonfor a live-action opening. - Run
node engine/make.mjs <name>.
engine/
player.html Deterministic player: seek(t), headline, chapters, karaoke captions
lib.js Drawing helpers: animated paths, arrows, typing, pop/fade, seeded random
props.js Shared props: laptop, server, database, lock, pills, gears, phones, keys
series-languages.js One look and shared props for the languages series
build_timing.py Script + word timestamps -> timing.json (one line = one scene)
soundbed.py Synthesised music bed and scene whooshes (no dependencies)
make.mjs Static server + headless Chrome frame capture + ffmpeg mix and encode
episodes/
ep01-password/ script.md, episode.js, voice.mp3, words.json, timing.json, caption.md
ep02-website/ same layout; every episode has its own colours and fonts
ep03-card/
ep04-messages/
lang00-how-code-runs/ series 2, one episode per language
lang01-c/
lang02-cpp/
lang03-java/
lang04-csharp/
lang05-python/
tests/ Node tests for the helpers and every episode, Python tests for timing
docs/ Preview GIF and scene sheet
Each episode uses one two-colour combination from @design.deb's colour combos and its own typefaces:
- Episode 1: Tiffany
#21F1A8+ Dark Gray#171717, Sora and Red Hat Mono. - Episode 2: True Pink
#FD1843+ Chill White#FFF9FA, Bricolage Grotesque and Azeret Mono. - Episode 3: Turmeric
#FFBE0B+ Malt#2A2312, Syne and Spline Sans Mono. - Episode 4: Skin Tone
#FFC6A8+ Bridal#741A2F, Fraunces and Sometype Mono. The visuals use generic phones and padlocks, no messenger branding. The format (a question, a myth busted, the mechanism step by step with "but what if…?" twists, and a callback ending) was inspired by short-form explainer videos.
- Voice-over: ElevenLabs text to speech ("Liam"), word timestamps from ElevenLabs Scribe.
- Music bed and sound effects are synthesised in code.
- Opening shots of languages episodes 06 and 07: AI-generated clips made with Higgsfield (fictional people, no real person).
Code is MIT licensed. See LICENSE.
