motion-reel

Videos are programs. You write a scene with a pure seek(t); render.mjs renders frames and an MP4. Read AGENTS.md first: its rules apply to everything here. Full docs are in docs/.

1. Parse the request

Extract; ask only if missing and it changes the result: subject (URL / product / "showreel"), length (default 15s), format (16:9 default; 9:16, 1:1 on request), reference (frame, video, image folder), audio (synth, own audio.wav, or narration). Scene name = kebab-case slug.

2. Reference before design

Without a reference the default look is centered text on a gradient with everything fading in: avoid it.

• Starting points in this repo: scenes/demo (minimal contract, one morphing shape) and scenes/litoral-na-palma (complete product film: spec, assets, 9:16, loop). Read the closer one and reuse its structure, not its brand.
• Frame: look at it; take palette, type, grain, pacing. Not the subject.
• Video: extract frames with ffmpeg, describe pacing shot by shot, then design.
• Folder of images: write scenes/<name>/style_guide.md from it first.
• None given: name a concrete look (e.g. "swiss editorial", "PC-98 pixel", "paper cutout") and say which. Let the technique follow the look; do not pick a library unless asked.

3. Brand / product

Fetch the product URL and gather the real logo, screenshots and copy ("actual product assets", never invented ones). Recreate screens in HTML from screenshots; do not paste the screenshots in. Keep one scene folder per brand so the renderer, audio and export are reused for follow-ups.

4. Write the spec, not the vibe

Before code, write scenes/<name>/spec.md:

• Film in one line: logline; every decision is checked against it.
• Beat sheet: timestamps on the beat grid (motion.beat(n, bpm)); hook in the first 2s; a visual payoff every 3-5s; last frame == first when it should loop.
• State list: for UI films, one element that morphs size/radius/color between named states (button, loader, player, slider, chart, palette), a cursor driving each change. One shape, never cut.
• Text on screen: when huge, when caption-sized; leave composition room.
• Gotchas: layout is a function of (w, h); real data, not lorem. Show the spec to the user before building when the film is more than a quick draft.

5. Build

• scenes/<name>/index.html, one file, zero dependencies. Copy the contract from scenes/demo: window.DURATION, window.BPM, window.seek(t), <script src="../../lib/motion.js">. Optional: window.READY (promise for fonts/images), window.SFX, window.MUSIC.
• seek(t) is pure: no timers, Date.now, Math.random (use a seeded hash of the index).
• All motion via motion.spring / motion.track (presets: snappy UI, default cards/camera, heavy big type/logos, playful mascots). Tiny overshoot on UI, none on type. A value with several targets uses track().
• Cuts and hits land on beats. Sound comes from lib/audio.mjs (synth on the same timeline) or the user's audio.wav. Narration: local TTS in tools/tts (see docs/narration.md) or a key from .env, read by name, never printed.
• Long films: gates plan -> rig -> stills -> animatic -> full pass -> polish -> audio -> render. Write STORYBOARD.md; for parallel work brief subagents through an ANIMATION_GUIDE.md.

6. Render and critique (mandatory)

1. npm run render -- scenes/<name> --fps 60 [--w --h]
2. Read the stills in out/<name>-still-NN.png (the Read tool shows images). For a single moment use node stills.mjs scenes/<name> <t1> <t2>.
3. Score 1-10: composition, type, motion feel, originality vs the reference. List the 3 worst problems.
4. Fix, re-render. Repeat until every score is 8+. Say how many rounds it took. Test cheap first (--fps 30, short, --from/--to), final at 60.

7. Deliver

Report out/<name>.mp4, the poster still, and the rounds of critique. Other formats: re-render with --w/--h (9:16 = 1080x1920, 1:1 = 1080x1080); reframe type and UI per format, never crop. Effort: medium for small edits and re-renders, high or above for new films.