For agents and developers. Team members don't need this page: their agent reads it and does these steps. The README is the people's guide.
| Path | What it is |
|---|---|
motion/engine/ |
The renderer and its command line (cli.ts): timeline, camera, cursor, stills, lint, preview, render, and the text legibility check a film runs while it builds (legibility.ts). motion/README.md explains how it works. |
motion/kit/ |
Reusable screen parts (a browser window, Roam's shell, dialogs, menus, the canvas), the decision films' slide parts (decision.ts), and motion helpers. |
motion/films/one-question/shared/ |
The One Question series layer: its world (graph, node types and colors, the story's nodes), headlines, end card, the template-lab look, and the Discourse Graphs and ZoteroRoam UI parts. |
motion/films/one-question/oqNN-*/ |
One folder per episode, six files each (below). |
motion/films/decision-*/ |
Decision films: an engineering decision laid out as full-frame slides (below). |
motion/films/_kit-sample, motion/films/smoke |
A minimal example film and the engine's self-test. |
tutorial-series/PLAN.md |
The series plan: the team's input, the episode list, the facts the films depend on, and the rules every episode follows. |
tutorial-series/evidence/ |
Real screenshots the UI is drawn from. |
examples/ |
The films made so far (in the examples release) and the prompts behind them. |
.agents/skills/make-film/ |
The order of work for every film (linked from .claude/skills/). |
recorder/chapters.ts |
A small helper the engine uses for chapter markers. |
An episode folder:
| File | What it holds |
|---|---|
data.ts |
Every word on screen: headlines, note text, labels. |
timeline.ts |
How long each beat runs. |
world.ts |
Builds the screens from the shared parts. |
scenes.ts |
The choreography: clicks, typing, camera moves, when each headline shows. |
film.ts, film.css |
Entry point and the episode's own styles. |
- Clone this repo next to
discourse-graph(DiscourseGraphs/discourse-graph), in the same parent folder. The engine borrowstsx,playwrightandesbuildfromdiscourse-graph/apps/roamby a relative path, or fromMOTION_DEPS_ROOTif set.parent/ discourse-graph/ dg-films/ - In
discourse-graph:pnpm install. - In
discourse-graph/apps/roam:npx playwright install chromium. - Install
ffmpeg(brew install ffmpegon a Mac). - Check: from
discourse-graph/apps/roam,The sheet lands inM=../../../dg-films/motion/engine/cli.ts npx tsc -p ../../../dg-films/motion/tsconfig.json # prints nothing npx tsx $M still one-question/oq01-highlight-v2 --at 1,20 --sheet
dg-films/output/motion/oq01-highlight-v2/stills/. Show it to the person as proof the setup works.
Reading the template graph needs the discourse-graph MCP server and the Roam desktop app running. Pass the graph's name explicitly.
Run from discourse-graph/apps/roam, with M=../../../dg-films/motion/engine/cli.ts:
| Command | What it does |
|---|---|
npx tsx $M info <film> |
The beat sheet, no render. |
npx tsx $M still <film> --beats 2 --cues --sheet --columns 4 |
Frames from every beat on contact sheets. |
npx tsx $M still <film> --at 1,5.5 --sheet |
Frames at the seconds you pick. |
npx tsx $M lint <film> |
Checks every camera move; must be clean. |
npx tsx $M preview <film> |
The whole film at 720p in seconds. |
npx tsx $M render <film> --crf 8 --preset slow --only 1080p |
The final 1080p60 mp4. |
<film> is a folder under motion/films, such as one-question/oq03-papers. Output goes to output/motion/<film>/ (not committed). Renders open real, visible Chromium windows for a minute or so; tell the person to leave them alone. --headless is refused on purpose. Films are silent; the engine's narration commands need tools that aren't in this repo.
A decision film lays out an engineering decision for the people who make it: one question per beat, what is on record, a status stamp, and the tickets it leans on. motion/films/decision-* are the ones made so far; start a new one from the closest of them.
- Parts. Build the slides from the kit's decision parts (
motion/kit/decision.ts): status stamps, the ticket line and ID chips, code and tag chips, dated pills, boxes, arrows and tokens, numbered questions, recap rows and ask cards.motion/kit/README.mdlists them. A film with its own look passes a class asclsand styles that class in itsfilm.css, asdecision-upsert-routedoes. - Legibility check. Call
checkLegibilityfrommotion/engine/legibility.tsat each beat's settled moment: after its last entrance, before it leaves. The build then stops on text that is too small, outside the frame, out of its card, or over other text. - The 720p preview is the default deliverable. Run
preview, send the person the mp4, and stop there. Render the 1080p master or the copy under 20 MB only when they ask. - The person reviews the preview before any re-render. Wait for their notes, make every change, then render once. Send the new preview to a new folder (
--out ../../../dg-films/output/motion/<film>-v2) so the one they reviewed stays.
Slack and some other places stop at 20 MB. Make a second copy with a two-pass encode, and lower the bitrate if it still lands over:
ffmpeg -i in.mp4 -map 0:v -c:v libx264 -preset slow -b:v 3400k -pass 1 -an -f mp4 /dev/null
ffmpeg -i in.mp4 -map 0:v -map_chapters 0 -c:v libx264 -preset slow -b:v 3400k -pass 2 -pix_fmt yuv420p -movflags +faststart -an out-under20mb.mp4