Skip to content

A motion design toolkit for coding agents.

JavaScript

Add motion design, review loop and sound design skills for agents

whaleybf94f057a600
diff --git a/.claude/skills/motion-design/SKILL.md b/.claude/skills/motion-design/SKILL.md
new file mode 100644
index 0000000..8a10176
--- /dev/null
+++ b/.claude/skills/motion-design/SKILL.md
@@ -0,0 +1,93 @@
+---
+name: motion-design
+description: Taste rules for Remotion motion graphics — timing, easing, springs, typography, color, texture, and scene continuity, with concrete numbers. Use whenever you create, animate, retime, or polish a video, composition, scene, or transition in this repo.
+---
+
+# Motion design
+
+Remotion teaches you the API. This file is the taste. Every number below comes from a shipped piece (`src/EffortVideo.tsx`); treat them as defaults you deviate from on purpose, not by accident.
+
+## 1. Time lives in `timeline.json`
+
+- Every beat is a named timestamp in seconds in `timeline.json`, grouped by scene (`s1`, `s2`, …). Components read it through `TL` from `src/lib.ts`; `scripts/sfx.py` reads the same file. That is what keeps picture and sound locked.
+- Never hardcode a start time inside a component. Offsets relative to a beat (`s1.exit + 0.05`) are fine.
+- Retiming = editing `timeline.json`, then `npm run sfx` so audio follows.
+- Everything is a pure function of `frame`. No CSS transitions or keyframes, no `Math.random()` (use `rand(n)`), no `Date`. Anything else flickers or drifts at render time.
+
+## 2. Easing
+
+| Curve | Use | Source |
+|---|---|---|
+| `easeOut` = `bezier(0.16, 1, 0.3, 1)` | entrances, reveals, anything arriving | `lib.ts` |
+| `easeIn` = `bezier(0.6, 0, 0.9, 0.35)` | exits — leaves fast, doesn't linger | `lib.ts` |
+| `easeInOut` = `bezier(0.65, 0, 0.35, 1)` | moves between two states (flip, dock, morph) | `lib.ts` |
+| overshoot `bezier(0.55, 0, 0.2, 1.12)` | a value that "lands" (slider climbing to a level) | `effortAt` |
+
+Linear is only for continuous motion: rotation, drift, grain, ticking hands.
+
+Use `prog(t, t0, t1, ease)` for tweens and `band(x, a, b)` to derive one animation from another value (e.g. captions from the slider position) instead of giving it its own clock.
+
+## 3. Springs (via `sp(frame, startSec, config)`)
+
+| Feel | damping / stiffness / mass | Used for |
+|---|---|---|
+| default settle | 14 / 140 / 0.8 | general UI entering |
+| heavy, calm | 15–20 / 140–240 / 0.6–1 | big panels, the rewind |
+| knob / notch | 12 / 190 / 0.75 | a control snapping to a step |
+| pop | 9–11 / 200–230 / 0.7 | callouts, badges, success dots |
+| elastic accent | 8 / 200 | one hero moment per video, not more |
+
+Springs for things that feel physical (UI, objects). Bezier tweens for type and camera-like moves.
+
+## 4. Timing
+
+- **Stagger** words by ~0.09 s, list items/chips by ~0.2–0.25 s, rings/dots by ~0.06 s.
+- **Word reveal** ≈ 0.8 s with `Mask` (slide up out of a clip + slight tilt).
+- **Exits are ~half an entrance** (0.35–0.55 s vs 0.7–1.25 s). Exits use `easeIn`.
+- **Overlap scenes.** The next scene starts drawing on before the previous one has fully left (`s2.drawOn` 4.02 s < `s1.flipEnd` 4.4 s). Hard gaps read as "loading".
+- **Typing** ≈ 0.035 s per character, caret blinks at ~2.4 Hz when idle.
+- **Reading holds.** Every readable state needs a hold after it settles: ≥ 1 s for a short phrase, add ~0.25 s per word beyond three, ≥ 2 s for the final hook. The 22 s cut of the effort video exists because the 15 s one flashed text too fast — when in doubt, hold longer and animate less.
+
+## 5. Typography
+
+- Max three families: display serif (Instrument Serif), UI sans (Inter), mono (JetBrains Mono) for labels, prompts, numbers.
+- Display type is big (≈ 138 px on a 1080 canvas) with tight tracking (`-0.02em`), `lineHeight: 1`.
+- One accent per line: a single italic word in the accent color carries the point (`Same *prompt.*`).
+- Mono labels: uppercase, `letterSpacing: 0.2–0.24em`, muted color. They're decoration; anything the viewer must read goes big.
+- Phone test: at 360 px wide (how X shows it in the feed) the key message must still read. Check it on the contact sheet.
+
+## 6. Color
+
+- Palette tokens live in `C` (`lib.ts`). Don't introduce new hex values in components.
+- One accent color (coral) and it means something: the thing that changed, the answer, the winner. If everything is coral, nothing is.
+- Drive glow from state, not time (`glow = effort`): light should explain the story.
+
+## 7. Texture — nothing is dead-still
+
+- Film grain overlay (`Grain`, opacity ≈ 0.09, reseeded on twos).
+- Vignette plus a dot grid drifting a few px/s (`Background`).
+- Hand-drawn "line boil" (`WobbleFilter`) for sketchy/low-fidelity states, faded out as quality rises.
+- Idle elements breathe: a ticking clock, a blinking caret, a slow rotation.
+
+## 8. Continuity and transitions
+
+- Prefer persistent objects over cuts. The prompt bar, the spark and the slider travel through scenes and change role; that's what makes it feel designed rather than assembled.
+- Every transition is motivated by an object on screen (the five result dots merge into one, which becomes the iris). No generic wipes.
+- Use velocity: derive motion trails / squash from `value(frame) - value(frame - 1)` instead of faking it.
+- One hero moment per video (the iris + impact). Build to it; don't spend it early.
+
+## 9. Anti-patterns
+
+- Everything fading in at once, or everything using the same duration.
+- Linear easing on anything that starts or stops.
+- Text that moves while it's supposed to be read.
+- More than one focal point per frame.
+- Content within ~60 px of the frame edge (safe area) unless it's intentionally cropped.
+- An empty or black frame 0 — X autoplays muted and the first frame is the thumbnail.
+
+## Workflow
+
+1. Write the beats into `timeline.json` first (a storyboard in numbers).
+2. Build scenes as components in `src/scenes/`, shared bits in `src/components/`.
+3. Run the `review-loop` skill after every meaningful change.
+4. Run the `sound-design` skill once picture timing is locked.
diff --git a/.claude/skills/review-loop/SKILL.md b/.claude/skills/review-loop/SKILL.md
new file mode 100644
index 0000000..db931cd
--- /dev/null
+++ b/.claude/skills/review-loop/SKILL.md
@@ -0,0 +1,50 @@
+---
+name: review-loop
+description: Visual self-review loop for motion graphics — render a draft, build contact sheets at every timeline beat, look at them, critique against a checklist, fix, repeat. Use after any change to a video's visuals or timing, and before calling a video done.
+---
+
+# Review loop
+
+You can't watch the video, but you can look at frames. Never report a video as done without looking at contact sheets of the current render.
+
+## Loop
+
+1. `npm run draft` — half-resolution render to `out/draft.mp4` (fast).
+2. `npm run sheet` — one frame per timeline beat, 0.3 s after it so motion has settled, tiled 4×2 into `out/sheets/beats-N.png`. Each tile is labelled with its timestamp.
+3. Open every sheet image and go through the checklist below.
+4. Zoom in on anything suspicious:
+ - `npm run sheet -- --from 3 --to 5 --every 0.2` to scrub a transition,
+ - `npm run sheet -- 3.7 3.75 3.8` for exact moments,
+ - `npm run still -- out/still.png --frame=222` for one full-resolution frame.
+5. Fix, then go back to step 1. Stop when a full pass finds nothing.
+6. Final: `npm run build`, then `npm run sheet -- --video out/effort.mp4` and `npm run wave`.
+
+## Checklist
+
+Composition
+- One focal point per frame. If two things compete, one of them waits.
+- Nothing collides or overlaps unintentionally, especially during transitions where an exiting and an entering element share space.
+- Safe area: nothing important within ~60 px of an edge.
+- Frame 0 is a real image, not black (it's the X thumbnail).
+
+Type
+- Nothing clipped by a mask, container or the frame when it shouldn't be.
+- Key message readable when the sheet tile is shrunk to phone width.
+- Text isn't moving while it's meant to be read.
+
+Timing
+- Each readable state holds long enough (see `motion-design` §4). If a tile mid-hold shows text still animating, the hold is too short.
+- Scenes overlap instead of cutting to empty frames.
+- Exits are faster than entrances.
+
+Consistency
+- Only palette colors from `C`; the accent marks the point of the frame.
+- Same element looks the same in every scene it appears in.
+
+Sound (after `npm run wave`)
+- Transients sit on beat lines in `out/wave.png`.
+- −14 LUFS ±1, true peak ≤ −1 dBFS.
+
+## Report
+
+When you finish, say what you checked, what you fixed, and which sheet shows it. Don't claim a fix you haven't re-rendered and looked at.
diff --git a/.claude/skills/sound-design/SKILL.md b/.claude/skills/sound-design/SKILL.md
new file mode 100644
index 0000000..ef83b0c
--- /dev/null
+++ b/.claude/skills/sound-design/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: sound-design
+description: Procedural sound design synced to timeline.json — which sound goes with which visual event, gain hierarchy, panning, musical key, mastering to -14 LUFS, and how to verify sync. Use when adding, changing or checking audio, SFX, music beds or loudness for a video in this repo.
+---
+
+# Sound design
+
+Most AI-made motion graphics are silent. Sound is what makes this one feel produced.
+
+All audio is generated by `scripts/sfx.py` (pure Python stdlib, no samples, no licenses to worry about) from the same `timeline.json` the visuals use. Output: `public/sfx.wav`, muxed into the final MP4 by `npm run mux`.
+
+## The rule
+
+A sound is `put(time, samples, gain, pan)` where `time` comes from a timeline key. Never type a raw number for when something happens; if the picture moves, the sound moves with it.
+
+## Visual event → sound
+
+| On screen | Sound | Generator |
+|---|---|---|
+| Typing | one key per character, ±4–6 ms jitter, random gain 0.14–0.26 | `key()` |
+| Word / line reveal | short airy whoosh + low blip on the landing | `whoosh()`, `blip()` |
+| Element pops in (badge, chip, callout) | pitched pop, rising pitch across a sequence | `pop()` |
+| Control snaps to a step | click + a note from the scale | `click()`, `blip()` |
+| Sketch / draw-on | pencil scratch texture | `scratch()` |
+| Progress / build-up | riser into the payoff (one per video) | `riser()` |
+| Success / arrival | bell chime in key | `chime()` |
+| Hero transition | whoosh in, low impact on the hit (one per video) | `whoosh()`, `impact()` |
+| Under everything | quiet pad chord, ducked under transitions | `pad()` |
+
+Accent, don't narrate: not every motion needs a sound. Continuous motion (drift, grain, rotation) stays silent.
+
+## Levels
+
+- Hero hits (pops, impact, key moments): gain 0.25–0.35.
+- Supporting (whooshes, blips, chimes): 0.08–0.2.
+- Bed (pad): ~0.03, ducked by ~65% during the hero transition and lifted after.
+- Only one impact per video. Only one big riser.
+
+## Space and music
+
+- Pan roughly follows on-screen position (−1 left … +1 right); sequences sweep across the stereo field.
+- Pick one key and keep every tonal sound in it. In the effort video the pad (D–A–D–F♯–C♯) and the slider notes (E5–F♯5–A5–B5) are in D major; the scene 3 pops and chime are still in C major, so fix those before copying them.
+- Pitch rises with progress (steps, pops) and resolves on the payoff chord.
+- Seed the RNG (`random.seed(...)`) so renders are reproducible.
+
+## Mastering
+
+- Normalize, soft-clip with `tanh`, 0.25 s fade-out (already in `sfx.py`). `DRIVE` sets loudness, `CEIL` sets headroom; tune them together and re-measure the muxed MP4, AAC overshoot isn't linear.
+- Target **−14 LUFS integrated** (X, Instagram, YouTube all normalize near this).
+- Keep **true peak ≤ −1 dBFS**. AAC encoding in `mux` adds overshoot, so the final MP4 peaks higher than the WAV.
+
+## Verify
+
+```bash
+npm run sfx # regenerate public/sfx.wav
+npm run wave # out/wave.png + loudness of the WAV
+npm run build # full render + mux
+node scripts/wave.mjs out/effort.mp4 # loudness of what you'll actually post
+```
+
+In `out/wave.png` every coral line is a timeline beat. Each transient should sit on a line or a hair after it. A hit between lines means a hardcoded time or a stale WAV.
+
+## Optional: generated audio
+
+For voiceover or sounds you can't synthesize, the ElevenLabs MCP (see `.mcp.json.example`) can generate SFX/TTS into `public/`. Place them with `<Audio src={staticFile(...)} />` inside a `<Sequence from={beat * FPS}>`, or mix them into `sfx.py` so everything stays one master.
diff --git a/.mcp.json.example b/.mcp.json.example
new file mode 100644
index 0000000..013d6c5
--- /dev/null
+++ b/.mcp.json.example
@@ -0,0 +1,24 @@
+{
+ "mcpServers": {
+ "remotion-docs": {
+ "command": "npx",
+ "args": ["-y", "@remotion/mcp@latest"]
+ },
+ "elevenlabs": {
+ "command": "uvx",
+ "args": ["elevenlabs-mcp"],
+ "env": {
+ "ELEVENLABS_API_KEY": "your-key",
+ "ELEVENLABS_MCP_BASE_PATH": "./public"
+ }
+ },
+ "playwright": {
+ "command": "npx",
+ "args": ["-y", "@playwright/mcp@latest"]
+ },
+ "figma": {
+ "type": "http",
+ "url": "https://mcp.figma.com/mcp"
+ }
+ }
+}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..8ed288e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,58 @@
+# Agent guide
+
+This repo is a motion design pipeline for coding agents, built on [Remotion](https://remotion.dev) (React → video). It ships one finished piece, `EffortVideo` (22 s, 1080×1080, 60 fps), as the reference implementation.
+
+## Read first
+
+The skills in `.claude/skills/` are the core of this repo. Claude Code and Cursor load them automatically; other agents should read them before touching a video.
+
+- `motion-design/SKILL.md` — taste rules with numbers: easing, springs, timing, type, color, texture, transitions.
+- `review-loop/SKILL.md` — how to look at your own renders and what to check. Mandatory before saying a video is done.
+- `sound-design/SKILL.md` — timeline-synced procedural audio and mastering.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `npm run studio` | live preview in the browser |
+| `npm run draft` | fast half-res render → `out/draft.mp4` |
+| `npm run sheet` | contact sheets at every timeline beat → `out/sheets/` |
+| `npm run sfx` | regenerate audio from `timeline.json` → `public/sfx.wav` |
+| `npm run wave` | waveform with beat markers + loudness check |
+| `npm run build` | sfx + full render + mux → `out/effort.mp4` |
+| `npm run gif` | README preview → `media/preview.gif` |
+| `npm run cover` | 5:2 article cover (`ArticleCover` still) → `out/article-cover.png` |
+| `npm run typecheck` | TypeScript check |
+
+Requirements: Node 20+, Python 3, ffmpeg. If `/usr/bin/chromium` (or `$REMOTION_BROWSER`) exists it's used; otherwise Remotion downloads its own browser on first render.
+
+## Layout
+
+```
+timeline.json every beat, in seconds — single source of truth for picture and sound
+src/lib.ts palette (C), fonts (F), easings, prog/band/sp helpers, TL
+src/Root.tsx composition registration
+src/EffortVideo.tsx the piece: scene orchestration
+src/ArticleCover.tsx 2000×800 still built from the same timeline and easing
+src/scenes/ one file per scene
+src/components/ reusable pieces (PromptBar, EffortSlider, primitives: Mask, Roll, Grain…)
+scripts/sfx.py procedural sound design
+scripts/sheet.mjs contact sheets for review
+scripts/wave.mjs waveform + loudness
+examples/ gallery: prompt, process and result for each piece
+```
+
+## Making a new video
+
+1. Agree on the message and a storyboard with the user first (what's on screen, in what order, what the one hero moment is).
+2. Write the beats into a timeline JSON before any component code.
+3. Add a `<Composition>` in `src/Root.tsx`, build scenes, reuse `src/components/` and `src/lib.ts`.
+4. Loop with `review-loop` until a full pass is clean, then do sound with `sound-design`.
+5. Add the piece to `examples/` with the prompt you were given.
+
+## Conventions
+
+- Animation is a pure function of `useCurrentFrame()`. No CSS animations, `Math.random()` or `Date`.
+- No hardcoded start times in components; read them from the timeline.
+- Colors only from `C`, fonts only from `F`.
+- Match the existing code style: small helpers, inline styles, comments only for non-obvious constraints.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@