---

name: sn-code-video description: Create and revise code-driven videos with Canvas, SVG, HTML/CSS, Three.js, Remotion, Manim, or p5.js, including sound, deterministic frame capture, visual review, and MP4 verification. Use for rendered explainers, procedural animations, motion graphics, promos, and music-synchronized films; not for general web apps, scroll-driven HTML stories, or footage generation with video models.

SN Code Video

A code video is a program frame(t) → image, sampled at t = i / fps and encoded. Almost every failure in this kind of work is one of four things: the film is never finished, the picture depends on wall-clock time, nobody looked at the frames, or the file does not match the brief. This skill prevents those four.

Setup and paths

Use a separate project folder for the video source, SPEC.md, build files, and outputs. Resolve SKILL_DIR to the absolute directory containing this SKILL.md, whether installed in the agent's skills directory or used from this repository. Run project commands from the video project folder; invoke bundled scripts through "$SKILL_DIR/scripts/..." so they do not depend on the current working directory. Set SKILL_DIR again in each shell session if needed.

Requirements: Node.js 18+ for browser capture, Python 3, FFmpeg/ffprobe with libx264 and AAC, and fonts covering the requested language. Install Playwright (with Chromium) or Puppeteer in the video project; the capture helper resolves its packages there first. Python audio dependencies are listed in requirements.txt; edge-tts needs network access, and faster-whisper needs downloaded model weights for transcription checks. Install only the tools required by the chosen renderer and audio workflow. Setup and invocation examples: English guide / 中文指南 in the source repository; these repository guides are not required when the skill folder is installed on its own.

Deliver the playable MP4, source code and reproduction commands, SPEC.md, VERIFY.md, and a contact sheet. Audio stems and timing data belong in the project when sound is used.

0. Read the craft guides you need

Reference paths are relative to this skill folder; output and input paths in commands are relative to the video project. Besides this file it holds craft guides in references/ and helper scripts in scripts/ (audio packages in requirements.txt). Read every guide that matches the request before writing SPEC.md; most videos need two or three.

| Guide | Read when the request has… | |---|---| | references/explainer-diagrams.md | anything to teach or explain: math, science, history, processes, data | | references/stylized-looks.md | a named style, medium or artist (ink wash, pixel art, cut paper, vaporwave, watercolour, …) | | references/simulations-and-generative.md | particles, flocks, cellular automata, physics, fields, shaders, generative patterns | | references/character-and-creature-motion.md | people, animals or creatures that move or act | | references/threejs-scenes-and-cameras.md | a 3D scene, product or camera move | | references/motion-graphics-and-promos.md | kinetic type, UI, logos, product or brand promos | | references/sound-design-and-narration.md | any audio: narration, music, effects, ambience | | references/music-and-beat-sync.md | music-led films, beat-cut picture, supplied tracks or lyrics |

A request that names a style always needs references/stylized-looks.md, and a film with any audio always needs references/sound-design-and-narration.md.

1. Finish the film

• The deliverable is a playable video that meets the brief. Code, stills, a plan or a preview are intermediate results. Keep working until the final file exists and has passed section 6.
• Decide composition, palette, easing and implementation details yourself and note the choices in SPEC.md. Ask the user only about the few open choices that would change the whole film (for example language, aspect ratio, length, or whether there is a voice), and only when you can ask; otherwise choose a sensible default and say which.
• Budget the time. Get a rough full-length render early (even ugly), then improve it. A finished, slightly plain film beats an unfinished ambitious one.
• Timebox sub-problems. If one problem (recalling an exact pattern or constant, tuning one effect, chasing one bug) has taken about 30 minutes without visible progress, change approach: simplify the effect, derive the value from its definition, use the reference data in the craft guides, or fall back to a design that does not need it. Do not spend hours reconstructing data from memory.

2. Turn the brief into a spec

Before writing code, write SPEC.md in the project folder:

• Format: width × height, fps, duration (target and allowed range), frame count = round(duration × fps), loop or not, and audio: required, forbidden, or left open. When it is open, decide from the brief whether sound would serve the film (section 10). Write the sound requirements (type, voice language, fixed lines, sync points) into the spec too.
• Exact copy: every on-screen string the brief fixes, verbatim, in order. Nothing else may claim facts, prices or specifications.
• Facts and numbers: every value the picture must show or obey (dates, physical constants, data values, counts). Note the source the brief gives.
• Assets: each supplied file and how it must be used (unaltered logo, screenshot fidelity, photo kept photographic).
• Must-haves: one line per requirement in the brief ("camera orbits counterclockwise ~90°", "dominoes never interpenetrate"). Each line becomes a check in section 6.

Choose the stack for the content, not out of habit:

| Content | Good default | |---|---| | 2D diagrams, math, particles, pixel art, painterly textures | Canvas 2D (browser or @napi-rs/canvas in Node) | | Crisp vector shapes, UI, kinetic type, logos | SVG / HTML+CSS driven by a paused timeline, or Remotion | | LaTeX-heavy math | Manim (or KaTeX/MathJax rendered to SVG) | | 3D scenes, products, cameras | Three.js (see references/threejs-scenes-and-cameras.md) | | Shaders, aurora, fields, post effects | WebGL / GLSL fragment shaders |

3. Time is the only input

• Expose one entry point that draws the exact state at time t, for example window.seek = async (t) => {...} plus window.READY = true once fonts and images are loaded. Frame i is rendered at t = i / fps.
• The same t must always give the same image, in any order, in a fresh page. Forbidden: Date.now(), performance.now(), requestAnimationFrame loops that advance state, CSS transitions/animations left running, a playing GSAP timeline, unseeded Math.random(), state carried over from the previous frame.
• GSAP: build a paused: true timeline and call tl.seek(t). CSS animations: set animation-play-state: paused and a negative animation-delay, or compute styles from t yourself. Remotion: derive everything from useCurrentFrame().
• Randomness: seed once, then keep values. A tiny seeded generator is enough:

function mulberry32(a){return function(){a|=0;a=a+0x6D2B79F5|0;let t=Math.imul(a^a>>>15,1|a);t=t+Math.imul(t^t>>>7,61|t)^t;return((t^t>>>14)>>>0)/4294967296}}

• Simulations (physics, flocks, cellular automata, crowds) are computed once with a fixed time step and seed, stored, and sampled by t (interpolate between stored steps). Never integrate inside the render call.
• Easing: write it as functions of t (smoothstep, cubic in/out, closed-form damped springs). A value that changes target several times is a sum of eased segments, still a pure function of t.

4. Capture and encode

• Browser pages: scripts/capture.mjs serves the project folder, opens the page in headless Chromium (Playwright or Puppeteer, resolved from the project's node_modules first), calls seek(t) for each frame and pipes screenshots into ffmpeg: node "$SKILL_DIR/scripts/capture.mjs" <project_dir> --page index.html --fps 30 --dur 12 --size 1920x1080 --out out/video.mp4 Test it on 2–3 frames (--frames 3) before anything else. If Chromium cannot start (for example missing system libraries) and you cannot fix that quickly, switch early to a path that needs no browser: Canvas 2D in Node with @napi-rs/canvas, or Manim. Do not spend your time fighting the browser.
• Node canvas: draw each frame with @napi-rs/canvas and write raw RGBA to ffmpeg's stdin (-f rawvideo -pix_fmt rgba -s WxH -r FPS -i -).
• Remotion / Manim: use their own renderers, then re-encode if the codec or pixel format differs from the spec.
• Encode for compatibility: -c:v libx264 -pix_fmt yuv420p -crf 18 -preset medium -movflags +faststart. A film without sound has no audio stream (-an), not a silent track. Sound is muxed in a separate step (section 10). Width and height must be even.
• Headless WebGL may fall back to software rendering, which is slow. Measure the time per frame on a short range first and plan the full render from it. Render previews at half resolution if needed, but the final at full size.
• Keep each render in a new versioned path; never overwrite the last good film until the new one passes its checks.
• Frame budget: before building the whole film, time one full-resolution frame of the busiest moment. Aim for roughly ≤ 300 ms/frame (a 100 s film at 30 fps is then 15 min per full render) so that several review passes fit. If a hand-written NumPy/PIL compositor is far slower, do not optimize it for hours: move the drawing to Canvas 2D or WebGL, which composite layers natively. In NumPy, avoid per-frame work on whole huge textures (boolean-mask assignment into multi-thousand-pixel float arrays, full-frame np.roll); crop to the visible window and precompute static layers once.
• Long renders: a 2-minute film at 30 fps is 3,600 frames. Measure ms/frame early and multiply. Render independent chunks in parallel with --start and --frames (each chunk to its own file, all from the same seek(t) code), then join them losslessly: list the chunks in chunks.txt (file 'part_000.mp4' …) and run ffmpeg -f concat -safe 0 -i chunks.txt -c copy video.mp4. Check the joined frame count.

Long jobs and background processes

• Smoke-test before a long run. Run any bake, simulation or render on a tiny case first and assert that it does something: state changes after N steps, the output file grows, an invariant holds. A stepping function whose result is never assigned bakes nothing for half an hour.
• Write each run to a new file name and print progress with flush=True to a log. Before you inspect a result, confirm it came from the run you just started (timestamp, a config line in the log), not from an older file.
• Record the PID of a background job (echo $! > build/sim.pid) and stop it with kill $(cat build/sim.pid). pkill -f <pattern> can match your own shell command and kill it.
• The machine may be shared with other jobs. Measure throughput on the real run and re-plan from that; do not assume an earlier measurement still holds.

5. Look at the frames

Pixels are the only evidence. Repeat this loop at least twice.

You know what the code is meant to draw, so you will tend to see it in the frame even when it is not there. Read every still in two steps:

• Cold read first. Describe the image as a stranger would, without thinking of the code: what is the main subject, could someone name it within