Animate

Animate

You make short animated videos in code: one <canvas>, drawn and scored procedurally, deterministic frame by frame, rendered with a headless browser and ffmpeg. The story follows a grammar studied from strong short-form animation; the look is a style — a plug-in kit chosen from styles/ or made from the user's references with new-style.md.

Requirements: Node 18+, Playwright with Chromium (npm i -g playwright && npx playwright install chromium), ffmpeg on PATH. Check them first; if one is missing, tell the user the install command and stop. For a voice-over, Python with faster-whisper (pip install faster-whisper) times every word; without it the word times are estimated.

All paths below are relative to this skill's base directory. Pieces live in the user's project at pieces/<name>/ (create pieces/ if needed); styles the user makes live in <project>/styles/<name>/.

Non-negotiables

1. No animating before the storyboard is approved. The check-ins exist because a wrong story or look costs a full build.
2. Look at references before drawing anything — the user's, or the style's sample.png and demo. Then check every key frame against grammar/FRAME.md and the style's own checklist in its STYLE.md.
3. Every factual claim on screen is checked with a web search and listed with its source in the brief. Never claim "first" without a source.
4. Single file, all code: one index.html; everything is drawn and synthesized in code — no image/audio/video files, no data: URIs, no URLs, no web fonts in the code. tools/build.mjs enforces it. Two opt-in exceptions, both the user's own: assets (screenshots and logos in <piece>/assets/, embedded by the build) and a music track (joined at export). See Assets and Music below.
5. Deterministic: seeded randomness only (RNG(...)), the boil index B for per-step variation. Never Math.random() or wall-clock time.
6. Reference media stays local. Never commit it, copy its code, or name its artist in published output unless the user asks to credit them.
7. "Done" is measured: tools/review.mjs passes and you have looked at the contact sheets. Report the numbers, not "looks good".
8. Ask with options. Use AskUserQuestion with a recommended default first, so the user can answer in one click.

The flow

0. Intake

Ask the questions in intake.md — only the ones you can't infer. For the look, build the gallery (node tools/gallery.mjs <out.png> [<project>/styles], ~3s), show it and ask: which of these, or show me a reference? Then study the references yourself against FRAME.md and the style's checklist.

1. Story check (text, fast)

Pick the format from grammar/FORMATS.md — the plot engine decides it (a history is a chronology joined by morphs; a mission cuts on the beat; a list is a catalogue). Read grammar/STORY.md. Web-check the facts. Then show the user:

• the one-line idea and the sayable device ("the spark gains a ray each era and ends as the answer")
• the format and why, the style, length, BPM
• a numbered beat table: time, what happens, the bridge into the next beat, the sound's role (where the silence is, where the loudest hit is)

Ask: approve / change beats / different angle. Revise until approved. This is where "I meant X, not Y" gets caught cheaply.

2. Look check (2–4 style frames)

Start the piece at pieces/<name>/: copy piece.json and src/ from the style's demo (styles/<name>/demo/) — it already speaks the style's kit and joins eras with a morph — or from templates/beat-cut/ for a piece that cuts hard on the beat (8ths, a 16th-note rush on odd frames, one era per shot, framings from cameras), or templates/piece/ for the plainest cut-paper morph. Set "style" in piece.json, then write brief.md and LOG.md fresh (the template's are placeholders).

• A shipped style: read its STYLE.md and demo and draw with its kit.
• The user's references: follow new-style.md. Measure the references first (tools/measure/refs.mjs); the piece's own style frames are the matched frames, so this is one check-in: the compare sheets and the frames together. Save the style folder after the piece is approved (the piece becomes its "proven on").

Draw 2–4 of the most different beats as full-size frames. Each must pass FRAME.md and the style's checklist. Render them side by side with node tools/still.mjs pieces/<name> 2.25,9.75,16.5 look.png --scale 0.5 (or tools/storyboard.mjs with TIMELINE.board set to those beats), and show the image. Ask: thumbs up per frame / change the look / try another style.

3. Storyboard check (every beat)

Draw every beat in the approved look. Fill TIMELINE.board with one key time per beat ({ t, title, sound, next }) and render the board. Ask for thumbs up/down by panel number and notes; redraw what's down; repeat. The panels are the video's own scene functions, so nothing is redrawn later.

4. Build

1. Write pieces/<name>/brief.md (spec, style, beats, bridges, sound plan, claims + sources). Keep a LOG.md.
2. Animate the scenes: timed actions with TT, ev(t, d), popS(t), write-ons (see craft.md → Motion). Wire eras, cameras and bridges in src/bridges.js (morph-joined formats) or leave BRIDGES = [] for hard cuts.
3. node tools/build.mjs pieces/<name> → index.html (the style's kit is pulled in from piece.json "style").
4. Test tiles while building: node tools/tile.mjs pieces/<name> tile.png <frames...> — look at them; tile across every morph and cut.
5. Score in src/score.js (see craft.md → Sound).
6. node tools/export.mjs pieces/<name> --share → frames, audio.wav, stems, renders/final.mp4, renders/share.mp4 (--formats 9:16,1:1,16:9 for every format; --blur 4 for motion blur on 1s styles). Iterate the mix with --only-audio (re-renders the score and remuxes it, ~4× faster).
7. node tools/review.mjs pieces/<name> → contact sheets per shot, cut grid, morph grid, story arc, anchor, text (cut off / overlapping / under the phone UI) and sound (the loudest moment, the silence before it, LUFS). Fix until it passes, view the sheets, write a per-shot PASS table in LOG.md. Trust the text check over your eye: a cropped label looks fine on a contact sheet.

5. Deliver

Send renders/share.mp4. Say in a few lines: what it is, the checks' numbers, what the review caught and fixed, the weakest shot, and what you haven't verified (e.g. you can't listen to the score). Ask what should change: story, look, transitions, pacing, sound.

6. Learn

After each run append to the piece's LOG.md. If something new went wrong or worked, propose a one-line rule for craft.md, the style's STYLE.md or a kit change, and add it when the user agrees.

Voice-over (optional)

Ask at intake (question 3). With a voice, the voice is the clock: each beat starts ~0.3s after the previous sentence ends, and the big moments land on spoken words. The script is the storyboard: one line per beat.

1. Write the script to pieces/<name>/voice/script.json: { "lead": 1.2, "tail": 1.8, "lines": [{ "id": "open", "text": "As it is spoken.", "after": 0.45 }, ...] }. Write numbers and names the way they should be said. Keep it ≤ 3.5 words/s; give a line a longer after where the picture needs time to land (a count, a caption, the silence before the payoff).
2. Build before the voice exists: node tools/voice.mjs pieces/<name> --scratch makes a timing voice with the OS's own speech (never ship it), so the whole piece can be animated and reviewed.
3. The takes: one file per line, saved as voice/<id>.mp3 with "file" set on the line.
   • The ElevenLabs connector (if the user has it: Claude's Settings → Connectors → ElevenLabs, signed in with OAuth, no API key): find 2–3 narrators that fit with its voice search, generate one line in each (one variation each, not four), let the user pick, then generate every line once with that voice and model. The generation result gives a short-lived download link per take: save each into voice/. It costs about one credit per character; say the total before the full run. If the connector was added during the session, its tools may only appear after the app restarts.
   • The user's own recording, one file per line (or cut from one take).
   • Never fetch a voice from a site the user didn't point to, and never clone a voice without its owner's consent.
4. node tools/voice.mjs pieces/<name> → voice/voice.wav (the lines with their pauses) and voice.json (every line's and word's start and end, heard in the audio by faster-whisper, locally). The build injects it as VOICE.
5. In the head: VL(id) is a line, VW(id, word, n) when its n-th word starts; beats start at the previous line's t1 + 0.3; TIMELINE.narration comes from VOICE.lines and DURATION from VOICE.duration. Cue Writes and flashes on the words that name them. Put the payoff hit in a pause before the line that names it: a hit under speech is ducked away.
6. piece.json: "voice": { "file": "voice/voice.wav", "music": -12 }. Export mixes the voice over the score (the score at music dB, ducked further while the voice speaks) to −14 LUFS. Review judges the story arc and the payoff window on the score alone (renders/audio-score.wav; a voice is louder than any hit) and the voice with its NARRATION check.
7. Re-takes and script edits: replace a line's file (or edit its text), rerun voice.mjs, rebuild: scenes cued from VOICE move with it. A changed word can orphan a cue that points at it; check those beats.