HTML render
Turns a web page into a video by painting it one frame at a time. The page is a pure function of the frame number, so the result is deterministic, never drops frames and lines up with audio to the frame.
When to use it
- Titles, kinetic text, charts, UI mock-ups, explainers: anything you can draw with HTML, CSS, SVG or canvas.
- Not for screen recordings of live sites, and not for pages that animate by themselves (CSS transitions,
requestAnimationFrameloops, videos): those must be rewritten to follow the contract below.
Command
node skills/html-render/scripts/render.mjs <page.html> --out out.mp4 \
[--audio mix.wav] [--width 1080 --height 1920 --fps 30] \
[--frames N | --duration S] [--data plan.json]
node skills/html-render/scripts/render.mjs <page.html> --still 1.5,3.0 [--stills-dir dir] [--data plan.json]
Needs Node 20+, ffmpeg, a local Chrome or Chromium, and npm install run once in skills/html-render/
(it installs puppeteer-core, which drives the Chrome that is already installed; nothing is downloaded).
If Chrome is not found, set CUTROOM_CHROME to its executable.
Length, in order of priority: --frames, --duration, window.renderInfo.frames, the length of --audio.
The output is H.264 high, yuv420p, bt709, with +faststart; with --audio, AAC 48 kHz stereo, padded or cut
to the video length. The script prints a JSON report and fails if the frame count or size does not match.
The page contract
The page must:
- Set
window.renderReady = trueonce everything is built (fonts and images loaded). If it cannot build, setwindow.renderError = "reason"instead, and the render stops with that message. - Define
window.renderFrame(i), which paints framei. It may return a promise. - Optionally set
window.renderInfo = { frames, fps }so the command line does not need a length.
Before the page loads, the renderer injects:
window.RENDER_DATA: the parsed--dataJSON, ornull. Put texts and timings here, not in the HTML.window.RENDER_CONFIG:{ width, height, fps }. Readfpsfrom here.
Minimal page:
<div id="box" style="width:200px;height:200px;background:#fff;will-change:transform"></div>
<script>
const fps = window.RENDER_CONFIG?.fps ?? 30;
window.renderInfo = { frames: 3 * fps, fps };
window.renderFrame = (i) => {
const t = i / fps; // the only clock
const p = Math.min(1, t / 1.2), eased = 1 - (1 - p) ** 3;
document.getElementById("box").style.transform = `translateX(${eased * 600}px)`;
};
document.fonts.ready.then(() => { window.renderFrame(0); window.renderReady = true; });
</script>
Rules for authoring a page
- Everything is computed from
t = i / fps. NoDate.now(),performance.now(),setTimeout,setInterval,requestAnimationFrame, CSStransitionoranimation, and no state carried from one frame to the next.renderFrame(120)must paint the same picture whether or not frames 0 to 119 were painted first: stills depend on it. - Randomness must be seeded. Use a small seeded generator, never
Math.random(). - Move things with
transform(and fade withopacity), notleft/top/width. Transforms are sub-pixel and do not reflow; layout properties snap to whole pixels and make slow motion judder. Give moving elementswill-change: transform. - Lay text out once. For typed or revealed text, put the full text in the DOM from frame 0 and hide the
part that has not appeared yet (
visibility: hidden), so lines never re-wrap mid-animation. - Write easing as functions (
1 - (1 - p) ** 3and friends) and clamp progress to 0..1. - Timings come from data. When motion must match sound, compute both from the same numbers: put event
times in the
--dataJSON and build the audio from those same times. - Use local or system fonts, loaded before
renderReady. Wrap setup intry/catchand report failures throughwindow.renderError. - Size the layout for the target frame (default 1080 x 1920). On vertical social video keep text away from the top 12 % and the bottom 20 %.
Workflow
- Write the page and its data JSON.
- Preview with stills first:
--stillwith three to six instants that cover every scene. It takes a second or two. Open the PNGs and check layout, overflow, contrast and that nothing overlaps. - Fix and repeat until the stills are right.
- Render the video, with
--audioif there is a soundtrack. - Check the JSON report (size, frames, seconds) and look at one or two frames of the result.
A full render takes roughly 20 to 40 frames per second of machine time for a simple page at 1080 x 1920.
Troubleshooting
- "The page never set window.renderReady": a script error or a resource that never loaded. Page errors are included in the message.
- Text or motion flickers between frames: something still depends on real time or on the previous frame.
- Different results on two machines: a font that is not installed on one of them. Ship the font file next
to the page and load it with
@font-face. - In containers, Chrome may need
CUTROOM_CHROME_ARGS="--no-sandbox".