The coding-agent sessions behind this repository: the prompts, where the agent went wrong and what the human did about it.
Video as code, for developers and their coding agents.
A web page is the film: it draws frame t on demand, in plain HTML, Canvas or anything else a browser runs.
motigen opens it headless, renders every frame in order and pipes them into ffmpeg, so one project gives the same
MP4 on every run. Real terminals and real browsers are recorded and replayed inside the same page; the narration,
the sound effects and the music are mixed from the timeline the page exports; the subtitles come from the same
cues. Everything is a file in git and every step is one command, which is exactly what a coding agent needs to
make a product video on its own.
npm i -g motigenjs && npx playwright install chromium # Node 22+, ffmpeg in PATH; the command is `motigen`
motigen init scenes my-launch && cd my-launch
motigen vo # narration from audio/lines.txt (ElevenLabs), one file per line
motigen build # events β mix β render 16:9 and 9:16 β subtitles, into out/
motigen preview # scrub it, play it with sound, render from a button
For a screencast of a real product: motigen init guide my-guide, then motigen record take.mjs records a real
browser and a real terminal into take/, and edit.js cuts them.
- Four kinds of film, one contract. A page registers
window.__film = { ready, dur, renderAt(t) }. Thescenestemplate makes a launch video from a list of scenes (kinetic titles, statements with a marker, counting numbers, charts, a comparison table, a phone with a notification, feature cards, a product window with a push-in and a callout, a typed terminal, a before/after split, a quote, an end card) with varied transitions and three themes; theguidetemplate is a screencast player (browser window, terminal window, chapters, key badges, cards) driven by one edit list; thecanvastemplate is a hand-drawn 2D engine (paper, letterpress type, ink strokes, a thread, cards, a pencil) with its own offline mix; thedomtemplate is the bare contract in 80 lines. - A recorder for the real thing.
Termrecords a shell through a pty withscript-style timing, so the player replays the actual bytes through xterm.js;Browserrecords a CDP screencast with the mouse path, the clicks, the keys and the URLs, and can serve a local folder or a local instance of your site under its real domain. - Sound from the timeline.
motigen eventsasks the page where the voice lines, clicks and key presses fall;motigen vomakes the narration (one ElevenLabs call with timestamps, split per line, or your own recordings);motigen mixlays everything out, ducks the music under the voice and masters to β14 LUFS / β1 dBTP;motigen srtwrites the subtitles. - Deterministic, parallel rendering. Every frame depends on
talone, so-j 4renders four slices at once and joins them losslessly, and the preview scrubs to any moment instantly. - Made for agents.
skill/SKILL.mdtells a coding agent how to take a script to a finished video with these commands; the whole project is text it can read and change.
Node 22 or newer and ffmpeg in your PATH. Playwright downloads its Chromium once; --channel chrome uses an
installed Chrome instead.
npm i -g motigenjs
npx playwright install chromium
The npm package is motigenjs; the command it installs is motigen. As a project dependency, npx motigen β¦
works the same way.
The terminal recorder uses node-pty (an optional dependency with prebuilt binaries for Windows, macOS and
Linux). Without it, record in a container: backend: 'docker'.
| Command | What it does |
|---|---|
motigen init <scenes|guide|canvas|dom> <dir> |
A new project from a template. |
motigen preview [--port 4310] [--open] |
A player over the project: scrub, play with audio/mix.wav , switch formats, render and export events from buttons. |
motigen frames -t 1,2.5,10 |
Stills into shots/ (--png ,--every 5 ,--element '#terminal' with a transparent background,--scale 2 ). |
motigen render |
The video to out/<name>.mp4 :-j N pages in parallel (default: half the cores, at most 4),--range 10-20 ,--audio file.wav or the project'saudio/mix.wav ,--crf ,--preset . |
motigen stability -t 3,10 |
Renders consecutive frames at those moments and reports what changed between them ( --every 2 ,--frames 3 ,--still to fail on any change,--replay to also render each moment again and fail when it differs). |
motigen events |
The page's events() intoaudio/events.json : voice cues, clicks, keys, Enter presses, effects. |
motigen record [take.mjs] |
Runs a take script; it imports { Term, Browser, sleep } frommotigenjs/record . |
motigen vo [lines.txt] |
Narration: one ElevenLabs call for the whole script, split per line into audio/vo/ withvo.json .vo voices lists your voices and their ids,vo split uses a saved response,vo import your own recordings,vo check flags breathy or garbled lines. |
motigen mix |
audio/mix.wav fromevents.json ,vo/ ,sfx/ andbed.* ; or the canvas kit's own mix when"mix": {"engine": "page"} . |
motigen srt |
Subtitles from the voice cues, with the written forms from "spellings" . |
motigen build |
events βmix βrender (every format) βsrt . |
motigen skill [dir] |
Installs skill/SKILL.md into.claude/skills/motigen/ , so a coding agent in that folder knows the workflow. |
Common options: -C dir (the project), -p page, --fmt name, --size WxH, --query "fmt=v", --channel chrome,
--no-gpu, --ffmpeg path, --timeout s. motigen help lists everything.
window.__film = {
ready: true, // fonts and assets are loaded
dur: 38, // seconds
fps: 30, // optional
renderAt(t) {}, // draw the frame at t seconds; sync or async; a pure function of t
events() {}, // optional: { dur, vo: [{id, t}], clicks: [t], keys: [t], enters: [t], sfx: [{id, t, db}] }
canvas, // optional: an HTMLCanvasElement to read frames from, at its own size
};
A frame must depend on t alone: no Date.now(), no CSS animations or transitions, no random numbers without a
seed, nothing that keeps running between calls. Then any frame can be rendered at any time in any order, which is
what parallel rendering and scrubbing rely on.
my-guide/
motigen.json page, fps, size, formats, audio folder, out, vo / mix / spellings settings
film.html the page; the guide template adds edit.js, theme.css, brand.svg, take.mjs, site/
take/ recordings: take/<clip>/ (frames + clip.json), take/term.out + term.tm
audio/ lines.txt β vo/ (L01.wavβ¦ + vo.json); bed.wav; sfx/; events.json, mix.wav (generated)
out/ renders and subtitles
{ "page": "film.html", "fps": 30, "size": [1920, 1080], "out": "out/my-film.mp4",
"formats": { "h": { "query": "fmt=h" }, "v": { "size": [1080, 1920], "query": "fmt=v" } },
"vo": { "voice": "<elevenlabs voice id>", "model": "eleven_v4", "seed": 7042 },
"mix": { "voiceDb": -3, "duckDb": -9, "target": { "lufs": -14, "dbtp": -1 } },
"spellings": [["Acme Cloud dot com", "acmecloud.com"], ["Pie", "Pi"]] }
scenes β a film from a list of scenes, for launch videos and explainers:
export default {
theme: 'dark', brand: { text: 'Acme Cloud' },
scenes: [
{ type: 'title', dur: 4.5, vo: 'L01', kicker: 'Introducing', title: 'Ship faster. Sleep better.', sub: 'One command, and it stays up.' },
{ type: 'terminal', dur: 6, vo: 'L02', lines: [{ cmd: 'acme deploy' }, { out: 'β Live at https://shop.acme.dev', ok: true, delay: 1.2 }] },
{ type: 'stat', dur: 4, vo: 'L03', stats: [{ value: 12, suffix: 's', label: 'from push to live' }, { value: 99.99, decimals: 2, suffix: '%', label: 'uptime' }] },
{ type: 'image', dur: 5, vo: 'L04', src: 'assets/app.png', url: 'app.acme.dev', zoom: { to: 1.08, x: 62, y: 45 }, callout: { x: 71, y: 34, label: 'Live traffic', at: 2 } },
{ type: 'end', dur: 4, vo: 'L05', wordmark: 'Acme Cloud', url: 'acme.dev', cta: 'Start free' },
],
};
Fourteen scene kinds (title, text, list, stat, chart, table, phone, grid, image, terminal, code, quote, split,
end), eight transitions that vary on their own, three themes, both formats from one list, and the voice, the
transition sounds and the typed keys go into the mix. docs/scenes.md has every field and the
rules that keep a film from turning into a slideshow; examples/scenes-gallery shows every kind once, and
examples/motigen-preview is the clip at the top of this page.
guide β a screencast. take.mjs records the demo site in site/ (served inside the recorder as
https://demo.local) and a shell on your machine; edit.js cuts them:
export default {
cols: 112, rows: 30, take: 'take', term: 'take/term',
shots: [
{ card: intro, dur: 4, vo: [['L01', -1, 0.5]] },
{ browser: 'site', segs: [[0, 9.5]], chapter: ['Step 1', 'Connect'], zoom: [[0, 1, 800, 450], [1.4, 1.35, 700, 420]] },
{ term: true, segs: [[0, 'edit.js|+1.2'], [null, 'node --version|+1.6']], keys: [['node --version|-0.2', 1.4, 'Enter', 'run it']] },
{ card: outro, dur: 4 },
],
};
Segments play source seconds back to back and can be stretched or squeezed; terminal bounds can be text anchors
('Installed|+0.8' = the moment that text appears, plus 0.8 s); the window zooms along keyframes; cards, chapters,
key badges and notes are overlays. docs/guide.md has the whole format and the recorder API.
dom β the contract and nothing else: a title, a bar and three typed lines in one HTML file. Start here for a film in plain HTML and CSS.
canvas β a 12-second film on the hand-drawn engine from a real promo series: paper, a letterpress title, an
ink thread with a needle, a rule card with a highlighter, tally marks, a pencil that underlines, a stamped name.
Both formats come from one LAYOUTS table. docs/canvas.md lists the kit.
audio/lines.txt is the script, one line per cue. motigen vo sends it to ElevenLabs in one call with character
timestamps and cuts the take at the quietest point between
lines. The key: create one at elevenlabs.io (profile β API keys) and put ELEVENLABS_API_KEY=sk_β¦ into a file
named .env in the project folder (every template ships .env.example; .env is git-ignored), or export it in
the shell. The voice: motigen vo voices lists the voices of the account with their ids; put one into
motigen.json under "vo": { "voice": "<id>" }. Then it cuts the take at the quietest point between
lines, so s sound natural and every line is its own file. Recorded your own? motigen vo import writes
vo.json for the files in audio/vo/. Then motigen mix places each line where the edit put its cue, adds the
click / key / Enter sounds for what the recorder logged (synthesised when audio/sfx/ is empty), loops the music
bed with a crossfade, ducks it under the voice and masters with ffmpeg's two-pass loudnorm. The levels, the
ducking and the target live under "mix" in motigen.json. docs/audio.md.
A still shot has to repeat the same pixels frame after frame; the smallest shimmer on text reads as jitter once it is encoded. motigen is built so that it does not happen, and ships the check:
-
Every frame is a pure function of
t: nothing on screen may depend on the clock, on CSS animations or on unseeded randomness. -
The guide player snaps its camera to whole pixels and a fixed scale grid, so a slow pan moves in clean steps and a hold repeats one transform; the canvas kit keeps hand-drawn strokes on one seed (no "line boil"); the templates settle every animated value to an exact number.
-
The templates use no
will-change: it makes the browser keep many composited layers, and then the screenshot of a freshly shown layer can lag, so a frame would depend on what was rendered before it (found the hard way: the last line of a quote went missing in the first render of its scene, and only there). -
The encoder puts keyframes every 2 s and nowhere else (
--gop), so fine texture does not pulse on holds. -
motigen stability -t 3,10,20renders consecutive frames at those moments and reports the share of pixels that changed, with a box around the change and a-diff.pngthat shows it brightened;--stillfails when a moment is not perfectly still. A cursor, a caret or a spinner show up as small boxes; jitter shows up as a small change spread across text that should not move. -
--replayrenders every moment a second time, last to first, and fails when a frame comes out different: the proof that a frame is a pure function oft, for your own pages too. -
Remotion : React, a bundler and a licence with limits for companies. motigen takes any page, needs no build step, and is MIT.
-
Motion Canvas : its own editor and generator syntax. motigen is a CLI over an ordinary HTML page.
-
VHS, asciinema : the terminal only. motigen puts a real terminal next to a real browser, cuts them with one edit list, and adds narration, sound and subtitles from the same timeline.
-
Screen recorders : a GUI and one take. A motigen project is text in git; change one line and render again.
The format and the tools were extracted from a pipeline that produced a real series of product guides and promo films. Every port was checked against that pipeline's own output: the guide player gives the same events and the same frames (SSIM 0.99 against the earlier render), the mix the same loudness and the same waveform within the random jitter of the key clicks, the subtitles the same file byte for byte, the canvas films the same frames.
A release is a version bump and a tag: npm version patch (or minor), git push --follow-tags. The
publish workflow then publishes to npm through trusted publishing with provenance, so the package page links
each version to the commit and the run that built it.
git clone https://github.com/crocone/motigen && cd motigen
npm i && npx playwright install chromium
npm test
node bin/motigen.js build -C examples/hello-dom
cd examples/hello-guide && node ../../bin/motigen.js record take.mjs && node ../../bin/motigen.js build
MIT.