Communitygithub.com

html-render

Renders an HTML page to an MP4, frame by frame, with headless Chrome and ffmpeg, so motion graphics written in HTML/CSS/JS come out identical on every run and in sync with an audio track. Use it when the user says "render this page to video", "make a video from HTML", "animate this in HTML and export it", "motion graphics with code", "render the composition" or asks for preview stills of an HTML animation.

O que é html-render?

html-render is a Claude Code agent skill that renders an HTML page to an MP4, frame by frame, with headless Chrome and ffmpeg, so motion graphics written in HTML/CSS/JS come out identical on every run and in sync with an audio track. Use it when the user says "render this page to video", "make a video from HTML", "animate this in HTML and export it", "motion graphics with code", "render the composition" or asks for preview stills of an HTML animation.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MIQUELZAVALA/cutroom/tree/HEAD/skills/html-render

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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, requestAnimationFrame loops, 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:

  1. Set window.renderReady = true once everything is built (fonts and images loaded). If it cannot build, set window.renderError = "reason" instead, and the render stops with that message.
  2. Define window.renderFrame(i), which paints frame i. It may return a promise.
  3. 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 --data JSON, or null. Put texts and timings here, not in the HTML.
  • window.RENDER_CONFIG: { width, height, fps }. Read fps from 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. No Date.now(), performance.now(), setTimeout, setInterval, requestAnimationFrame, CSS transition or animation, 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 with opacity), not left/top/width. Transforms are sub-pixel and do not reflow; layout properties snap to whole pixels and make slow motion judder. Give moving elements will-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) ** 3 and 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 --data JSON and build the audio from those same times.
  • Use local or system fonts, loaded before renderReady. Wrap setup in try/catch and report failures through window.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

  1. Write the page and its data JSON.
  2. Preview with stills first: --still with 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.
  3. Fix and repeat until the stills are right.
  4. Render the video, with --audio if there is a soundtrack.
  5. 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".

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Habilidades Relacionadas