endlessconflict/sourceframe

What does sourceframe do?

A method for making a video the way you would build a system: requirements first, a ledger of what is true, a layout contract, small verified steps, measurement before opinion. The product is a short silent-first video (15 to 90 s) that explains one mechanism by following one focal element through it. The name is the rule: every frame traces back to a source.

This skill was distilled from a real build (a 77 s explainer on how coreboot runs C code before DRAM exists, with a 4,096-cell cache grid, a 3D flash chip and DRAM training) and re-proven on a second, unrelated subject (examples/merkle-proof, a Merkle inclusion proof whose every hash is computed by the build). Paths below are relative to this skill's folder.

When to use it, when not to

Use it for: how-it-works videos, protocol or algorithm walkthroughs, system architecture tours, "what happens when" sequences, post-mortem replays. It shines when the subject has a mechanism with a state that changes (bits flip, a pointer moves, a hash propagates).

Do not use it for: talking-head or footage edits, product ads, pure motion branding, anything where the content is opinion rather than mechanism. For those use a plain motion skill. If the user only wants a static carousel, use a carousel skill.

The seven principles

1. Ledger before pixels. Write FACTS.md (claim, evidence, status) before the first scene. Status V read from a source this session, C computed by the build, S schematic and labelled so on screen, H memory (re-check), N needs source (blocks shipping). Never invent a number, a symbol, a path, a version. Prefer C: let the build compute what the video shows.
2. One focal element. One thing per frame is the eye's anchor: it gets the single "focus" colour, it is always the current step, and it never competes with a second one. Everything else is quieter by construction.
3. Colour is meaning. Palette roles (data, focus, ok, bad, ink) are semantic and fixed for the whole video. Never pick a hue for looks.
4. Determinism. A frame is a pure function of its frame number. No wall-clock time, no Math.random, no CSS transitions, no useFrame. Seeded hash(n) for anything pseudo-random. This is what makes parallel rendering, stills and later sound sync possible.
5. The picture is the instrument. Animation exists to show a state change. Every motion answers "what does this show?". Banned: the same fade-up on every block, bounce or elastic easing, looping decoration, glow for its own sake.
6. Measure first, look second. Numbers are cheap and exact; opinions are expensive. Typecheck, ledger lint, probe the container, measure pixels where you can, then look at one contact sheet per round.
7. Stop rules. Max three review rounds per scene set, max three fixes per round. Say what is left and why you stopped. Honesty beats polish: label what was not verified.

The ten phases

Each phase has a deliverable and a gate. Do not skip a gate to save time: the expensive mistakes are all upstream.

#	phase	deliverable	gate
0	intake	one-line fit check, platform, duration, silent-first or with sound	ask only what blocks work (one question), otherwise decide and state
1	brief	BRIEF.md sections 1 to 3	takeaway fits one sentence; focal element nameable in one phrase
2	evidence	FACTS.md filled for every planned claim; computation scripts for C rows	tools/ledger_lint.py passes; no N row
3	direction	kill-list, idea sentence, signature moment, theme.ts tokens	competitor test passed (see references/02-direction.md)
4	storyboard	table: scene, seconds, what moves, caption, ledger row; timeline.json	caption budget met; total length justified
5	foundations	scaffolded project, fonts, theme, shell, camera, preview opens	one still renders; WebGL works (see pitfalls: path length)
6	build	scenes, hardest and most central first	per scene: stills, one contact sheet, at most 3 fixes
7	assets	3D and icon assets, procedural unless a licensed source is needed	every logo or mark used unaltered and credited
8	verify	full render, encode, probe, frame sheet, ledger lint	all automatic checks green; sheet reviewed; flaws listed
9	deliver	mp4, cover frame, caption text, alt text, credits, "not verified" list	the user can post it without asking what is true

Phase 0: intake

State in one line what you will make: Reading this as: <medium> for <reader>, <focal element>, <duration>. Ask a question only if the answer changes what you build (platform and aspect ratio; whether sound will follow; which sources are authoritative). Default canvas 1080 x 1350 (4:5) at 30 fps for social feeds; see references/08-adapting.md for 16:9, 1:1, 9:16.

Phase 1: brief

Copy templates/starter/BRIEF.md. Fill intent (medium, reader, takeaway, focal element, mood). The takeaway must be one sentence a viewer could repeat. If you cannot name the focal element in one phrase, you do not have a video yet: decide and say so, or ask one question.

Phase 2: evidence (the part most videos skip)

1. Identify the primary sources (spec, RFC, source tree, datasheet, man page, measured output). Read the exact lines you will quote. Record file:line or URL plus section.
2. For every number, ask: can the build compute it? If yes, write a script that computes it, cross-checks it a second way, aborts on disagreement, and writes a generated module the scenes import (examples/merkle-proof/scripts/compute.mjs is the model: RFC recursion versus iterative build must agree or nothing is written).
3. Anything that cannot be sourced becomes either a labelled schematic (S, and the word "schematic" appears on screen) or is cut. Visible [NEEDS SOURCE] is allowed in drafts, never in the render.
4. Illustrative data is legal when it is honest: invented example items are shown as plain example text and logged S.
5. Run python tools/ledger_lint.py as a tripwire: every digit in a scene string must appear in the ledger.

Full format and examples: references/01-brief-and-ledger.md.

Phase 3: direction

Write the idea sentence: "On this video, [something that belongs to the subject] becomes [the device]." Run the competitor test: if a generic video on the topic could use the same sentence, it is a category idea, not an idea. Pick one signature moment (the only loud move) and the kill-list (the three most obvious visualisations, now forbidden: typically a stack of rectangles with arrows, a screenshot, a centred object on a gradient). Set the dials: variance, motion intensity, density, each 1 to 10, from the subject (a security explainer for engineers is calm and dense; a launch teaser is neither). Details and the choreography rules in references/02-direction.md.

Phase 4: storyboard and timing

One table: scene, seconds, what moves, caption, ledger row. Budgets that held up in practice:

• caption at most 2 lines and 14 words, minimum 48 px on a 1080 canvas (a phone shows the canvas at about 0.36x, so 48 px is about 17 pt); labels at least 26 px;
• a caption stays at least words / 2.6 + 0.8 seconds, never replaced mid-sentence;
• one idea per scene; a scene longer than 12 s needs internal beats (steps) with their own caption;
• the whole piece is one idea told once: cut any scene whose removal does not lose a ledger row.

Write scene order and lengths in timeline.json only. Remotion, the verification scripts and the cuelab sound pipeline all read that one file.

Phase 5: foundations

node scripts/scaffold.mjs <target-dir> --install

Then: edit src/theme.ts (palette, canvas), drop fonts in public/fonts, set BRAND in src/ui/Chrome.tsx, edit timeline.json. Keep the project path short (see pitfalls: ANGLE needs a short path on Windows). Render one still of a 3D scene before writing more: if WebGL fails now, it will fail later.

Phase 6: build, scene by scene

Order: the signature scene first (the hard 3D or grid), then the scenes that depend on it, then connective scenes. Per scene:

1. write the scene against the layout contract (references/03-layout-contract.md) using Shell, tokens and the anim helpers;
2. bash tools/shots.sh <Scene> out/<scene> <frames...>: pick frames at the start, mid-motion and rest of every beat, one contact sheet;
3. read the sheet once, answer: first/second/third thing seen? focal element where intended? anything generic? what to cut? Fix at most three things; re-shoot only changed frames;
4. when the scene is stable, move on. Do not polish scene 2 while scene 6 is unbuilt.

Animation patterns that carry the work (masked line reveals, staggered rows, hash scramble, bit flips, projected labels on 3D, instanced grids) are in references/04-remotion-patterns.md; 3D recipes in references/05-three-assets.md.

Phase 7: assets

Prefer procedural assets: they are deterministic, tiny, themeable and carry no licence risk. Foil boxes, extruded logos, instanced cell grids and point fields cover most explainers. Use AI-generated meshes only when an organic or branded object is essential and the service's licence and cost are acceptable to the user; never hide that an asset was generated. Real logos and marks: use the project's own file unaltered (recolouring a single-colour mark is usually fine; redrawing is not), check the licence, credit on screen or in the caption.

Phase 8: verification

Automatic, in this order (cheap to expensive):

npx tsc --noEmit                 # types
python tools/ledger_lint.py      # numbers vs ledger
bash tools/shots.sh Main out/m <frames>   # contact sheet, look once
npm run render && npm run encode          # raw render, then limited-range yuv420p h264
                                          # encode.sh ends by running tools/probe.py

tools/probe.py checks codec, yuv420p (not yuvj420p), size, fps, duration against timeline.json, limited range, no black frames, fast-start atom. Then look at a sheet of the final mp4 (frames every 4 s, extracted with ffmpeg) and at one frame at full size for text sharpness. If a design critic is available (for example the creator-critic skill), run it on a folder of stills: treat blockers as blockers and majors as questions. Full checklist: references/06-verification.md.

Phase 9: delivery

Deliver: out/video.mp4, a cover frame (a rest frame where the title and the focal element both read), caption draft (plain, no hype, source named), alt text (one sentence on what the video shows), credits (assets, logos, licences), and a "not verified" list (anything in ledger status H or S, anything the build cannot prove, anything you could not review by eye). Do not post anything yourself.

Choosing between options (decision tables)

question	choose	because
2D or 3D for an element	3D only when depth or physical form is the point (a chip, a stack, a field of a million items); otherwise 2D	3D costs render time and legibility; use it where it explains
camera	orthographic, manual = true, fixed per scene	ortho keeps labels projectable and measurements honest
labels on 3D	HTML or SVG projected with project()	text stays crisp and styled
a lot of repeated cells	InstancedMesh (thousands) or Points (a million)	draw calls
fonts	two families at most, OFL or licensed, bundled in public/fonts	determinism, no network at render
text on slab or fill	dark text on bright fills, never white on bright	contrast
sound	design it after the picture is locked, from timeline.json	see the cuelab skill

Failure modes this method exists to prevent

The beautiful but wrong video (no ledger); the correct but unreadable video (no layout contract); the generic video (no idea sentence, no kill-list); the video that looks fine in the studio and breaks in the render (non-determinism); the video that looks fine at 100% and is mush on a phone (type floors, thumbnail test); the video that cannot be scored (no single timeline); the video whose claims nobody can check (no delivery honesty). Concrete bugs found while building the first two videos, each with symptom, cause and fix, are in references/07-pitfalls.md; read it before debugging anything that looks like magic.

Files in this skill

path	what
references/01-brief-and-ledger.md	brief template, ledger format, how to compute and cross-check facts
references/02-direction.md	idea sentence, kill-list, dials, choreography rules, motion tokens
references/03-layout-contract.md	canvas, safe areas, type floors and the phone-scale arithmetic
references/04-remotion-patterns.md	tested animation patterns with code
references/05-three-assets.md	three.js in Remotion: camera, foil shader, edges, instancing, points, extrusion, label projection
references/06-verification.md	the full verification ladder, contact-sheet protocol, encode and probe
references/07-pitfalls.md	every real bug met, with fixes
references/08-adapting.md	other aspect ratios, themes, languages, no-3D variant, handoff to sound
templates/starter/	a working Remotion project: theme, helpers, UI chrome, three.js kit, tools, BRIEF and FACTS templates
scripts/scaffold.mjs	copies the starter into a new project and installs
../../examples/merkle-proof/	a complete 36 s example with computed facts, ledger, render and probe

Licence note you must pass on

Remotion is not MIT. It is free for individuals and for teams of up to three people; companies above that need a paid licence (the Remotion CLI prints the notice, see remotion.pro/license). Tell the user once, early, when the project may be commercial. three.js, React and the bundled fonts (SIL OFL) are permissive.