name: film description: Directs a code-drawn film or seamless loop from one prompt to a finished, checked MP4. three.js, canvas or DOM pages expose renderAt(t) and render frame-exact on the GPU. The film gets a brief written in numbers, a score file as the master clock, closed-form motion, QA that measures motion, synthesized sound and X-ready export. Use when the user wants a code-made animation: a mascot or character loop, motion graphics, kinetic type, a product or explainer clip, a music-synced animation, or "a film from one prompt" with Claude. Also use it to fix a code animation that freezes, stutters at the loop, drifts off the beat, renders differently from the preview, or keeps the hero too small. argument-hint: "[idea, brief or film.html]"
Film: one prompt, one film
Paths. File paths in this skill (
../../references/...) are relative to this SKILL.md; the plugin root is two folders up. Themotion-*commands are on PATH in Claude Code. In Codex, OpenCode, Cursor or any other host, runexport PATH="<plugin root>/bin:$PATH"once in the shell first.
You direct a short film drawn by code and deliver a file that has passed its checks. The method comes from 40 finished films:
- Write the clock first.
- Replace every adjective with a number.
- Measure the hero.
- Fix on stills before you render.
- Measure motion, because stills cannot show it.
- Press play.
Tools
Each one prints --help. If a name is not found, put <plugin root>/bin on PATH (see Paths above), or call node <plugin root>/scripts/<name>.mjs.
| Command | Does |
|---|---|
motion-doctor | Checks Node, the ffmpeg filters, Chrome with the GPU renderer, and optionally Blender and uv |
motion-new <dir> | Scaffolds a film that already passes QA: film.html, timing.spec.json, BRIEF.md, NOTES.md, git |
motion-timing build spec.json --inject film.html | Builds the score: beats, tempo ramps, events, shots. grid, check and from-audio are also available |
motion-lint film.html | Static check for determinism: clocks, Math.random, state carried between frames, CSS animation, unpinned CDNs |
motion-inspect film.html | Checks the page: GPU, contract, stills, contact sheets, seek, seam, hero width per shot, hero and text inside the frame |
motion-render film.html [--draft] | Frame-exact GPU render of frames 0..N-1 to MP4, with motion blur from sub-frames (in linear light, clamped at cuts) and the in-page soundtrack |
motion-qa renders/x.mp4 --timing film.html | Checks the file: freezedetect, motion graph, planned moves, seam, black frames, format, colour tags, loudness |
motion-export x.mp4 [--preset x|gif|master] | Last mile: X MP4 with the sound mastered and measured after AAC, a GIF inside X's limits, or a ProRes master |
motion-blender turnaround|costume|template | Runs the bundled Blender scripts headless (finds Blender itself) |
The loop
Follow these steps in order. Each one is cheap compared with the next.
- Model and effort. If the session runs Fable 5.2, use
/effort mediumfor the brief, storyboard and stills, and/effort highfor the unattended build. Do not use Max: it costs about 3x and is not reliably better. One Max run thought through 128K tokens and drew nothing. Details are in../../references/effort-and-cost.md. - Brief in numbers. Write
BRIEF.mdusing the template in../../references/brief.md, which covers SUBJECT, TIME, PALETTE, TYPE, SHOTS, EASING, HOLDS, BANS, QA and LOOP, plus the camera list.- Each line holds a number or a named thing; "premium" or "bouncy" is not allowed.
- If the request already settles what happens, the length and the look, start building.
- Otherwise ask once, only about choices that change the film: story beats, length, a look the request does not name, or the music source. Put the recommended option first.
- Score first. Put every hop, cut, camera move and sound hit in
timing.spec.jsonas beats or bars, then runmotion-timing build timing.spec.json --inject film.html.- Nothing is timed by hand.
- Sound lands 1 frame after its picture event.
- Pick a BPM that gives a whole number of frames per beat (
motion-timing grid --bpm N).
- Build on the contract. Start from
motion-new <dir>, or keep the user's page and add the contract from../../references/contract.md:window.renderAt(t)draws exactly time t.window.__readyis set only after fonts, models and textures have loaded.window.FILMholds duration, fps, size, loop,minHeroPxandcuts.window.probe(t)returns the hero box and the text boxes.window.renderSoundtrack()is optional.- Motion uses motionkit (
window.MK, inlined in the template): closed-form springs, hops, easing, tempo ramps and seeded noise. The numbers are in../../references/motion-numbers.md.
- One round of fixes on stills.
- Run
motion-lint film.html, thenmotion-inspect film.html. - Read the contact sheet and the stills yourself with the Read tool.
- First stills always come out too wide and the hero shrinks to a dot. Fix framing, size and focus here, once, before any full render.
- Run
- Draft, then measure motion.
- Run
motion-render film.html --draft(half size, 30 fps). - Run
motion-qa renders/film_draft.mp4 --timing film.html. - Treat any freeze, still stretch or missing bump you did not plan as a bug. Add planned holds to the spec's
holds.
- Run
- Final render.
- Run
motion-render film.html --subframes 16. Add--capture canvaswhen everything visible is drawn in one WebGL or 2D canvas; it is about 5x faster than page screenshots. - Run
motion-qa renders/film.mp4 --timing film.html.
- Run
- Export and check what you upload. Run
motion-export renders/film.mp4, thenmotion-qa renders/film_x.mp4 --timing film.html --delivery. Use--preset giffor a GIF. - Report.
- List each check with its number. "Looks good" is not a check.
- Update
NOTES.mdwith what changed this round. - Commit.
- Give the path to the file and ask the user to press play and listen. No tool replaces that.
Finished means:
- the full-length MP4 has rendered;
- every QA check passes with its number;
- the delivery file passes
--delivery; - NOTES.md lists the changes.
Until then, keep going. A failed render, a timeout, a missing font or a locked file is an ordinary obstacle: fix it and continue. Stop only for a real blocker, such as an asset only the user can provide, and say exactly what you need.
Rules that prevent the usual bugs
- Every frame is a pure function of t. No clocks, no
Math.random, and no velocity carried between frames. Springs are closed-form functions of t, with the damping ratio written out.motion-lintand the seek check enforce this. - Render frames 0..N-1, never frame N. The last frame must flow into frame 0 in pose, velocity, camera and light. A seam that is not a planned cut must look like one normal step (ratio ≤ 1.5).
- The hero is at least 170 px wide at 1080p in every main shot. Measure it per shot through
window.probe. Faces get an 85 mm lens, and focus follows the hero's real depth on every frame. - Design collisions out instead of fixing them. Give separate lanes or planes to things that could clip, such as notes that fall behind the keys. When something must not intersect, give it a numeric check.
- Get energy from cuts on the beat, not from zooms or whip pans. A good angle holds for a whole beat. Text is fully in frame or fully out. The last frame is the image, with nothing under it.
- Name the defaults you do not want in a BANS line: glow orbs, purple gradients, fade-in on everything, lens flares, extra labels. Only the text listed in the brief appears on screen.
- Write fewer, better rules. Fable 5.2 follows style rules to the letter. Use numbers and named steps, not CAPS. Read the diff, not the summary.
When it goes wrong
../../references/troubleshooting.md maps each symptom to the line to fix or paste back. The most common:
| Symptom | Fix |
|---|---|
| The hero is a dot | Set a minimum hero width per shot, measure it with probe, move the camera in or use a longer lens |
| Graphics are frozen but the checks passed | Run freezedetect and the motion graph on a draft. Stills cannot show motion |
| The loop stutters | Render frame N-1, not N. Match pose, velocity, camera and light at the seam |
| Preview and render differ | State is carried between frames. Make it closed-form in t; the seek check shows where |
| The model stopped and offered to continue | Restate what "done" means (above) and say "keep going" |
References
Read a reference only when the step calls for it.
| File | Covers |
|---|---|
../../references/brief.md | Brief template, adjective-to-number table, camera list, ownership and finishing blocks, prompt style |
../../references/contract.md | renderAt contract for three.js, canvas, DOM/CSS, SVG/GSAP and <video>; probe; soundtrack; pitfalls |
../../references/motion-numbers.md | Springs and damping-ratio tables, easing, durations, stagger, squash and stretch, beat grid, tempo ramps, lenses |
../../references/qa.md | The QA protocol, thresholds, the reviewer rule, report format |
../../references/render-and-export.md | GPU flags per OS, capture modes, motion blur, X and GIF limits, loudness |
../../references/sound.md | Sound from the score, synth voices, seamless audio loops, bit-identical mixing, mastering, beat tracking |
../../references/examples.md | The playbook's full prompts: Encore, the effort race, the crow, the springs, QA, the ant, the costume show |
../../references/effort-and-cost.md | Effort levels and prices, changing effort mid-conversation, cache, fast mode, advisor, usage limits |
../../references/troubleshooting.md | Symptom-to-fix table |
../../references/toolbox.md | Remotion, HyperFrames, GSAP, motion2code, claude-video, chrome-devtools-mcp, Mediabunny, Blender tools, with licences |
Related skills in this plugin:
motion-playbook:briefturns a request into a numeric brief.motion-playbook:qareviews any film or MP4 with numbers.motion-playbook:exporthandles the last mile.motion-playbook:blender-assetbuilds costumes and props by script.motion-playbook:studioruns a long film with a team of agents.