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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.examplenew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 0000000..43c994c--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1 @@