motion-film

motion-film: Make Videos in Code

Every frame, animation, subtitle, and sound effect is generated by code, rendered frame by frame into an MP4. No video generation models used.

This skill is a methodology + a lightweight toolset — no media library included; materials are sourced, synthesized, and licensed per project.

First, Determine the Route

Route	Typical Request	Primary Reference
A. Product Promo	Turn a website/app/frontend project into a promo or feature demo	references/product-promo.md
B. Style Film	"Make a 30-second film in XX style about…" — MG animation, title sequences, variety-style text	references/style-atlas.md + references/style-spec.md
C. Single Shot / Single Effect	"Create a title fly-in" or "Make a lock-frame animation"	Follow principles below directly; read relevant sections of references/aesthetic-rules.md

Both main routes share: references/directing.md (direction), references/timing.md (rhythm), references/sound.md (audio), references/tech.md (rendering), references/review.md (review).

If the user provides a BGM to sync: references/beat-sync.md — analyze the music first, then storyboard.

Ask Only Once Before Starting

Consolidate all unresolved questions into one message, then never ask again; use defaults for everything else and document them in the treatment:

• Only the user knows: product focus, target audience, release platform, must-include content;
• Does the user have their own assets: logo, brand colors/fonts, voice-over, music, reference videos;
• Does the user want to see the storyboard/style frames before the final video? (If yes, pause once; if no, run straight through).

Defaults: 30–60 s (single shot 3–8 s); 1920×1080; product promos at 30 fps, style films per style (24/30); subtitles and voice-over match user's language; loudness −14 LUFS, true peak ≤ −1 dBTP.

If the user explicitly says "you decide" or "just do it," skip the question and proceed with defaults.

Ten Core Principles (Refined from Four Sources & Real Experience)

1. The picture is a pure function of time. render(t) always yields the same frame for the same t; forbid Date.now(), seedless Math.random(), or cross-frame cumulative state. Use mulberry32/hash with a fixed seed for all randomness. Every frame can be rendered independently, out of order, or in parallel.
2. One timeline drives everything. Shot boundaries, key actions, subtitles, sound effects, and music hit points all derive from a single cue table; change the duration in one place, and audio follows automatically. For beat-sync videos, write in beat notation (beatF(n)), not raw frame numbers.
3. Time for the audience, not for the code. List what the audience needs to read (reads) in each shot — one at a time. Actions can be fast, but meaning must pause. The first pass is almost always too fast — default to one notch slower. See the formula in timing.md.
4. One shot tells one thing; one technique is the star only once per film. The opening gives only one subject + one complete action arc (setup—development—resolution). Delete duplicate shots and repeated taglines.
5. Motion is like life, not like machinery. No linear interpolation; use anticipation → action → follow-through; stagger parts to avoid "twins" (left-right symmetry, group synchronization); landing bounces must overshoot.
6. Visual language grows from the subject/product itself. For product promos, fonts, color palettes, corner radii, and materials come from the product's design system; for style films, adhere to the essence of that style (and what it is not). Do not apply an unrelated "promo skin."
7. Restrain effects. Light effects should not be clustered; give one to the hero only once and crop it into rounded corners. Product promos default to no handheld camera shake. Full-frame impacts (screen shake, flash frames, overall scale pump) are limited to ≤ 3 times per film.
8. Sound is half the film. Three layers: ambient + Foley + music. Every visible action has a sound. Leave real silence before the climax. Sound is final after picture lock.
9. First, decide direction with the cheapest output. Treatment (text) → style frames (real rendered stills from code) → low-res preview → final render. Never enter the expensive phase over a direction dispute.
10. Review yourself first, then submit to an independent review. After each iteration, generate contact sheets, motion bars, and cropped/enlarged views for self-inspection. Before delivery, submit to a reviewer who did not participate (a clean-context subagent or a separate session), who scores and flags issues per review.md. Fix only one round.

Workflow

1. Brief: The round of questions above; for product promos, additionally perform a read-only product inspection (positioning, features, page state, design tokens, data risks).
2. Treatment (write TREATMENT.md before any visual code): Select one of three candidate structures; logline and arc; reference works — "what to learn / what not to take"; shot table (shot size, camera position, movement, duration, rationale); second-by-second beat map; cue map; sound design table; subtitle and typography plan. See template in directing.md.
3. Style frames: 2–3 keyframes (with character model sheets if applicable) rendered from real code; verify against style specifications.
4. Per-shot implementation: First, render key poses as still frames for inspection; once readable, fill in the motion between them. Hard-code 2 acceptance moments per shot; after completing each shot, generate a still frame for self-check.
5. Sound: After picture lock, generate music, Foley, and subtitles from the cue table; mix and master.
6. Self-inspection: Contact sheet (every 0.5–1 s), motion bars for key actions (0.1–0.2 s), full-resolution crops of text and edges; watch through with audio at full speed. Check against every item in aesthetic-rules.md.
7. Independent review + one round of fixes: review.md. Fix minor issues immediately; for major issues, include a one-line explanation at delivery.
8. Delivery: See below.

Tools (scripts/, copy to project as needed)

File	Purpose
scripts/render.mjs	Renderer: HTML page exposes renderAt(t) → still frame / contact sheet / motion bar / crop / MP4, supports multi-worker, motion blur (sub-frame accumulation), portrait orientation
scripts/motion.js	Pure-function utilities for in-page use: seeded random, easing families, keyframes, spring, overshoot, staggering, beat notation, speed curves
scripts/sfx.py	Programmatic Foley and mixing: whoosh / impact / riser / pop / click / sparkle / tick — synthesizes mix.wav from an event table
scripts/master.sh	Multiplex + two-pass loudnorm (−14 LUFS / −1 dBTP) + black frame detection + duration/specs report
scripts/beat_grid.py	BGM beat grid fitting (including 2x / 0.5x / 3:2 mis-correction) + kick/snare/hi-hat classification + energy structure, outputs beat_data.json
scripts/capture.mjs	Product promo asset trio: full-page 2x screenshot, element cutouts (with transparency, up to 4x), empty plate, layout.json coordinate table
templates/starter/	A ready-to-run 9.6s demo project (timeline, renderAt, sound events, subtitles, build.sh one-command output) — copy this as a starting point for new projects

render.mjs maps /lib/ to the scripts/ directory of this skill. In a page, use <script src="/lib/motion.js"> to reference the utility functions.

For a new project: copy templates/starter/ → run npm i puppeteer-core in the project → modify the timeline and shots → run MF=<path to this skill> sh build.sh.

If using Remotion for product promos: the same methodology applies (see tech.md for a comparison). Note that Remotion may require a paid license for commercial use; remind the user before starting.

Dependencies: Node 18+, ffmpeg, Chrome/Chromium (render.mjs finds it automatically or set CHROME_PATH); npm i puppeteer-core installed in the project. Python 3 + numpy/scipy (audio); install librosa only for beat-sync analysis, into the project's own venv. Do not install system software for the user; if missing, mention it in the round of questions.

Delivery

The project folder contains:

• <name>.mp4 (and poster.jpg); for product promos with BGM, also provide a version without BGM (keep sound effects) for easy music replacement later;
• <name>.srt (if subtitles or narration exist);
• TREATMENT.md;
• CREDITS.md: source and license for every third-party asset (fonts, images, music, samples, TTS engine);
• source code and a one-command build.sh.

Inform the user: where the final video is, that CREDITS.md lists licenses, and that assets provided by the user are their own responsibility for licensing. Do not attach any promotions, attribution requests, or "where to publish" suggestions unless the user asks.

Red Lines

• Reference works are studied only for syntax (composition, rhythm, camera movement, color logic); do not copy characters, designs, melodies, specific shots, logos, or fonts.
• No real brands, works, or characters appear in the video unless the user owns or has confirmed permission to use them; use fictional brand/product names.
• Use only CC0 / public domain / OFL / CC BY (with attribution) / clearly free-for-commercial-use assets; "no known restrictions" does not count. For other open licenses, first explain the terms to the user.
• For product promos: all customer data, personal information, internal data, secrets, and live data must be fictionalized or anonymized before taking screenshots.
• Do not automatically pull code from the internet to execute, and do not automatically update this skill; when downloading assets, tell the user what to download, from where, and under what license.