code-motion

---
name: code-motion
description: >-
  Makes a NEW video file (MP4) from code alone — motion graphics, a reel, an intro, an animated title, an animated logo,
  a product demo, an interface animation as a video, a title card — with no After Effects, no video models and no credits.
  Use it whenever the deliverable is a RENDERED VIDEO: "build me an animation", "make one like this" next to a recording or
  a reference, "replicate this animation", "recreate this ad 1:1", "animated words", "screens that type themselves",
  "flying cards", "a luxury title", "animate this", "motion graphics" — even without the word "code".
  **The core work is faithful replication of a reference video, including the small details** ("replicate", "make one
  like this", "1:1"). Inspiration and original creation — only when explicitly asked. The engine (bundled in this skill):
  2D canvas, WebGL, real 3D with perspective and depth of field, motion blur, audio-reactive data, images, green-screen
  keying, and mechanical gates with selftests.
  Not for: live animation inside a website or app (hover, transitions — write that in the site's own code) · editing
  existing footage · generating video with an AI model · working inside After Effects.
---

# code-motion — film from code

> **What it is:** one function, `draw(ctx, t)`, paints the picture at a given moment. Headless Chrome calls it for every
> frame, and ffmpeg encodes an MP4. There are no layers and no keyframes — there is the text of a program.

| read | when |
|---|---|
| **`references/REPLICATION.md`** | **in every replication — the main workflow** (compare · gap log · watching it through) |
| **`references/SOURCES.md`** | what was inside sources replicated before — what to look for in a new source (not a look to copy) |
| `references/DIRECTION.md` | a direction doc + animatic — before building |
| `references/QUALITY.md` | artistic judgement by type of film — in every review round |
| `references/GOTCHAS.md` | **before every build** — engine traps |
| `references/MEASURE.md` | when there is a reference — how to read the source |
| `references/ENGINE.md` | the module API · the renderer · sound · combining AI video |
| `references/UI-EXPLAINER.md` | an interface explainer video |

---

## 0 · Setup — once per project

The engine ships inside this skill as a template, at `<this skill's folder>/engine`. Work happens in a copy inside the user's
project, so scenes, renders and direction docs live with their project:

```bash
SKILL=<this skill's base directory>          # shown when the skill loads
[ -d motion ] || cp -R "$SKILL/engine" motion   # first time in this project only
cd motion && npm install && node doctor.mjs
```

From here on: **`$E`** = that `motion/` folder (run engine commands inside it) · **`$S`** = `$SKILL/scripts` (the measuring
tools and gates). `node doctor.mjs` must end with "Environment OK" — every line marked ✗ prints the exact command that fixes it
(Chrome, ffmpeg, Python with numpy + Pillow). Chrome is found automatically on macOS, Windows and Linux; `CHROME_PATH` overrides.
If the user already has a `motion/` folder from an earlier session, use it — do not copy over it.

Check that everything works before the first real scene:
```bash
node gate.mjs --selftest        # 5 engine gates, each proven to catch its own bug
node render.mjs example         # → out/example.mp4 (5 seconds)
```

---

## 1 · When here, when not

| the request | where |
|---|---|
| a new video: reel, intro, title, logo, demo, an interface explainer as a video | **here** |
| "replicate this" / "make one like this" next to a video | **here** — the replication or inspiration path (§2) |
| "animate the button/transition on the site" — animation that runs in the user's browser | **not here.** CSS/JS in the site itself |
| "edit my clip", cutting, captions on footage | **not here.** a video editor |
| filmed/realistic video generated by a model | **not here.** a video model |
| layers · keyframes · `.aep` · ExtendScript | **not here.** After Effects |

Not clear what the deliverable is (a video file? a live component? an edit?) ⇒ **ask before choosing a tool.**

---

## 2 · Brief and path — before the first line of code

These decisions change the solution at its root. Anything not stated — **ask, don't invent**:

| | question |
|---|---|
| message | what should the viewer understand / feel at the end? |
| audience and place | for whom, and where it will run (reel · story · site · presentation) |
| aspect ratio · length | 9:16 · 1:1 · 16:9 · 4:5 — how many seconds |
| on-screen language | **set by this brief**, not by earlier films |
| sound | is there any? music / derived effects / deliberate silence? must it work without sound? |
| reference and fidelity | none · inspiration · exact replication — and what exactly must be kept |
| export | rate · resolution · format · transparency? |
| success | what will count as "that's it" — and who approves |

### The paths — replication is the core work

| path | when | the yardstick |
|---|---|---|
| **faithful replication** ⭐ | the default — "replicate", "make one like this", "1:1" | **this source**, including the small details. Don't improve and don't interpret (§3) |
| inspired by a reference | only when explicitly asked | what was chosen to keep from the source; the rest — a decision |
| original creation | only when explicitly asked | directions to choose from first (§3′) |

In a replication the brief is short: **which source · what crop/frame · what cannot be drawn in code (assets) · sound yes/no.**
Everything else is measured from the source.

### Every number is marked with its origin

In code and in the spec, for every important value — a short comment:

- **`measured`** — from where and how (`#295bfb — sampled at 9 points, f120`). And a way to verify it again.
- **`estimated`** — a partial measurement or by eye. No more digits than were measured (not `0.5104` from an estimate).
- **`decision`** — a design choice. Entirely legitimate in original work.

In an exact replication, `estimated` is a debt to close before delivery. In original work there is no "source" to measure —
**false precision (a long number with no measurement) is worse than an honest "decision".**

---

## 3 · Replication — the main path (details: `references/REPLICATION.md`)

0. `node doctor.mjs` — once per session.
1. **What is in the file:** the real frame (embedded? a frame that is part of the film?) · the animation rate (duplicated frames) ·
   audio · assets that cannot be drawn (ask the user for them, or declare a deviation — never replace them silently).
2. **Watch the whole source and break it into shots** at the source rate: for each shot — what it does in one sentence, what moves,
   and a **list of small details** (font · weight · tracking · HEX · per-frame easing · type of blur · flashes · cursor).
3. **Build shot by shot. After every shot:** `sbs.py REF OURS --ref-from A --ours-from B --duration D` ⇒ `sbs.mp4` + `frames.png` ⇒
   every difference into **the gap log** `direction/NAME.gaps.md`. Do not move on with an open gap that can be closed.
   **Show the first shot to the user** before building the rest. (In an unattended run with no one to ask: write in the gap
   log that the first shot was not reviewed, and carry on.)
4. **Full assembly:** `sbs.py` over the whole length — **watch it through from start to end** · `replicate_gate` (+`--roi`) as a
   sanity check · `deliver_gate`.
5. **To the user:** `sbs.mp4` + the gap log (open · declared deviations) + what was not checked (real-time viewing · listening).

⛔ **The source is the yardstick.** "Better than the source" = a gap. ⛔ **A previous replication is not a source** — even if its
style is loved, its details were not confirmed as accurate. Measure in the current source.

## 3′ · Inspired / original — **only when the user explicitly asks**

1. **Brief** (§2) ⇒ the type of film (QUALITY.md §2). **Original ⇒ first 3–4 really different directions** (DIRECTION.md §Directions)
   **and wait for a choice.**
2. **A direction doc** + **an animatic** (`node tools/animatic.mjs direction/SCENE.md`) — weak ⇒ change the idea, don't add polish.
3. **The scene** (§4) · a new version = a new file · **render** · **a review round** (`review.py` + QUALITY.md) until no weakness is
   open · **the delivery threshold** (§6).
4. **The user's feedback** decides. **Approval = the user watching it through with sound**, not gates.

**Measuring tools for replication (steps 1–2):**
```bash
bash $S/sheet.sh REF.mp4 1 6 4 sheet.png           # overview — not evidence of pacing or freezes
python3 $S/measure.py REF.mp4 --out spec           # segments·palette·motion, at the source rate
python3 $S/refmeasure.py --selftest                # assets·reveal·scale: MEASURE.md
```
`measure.py` without `--fps` samples at the source rate (up to 30) and keeps segments down to 0.1s; `--fps 6` = a quick overview map
only, and the report says so. A reference recorded off a screen ⇒ `--crop W:H:X:Y`.
`measure.py`'s circle fit is only for sources with a bright arc or ring — ignore that section for typographic pieces.
Speech in the reference? Transcribe it — but a transcript is no substitute for watching.
**Frame numbers:** `sbs.py`, `perframe.py` and the gap log count frames **from 0**. ffmpeg image sequences count from 1 unless you
pass `-start_number 0` — use it, or every frame reference will be off by one.

**Don't skip "looking".** Mirror writing, overflowing text, cards floating in front of the phone — all were caught by looking, not by
reading code.

---

## 4 · The scene contract

Scenes live in `$E/scenes/NAME.js`. Copy `scenes/example.js` to start. **In a replication, `width`, `height`, `fps` and
`duration` come from the source** (`ffprobe`) — the values below are just an example.

```js
import { resetFrame } from './_lib.js';
import { applyPost } from './_post.js';

export const SCENE = {
  name: 'my-scene',
  width: 1080, height: 1920, fps: 30, duration: 8.0,
  audio: 'audio/track.json',         // optional — analysis data for drawing (parameter A)
  soundtrack: 'audio/my-scene.wav',  // optional — a soundtrack the renderer muxes
  events: { hits: [/* {t, ...} */] },// optional — the sound event timeline → out/SCENE.events.json
  images: { hero: 'assets/x.jpg' },  // optional — parameter IMG
  fonts: [{ family: 'X', src: 'assets/fonts/x.ttf' }],
  samples: 4, shutter: 0.55,         // motion blur
  draw,
};

function draw(ctx, t, W, H, A, IMG) {
  resetFrame(ctx, W, H);             // mandatory — also resets ctx.direction
  // ... everything is derived from t
  applyPost(ctx, W, H, { bloom: 0.4, threshold: 0.64, chroma: 0.01 });
}
```

**Determinism — the exact contract:** resources and caches (images, fonts, shaders, `_post` caches) are initialised **before**
rendering; the host draws two warm-up frames that are thrown away. **From then on, the same `t` ⇒ the same pixels**, in any call
order. So: no `Date.now()`, no live `Math.random()` (only `rng(seed)`), and no state that accumulates between frames (a simulation ⇒
compute it from `t`). Without this there is no motion blur, no `--from`, and no determinism gate.

**Sound — one event timeline:** when sound is derived from the animation, the scene defines `events`, the sound script **reads**
`out/SCENE.events.json` (it does not duplicate constants), and `soundtrack` is muxed at render time. Order:
`render --no-audio --to 0.1 --out /tmp/x.mp4 --force` (writes the events) → the sound script → `render`.

**On-screen language:** from the brief. Right-to-left text (Hebrew, Arabic) ⇒ `layoutRTL` from `_words.js`, or `direction='rtl'` on
the texture (GOTCHAS 1).

**Fonts:** a font that is only installed on one machine renders differently elsewhere — put the font file in `assets/fonts/` and
declare it in `fonts`, if the user has the right to use it.

---

## 5 · The commands

```bash
cd $E
node doctor.mjs                               # environment check
node render.mjs SCENE                         # → out/SCENE.mp4 (+ soundtrack if defined)
node render.mjs SCENE --mblur 6 --shutter 0.6 # motion blur
node render.mjs SCENE --from 4 --to 9         # a section
node render.mjs SCENE --scale 2               # native 2× resolution (delivery)
node render.mjs SCENE --out x.mp4 --force     # an explicit existing destination — only with --force
node render.mjs SCENE --audio a.wav           # / --no-audio · --keep-frames · --tag709
node gate.mjs [--scene X] [--selftest]        # the engine gate
node tools/still.mjs SCENE 1.0,2.5 /tmp/f     # single frames → /tmp/f_1.0.png …
python3 $S/sbs.py REF.mp4 out/SCENE.mp4 [--ref-from A --ours-from B --duration D] [--ref-crop …]
                                              # ⭐ replication: preflight · sbs.mp4 · blink.mp4 · hires/ · gaps.json
python3 $S/align.py REF.mp4 out/SCENE.mp4 --ranges 0:62,63:100
                                              # a time shift or a visual model? (before fixing)
node tools/animatic.mjs direction/SCENE.md    # an animatic from the shot block
python3 $S/review.py out/SCENE.mp4 --direction direction/SCENE.md --prev out/OLD.mp4   # a review package
python3 $S/deliver_gate.py out/SCENE.mp4 --audio yes|no --hold A-B …                   # the delivery gate
python3 -m http.server 4320                   # then localhost:4320/player.html
```

**The player (`player.html`) is a scrubbing tool, not an approval.** It draws once per screen refresh (no motion-blur sub-samples).
When there is a `SCENE.soundtrack` it plays it, and **audio time is the clock**. How the film looks and sounds — only in the rendered
MP4, by watching and listening.

PNG frames are deleted after a successful encode; the renderer prints a disk estimate and stops if there is no room.

---

## 6 · The gates — and what each one does NOT say

| gate | on what | what PASS says | what PASS does **not** say |
|---|---|---|---|
| `node gate.mjs` | every scene | the engine: orientation · text direction · per-plane size (capability checks), and per scene: `draw(-t)` does not crash · determinism **at one point in time** | nothing about a whole film: overflowing text, pacing, composition, sound, encoding |
| `replicate_gate.py REF OUT` | replication | no deviation of six types: length · blanks · background (RGB) · freezes · cuts · coverage curve. Windows in seconds; samples at the source's own fps unless `--fps` is given | that the object is in place, that the typography matches, that the content inside a screen is right. ⇒ `--roi NAME=x0,y0,x1,y1` on every important element. ⚠️ G4 finds a cut as a sharp jump against its neighbourhood — a cut into or out of a near-empty frame can go undetected on both sides and still "pass". Check every cut in your shot table by eye |
| `deliver_gate.py OUT --audio yes\|no` | **the file to be delivered** | h264/yuv420p/constant rate · audio present, not silent, the right length · no undeclared freeze (`--hold`) · no black at the edges · HEX after encoding (`--hex`) | legibility, margins, pacing, message — it prints the watch-list |

**`--selftest` in all three** injects the bug the gate is meant to catch and checks that the **specific** gate failed (in the Python
gates — also that the stated reason is the right one), and the Python gates also run a clean control that must pass. That proves the
gate is **sensitive to the injected faults** — not that the film is ready. Run `gate.mjs` after any change to `_quad3d` / `_lib` / `_post`.

### The delivery threshold — before showing or sending

1. `node gate.mjs --scene SCENE` passes.
2. In a replication: `replicate_gate.py` passes, **including `--roi`** on the elements the brief said to keep.
3. `deliver_gate.py out/SCENE.mp4 --audio yes|no --duration … --size …` passes; every intended hold is declared with `--hold`;
   brand colours with `--hex`.
4. **Watching** — by the list the gate prints (`--checklist` writes it to a file): this file, from start to end, at phone size, at
   normal speed, with sound — legibility · margins · cuts · an ending that gives a moment · sync · without sound · **does the message
   come across in one viewing**.
5. Only then: show it, with what was checked and what was not.

A contact sheet is **not** step 4: it does not show a short freeze, unpleasant motion, or sync.

---

## 7 · What the engine knows

| capability | module |
|---|---|
| blurred layers + additive light | `_lib.js` |
| WebGL shaders · turbulent displace | `_gl.js` · `_shaders.js` |
| post pass: bloom·chromatic·dither | `_post.js` |
| quads in 3D · depth of field · camera | `_quad3d.js` |
| hinge kinematics (a panel on a panel's hinge) | `_hinge.js` |
| perspective-correct homography warp | `_homog.js` |
| volumetric tunnel (raymarching) | `_shaders3d.js` |
| word animation, including RTL | `_words.js` |
| squircles · luxury typography | `_icons.js` · `_lux.js` |
| interface springs (motion.dev registers) | `_spring.js` |
| real motion blur | `render.mjs --mblur N` |
| audio-reactive · soundtrack · event timeline | `audio/analyze.py` · `SCENE.soundtrack` · `SCENE.events` |
| green key → silhouette / colour-keeping | `$S/keyspin.py` · `$S/keycolor.py` |

API details: `references/ENGINE.md`. A starting scene: `scenes/example.js`.

---

## 8 · Traps — the three that recur most

1. **The canvas inherits `direction` from the page.** `resetFrame` pins `ltr`; without it `fillText` aligns right and the text is drawn
   out of its shape.
2. **`globalAlpha` is clamped at 1.** To strengthen a glow = paste the same layer twice.
3. **Canvas 2D knows no perspective** — only affine. For real perspective: `_quad3d.js` (or `_homog.js` for four measured corners).

And in replication — measurement traps come first (`MEASURE.md`): **§10** measure a property immune to the second effect (a low rms is not
evidence) · **§12** two hypotheses ⇒ render and measure both.

---

## 9 · Working with the user

- **Assets that cannot be drawn** (photos, illustrations, footage, a brand's font file): ask the user for them. Do not substitute
  something generic without saying so.
- **Show the first shot** of a replication before building the rest — it is the cheapest moment to discover a misread.
- **Report honestly:** what was checked, what was not (Claude cannot watch in real time or listen), and every open gap. Never present
  a green gate as approval.
- **Rights:** replicating a brand's ad is a study exercise. If the result will be published, the user decides what is allowed — credit
  the original, and do not use the brand's logo, audio or assets without permission.

• SKILL.md 18 KB
• engine/.gitignore 1 KB
• engine/doctor.mjs 4 KB
• engine/gate.mjs 5 KB
• engine/gates.html 9 KB
• engine/host.html 6 KB
• engine/package-lock.json 1 KB
• engine/package.json 1 KB
• engine/player.html 6 KB
• engine/render.mjs 13 KB
• engine/audio/analyze.py 2 KB
• engine/scenes/_gl.js 5 KB
• engine/scenes/_hinge.js 7 KB
• engine/scenes/_homog.js 3 KB
• engine/scenes/_icons.js 6 KB
• engine/scenes/_lib.js 5 KB
• engine/scenes/_lux.js 5 KB
• engine/scenes/_post.js 2 KB
• engine/scenes/_quad3d.js 7 KB
• engine/scenes/_shaders.js 5 KB
• engine/scenes/_shaders3d.js 3 KB
• engine/scenes/_spring.js 2 KB
• engine/scenes/_words.js 6 KB
• engine/scenes/example.js 5 KB
• engine/tools/_color.mjs 1 KB
• engine/tools/animatic.mjs 5 KB
• engine/tools/chrome.mjs 2 KB
• engine/tools/scene-eval.mjs 2 KB
• engine/tools/still.mjs 2 KB
• references/DIRECTION.md 4 KB
• references/ENGINE.md 15 KB
• references/GOTCHAS.md 16 KB
• references/MEASURE.md 15 KB
• references/QUALITY.md 6 KB
• references/REPLICATION.md 28 KB
• references/SOURCES.md 14 KB
• references/UI-EXPLAINER.md 3 KB
• scripts/_compare_core.py 16 KB
• scripts/align.py 12 KB
• scripts/compare.py 3 KB
• scripts/deliver_gate.py 45 KB
• scripts/keycolor.py 4 KB
• scripts/keyspin.py 2 KB
• scripts/measure.py 10 KB
• scripts/perframe.py 20 KB
• scripts/refmeasure.py 15 KB
• scripts/replicate_gate.py 31 KB
• scripts/review.py 14 KB
• scripts/sbs.py 63 KB
• scripts/sheet.sh 1 KB