Skip to main content
All posts
Engineering

How to Render HTML and CSS Animations to Frame-Accurate MP4 Without Dropped Frames

Why screen recorders and naive headless loops drop frames on CSS keyframes, ECharts and web fonts — and how to convert wall-clock HTML animations into deterministic HyperFrames MP4 exports

Modern browsers are extraordinarily good layout and vector motion engines: CSS grid, custom properties, SVG paths, variable fonts, and Canvas libraries like ECharts can render sharper typography and smoother data transitions than almost any pixel-based AI video generator.

Yet the moment an engineering or product team tries to turn an interactive HTML animation into a clean 1080p MP4 — whether with MediaRecorder, OBS screen capture, or a quick Puppeteer screenshot loop — the output stutters, drops beats, or flashes unstyled fallback text on frame zero.

This guide breaks down the four root causes of dropped frames in browser-to-video pipelines and shows how to refactor wall-clock HTML/CSS/JS scenes into a deterministic, seekable HyperFrames composition that exports frame-accurate H.264 MP4 locally.

Why recording a live browser tab drops frames

A live browser tab advances on wall-clock time: CSS animations tick alongside OS display refreshes, JavaScript timers fire whenever the main thread is free, and network assets arrive asynchronously. Video encoders, by contrast, expect exact discrete timestamps (t = frame / fps, such as 0.000s, 0.0333s, 0.0667s at 30 fps).

When those two clocks are not locked together, four classic failure modes appear:

Failure modeWhat happens in naive captureDeterministic fix
setTimeout / requestAnimationFrame driftCPU load during screenshot encoding delays JS callbacks, shifting reveals 200–600 ms late or skipping steps entirelyDrive every state change from an explicit seek(t) function rather than wall-clock timers
Unpaused CSS @keyframesAnimations keep running while headless Chrome encodes PNG frames, causing speedups or jitterBind progress to timeline-driven CSS variables or seekable clip windows (data-start, data-duration)
Remote web font FOUTFrame 0 renders in system sans-serif before Google Fonts or WOFF2 files finish loadingAwait document.fonts.ready and bundle local font assets before frame capture starts
Async Canvas / ECharts tweensECharts starts an internal 1,000 ms tween on mount, so frame 0 is blank and mid-render frames tearDisable internal chart animation in render mode and interpolate series growth directly from t

Refactoring wall-clock HTML into a seekable HyperFrames composition

Instead of filming a running page in real time, HyperFrames treats an index.html file as a multi-track timeline composition. The renderer steps through every frame k from 0 to totalFrames - 1, seeks the composition to t = k / fps, waits for layout and paint to settle, and pipes the exact frame to FFmpeg.

1. Declare composition geometry and clip windows

At the root of the HTML document, declare the canvas dimensions, frame rate, and total duration. Inside it, every scene and timed layer carries class="clip", a unique id, data-start, data-duration, and data-track-index:

<div
  id="deck"
  data-composition-id="q4-architecture-explainer"
  data-width="1920"
  data-height="1080"
  data-fps="30"
  data-duration="18"
>
  <!-- Track 0: consecutive non-overlapping scenes -->
  <section
    id="s1"
    class="clip cm-slide"
    data-start="0"
    data-duration="6"
    data-track-index="0"
  >
    <h1 id="s1-title" class="clip" data-start="0.2" data-duration="5.8" data-track-index="1">
      Q4 Latency Cut from 420 ms to 118 ms (-71.9%)
    </h1>
  </section>

  <section
    id="s2"
    class="clip cm-slide"
    data-start="6"
    data-duration="12"
    data-track-index="0"
  >
    <div id="s2-chart" class="clip cm-chart" data-start="6.4" data-duration="11.6" data-track-index="2"></div>
  </section>

  <!-- Track 8: synced narration; Track 9: backing music -->
  <audio id="vo-s1" class="clip cm-voiceover" src="audio/voice-s1.mp3" data-start="0" data-duration="5.2" data-track-index="8"></audio>
</div>

Following a consistent track convention keeps multi-layer compositions easy to inspect in a visual timeline editor:

  • Track 0: Base scenes (section.cm-slide), consecutive and non-overlapping (start of scene n + 1 equals start + duration of scene n).
  • Track 1: Typography, callouts, and kinetic captions nested inside their parent scene's time window.
  • Track 2: Data visualizations and ECharts canvases.
  • Track 3: Interactive blocks (quizzes, parameter filters, drag-and-drop) whose solved path plays automatically in MP4 renders.
  • Tracks 7 / 8 / 9: Cut-point sound effects (cm-sfx), scene voiceover (cm-voiceover), and background music (cm-music).

2. Replace setTimeout with deterministic seek(t) interpolation

Compare a fragile wall-clock counter against a frame-accurate seek handler. In wall-clock JS, CPU spikes ruin timing:

// Fragile: wall-clock timer drifts whenever frame capture blocks the thread
let current = 0;
const timer = setInterval(() => {
  current += 12;
  el.textContent = `${Math.min(current, 420)} ms`;
  if (current >= 420) clearInterval(timer);
}, 16);

When refactored to a pure function of composition time t (in seconds), frame 45 at 30 fps (t = 1.500s) produces the exact same DOM state on a laptop, a CI runner, or a re-render six months later:

// Deterministic: pure function of seek time t (seconds)
function easeOutCubic(x) {
  return 1 - Math.pow(1 - Math.min(Math.max(x, 0), 1), 3);
}

window.__cm = {
  seek(t) {
    const start = 0.4;
    const duration = 1.4;
    const progress = easeOutCubic((t - start) / duration);
    const value = Math.round(420 - (420 - 118) * progress);
    el.textContent = `${value} ms`;
  },
};

In Claude Motion's runtime, window.__cm.seek(t) automatically disables asynchronous ECharts tweens during render mode and drives chart bar growth (chartGrow), number roll-ups (countUp), and step reveals (cm-step) directly from the seek timestamp.

Automating build, render, and codec verification from the CLI

If you already work in Claude Code, OpenAI Codex, or Cursor, you do not have to wire data-start attributes or FFmpeg flags by hand. Installing the claudemotion skill lets your coding agent ingest a Markdown spec, HTML page, or blog post, compose timed scenes, and run both structural and binary MP4 checks locally:

# 1. Initialize a local project and extract structured facts + numbers
npx -y claudemotion@latest init ./claudemotion/latency-demo
npx -y claudemotion@latest ingest ./docs/latency-postmortem.md --project ./claudemotion/latency-demo --lang en

# 2. Compose timed scenes and verify slot capacity + verbatim number accuracy
npx -y claudemotion@latest compose scenes.json --project ./claudemotion/latency-demo
npx -y claudemotion@latest check --project ./claudemotion/latency-demo

# 3. Render deterministic MP4 via HyperFrames (draft | standard | high)
npx -y claudemotion@latest render --project ./claudemotion/latency-demo --quality high

# 4. Run strict post-render technical verification on out/render.mp4
npx -y claudemotion@latest verify-export ./claudemotion/latency-demo/out/render.mp4 --project ./claudemotion/latency-demo

Two verification gates protect production output before you publish or hand off a file:

  1. claudemotion check (pre-render DOM & data gate): Confirms every clip has a unique id and valid timing window, checks character capacities (counting CJK glyphs at double width so text never overflows or shrinks arbitrarily), and verifies that every number on screen exists verbatim in content.json.
  2. claudemotion verify-export (post-render MP4 binary gate): Runs ffprobe and ffmpeg against out/render.mp4 to verify H.264 (yuv420p pixel format so QuickTime, Safari, Slack, and X play it without black screens), exact width/height, nominal and average frame rate, duration tolerance, AAC audio stream policy, full-stream error-free decode (ffmpeg -xerror -err_detect explode), three-point seek MD5 frame decode (seek-first, seek-middle, seek-last), and an immutable SHA-256 digest.

When to use HTML/HyperFrames vs React/Remotion

If your team already maintains a shared React component monorepo and renders parameterized videos in AWS Lambda, Remotion fits naturally into that stack. When your starting point is a Markdown document, PDF report, .docx spec, or standalone HTML prototype — and you want one local composition that works as both an interactive web link (with clickable source citations, filters, and quizzes) and a verified MP4 — HyperFrames with Claude Motion skips the per-video React bundler setup completely.

Explore 287 MOTION.md shot-timing blueprints for pacing inspiration, read more on the HTML to video workflow, or install Claude Motion in your coding agent to render your first composition locally.

Note: Claude Motion (claudemotion.design) is an independently operated product and has no relationship with Anthropic, PBC or Claude.