code_motion_design v1.0.0

name: code_motion_design description: Produce motion-design video from code only: turn a creative brief into a beat map (timed scene JSON), review PNG stills, then render frame-by-frame with Playwright and encode to MP4 with ffmpeg. Use when someone asks to "make a video" or "animate" something programmatically, turn a script into motion graphics, render an HTML/JS animation to video, or build a repeatable, version-controlled video pipeline with no editor, no React build, and no wall-clock recording.

Code Motion Design

Purpose

Ship a finished MP4 from a written brief without a video editor. The pipeline is deterministic: every frame is a pure function of t = frame / fps, so the same beat map always produces the same video, frame counts are exact, and re-renders after a copy change are one command. This is the same architecture Remotion and similar tools use, but framework-free: a single HTML file, Python, Playwright, and ffmpeg, nothing to install beyond that.

Workflow

1. Brief. Get the creative intent in writing: audience, message, duration, aspect ratio, tone. One paragraph is enough for a short; insist on a paragraph, not a vibe. No brief, no build.
2. Beat map. Write beatmap.json following references/beat-map-schema.md: timed scenes (title, bars, lower, fade) with start/end seconds. Duration = last scene end. Frames = duration * fps. Budget accordingly.
3. Stills review. python3 bin/render.py stills beatmap.json --times 0.5,2.6,6.0 Captures those exact timestamps and prints the PNG paths. Look at them. Every one must read correctly before you proceed. This is the quality gate; a full render of a broken map is wasted time.
4. Render. python3 bin/render.py render beatmap.json --out out.mp4 Captures every frame headless, then encodes (h264, yuv420p, crf 18, faststart). Options: --workdir to keep frames, --audio track.wav to mux a soundtrack, --supersample for razor text (renders 2x, downscales after), --crf for quality vs size.
5. Verify. Run the ffprobe check from references/encoding-notes.md: resolution, duration, fps, codec. Extract one frame per scene and confirm the subject matches what the beat map promised.
6. Iterate. Copy changes mean editing the beat map and re-running step 4. The beat map is the source of truth; check it in.

Output Contract

• Deliverable: an MP4 that plays everywhere (h264, yuv420p, faststart), plus the beat map JSON that produced it.
• The video must match the brief: same message order, same durations, text readable at the delivered resolution (check the stills at 100%).
• A re-render of the checked-in beat map must reproduce the video; never hand over a video whose beat map is lost or differs.

Operating Rules

• Determinism is load-bearing: the engine never uses Date.now(), Math.random(), or free-running requestAnimationFrame in the render path. Seeded pseudo-random only. Anything time-varying must be a function of t.
• Never record the screen or play-and-capture in real time. Always seek to exact timestamps; that is what makes timing frame-accurate and output repeatable.
• Text is the usual failure: fonts fall back to DejaVu Sans in headless Linux, so sizes that look right on a designer's machine may not hold. The stills review is where you catch this, not after the render.
• Keep scene types in the shipped engine (assets/engine.html) to the four it supports; new scene types get a painter function in the engine and a test still before use.
• Stills before renders, no exceptions. Stills are cheap; renders are not.
• When Remotion or Motion Canvas is the better fit (React team, complex scenes, existing Node pipeline), say so and point there instead of forcing this tool.
• Style law: plain direct copy in any on-screen text, no em dashes, no marketing filler. The words on screen are part of the craft.

Quick start

bash
cd <this skill dir>
cp assets/example-beatmap.json my-video.json   # edit the copy
python3 bin/render.py stills my-video.json --times 1.0,3.5,6.5
python3 bin/render.py render my-video.json --out my-video.mp4