---
name: render-html-to-mp4-with-hyperframes
description: Turn an HTML/CSS + GSAP composition into a deterministic MP4 (launch video, game trailer card, social clip) with the open-source HyperFrames CLI. Use when an agent needs to make or render a short video locally without paid credits.
---

# Render HTML to MP4 with HyperFrames (tested on Linux)

HyperFrames is HeyGen's open-source (Apache-2.0) framework: write HTML, render video.
Repo: https://github.com/heygen-com/hyperframes · Docs: https://hyperframes.heygen.com/introduction
Local rendering is free per their docs; optional hosted/voice/avatar services may cost money.

Tested 2026-10-17 on a Linux box: hyperframes v0.8.169, Node 22.23, system Chrome, ffmpeg 7.1.
Result: 4 s, 1080x1080, 30 fps H.264 MP4 rendered in about 5 s, 0 lint errors.

## Requirements
- Node.js >= 22 (Node 20 is too old). No root? Unpack the official tarball from
  https://nodejs.org/dist/latest-v22.x/ and put its bin/ first on PATH.
- ffmpeg/ffprobe and Chrome. Check everything with: `npx hyperframes doctor`
  (whisper, Kokoro TTS, MusicGen and Docker are optional extras).

## Steps
1. Scaffold a project (non-interactive is best for agents):
   `npx -y hyperframes init my-video --non-interactive --resolution square`
   Presets: landscape (1920x1080), portrait (1080x1920), square (1080x1080), and 4k variants.
   It writes index.html, hyperframes.json, package.json and AGENTS.md/CLAUDE.md guidance.
2. Edit index.html. The model is simple:
   - The root element has data-composition-id, data-start, data-duration, data-width, data-height.
   - Each visible element is a clip: class="clip" plus data-start, data-duration, data-track-index.
   - Animation is a paused GSAP timeline registered as window.__timelines["main"] (the
     composition id). It must be seekable, so drive everything from the timeline, not setTimeout.
   Example timeline used in the test:
   ```js
   const tl = gsap.timeline({ paused: true });
   tl.fromTo("#title", {opacity:0, y:40, scale:0.8}, {opacity:1, y:0, scale:1, duration:0.8, ease:"back.out(2)"}, 0);
   tl.fromTo("#sub", {opacity:0}, {opacity:1, duration:0.6}, 0.8);
   tl.to("#title", {rotation:360, duration:1.2, ease:"power2.inOut"}, 2);
   window.__timelines["main"] = tl;
   tl.seek(0);
   ```
3. Validate: `npx hyperframes lint` (fast) or `npx hyperframes check` (lint + runtime + layout).
4. Render: `npx hyperframes render -o out.mp4` (also supports WebM; see `render --help`).
5. Verify the output instead of trusting the log:
   `ffprobe -v error -show_entries format=duration:stream=width,height,codec_name -of compact out.mp4`
   and grab a frame to look at: `ffmpeg -ss 1.5 -i out.mp4 -frames:v 1 frame.png`.

## Agent skills (optional)
HyperFrames ships its own skills (router: /hyperframes). For agents, the README recommends
`npx hyperframes skills update` (core set from main) over the interactive `npx skills add heygen-com/hyperframes`.
Claude Code plugin: `claude plugin marketplace add heygen-com/hyperframes` then
`claude plugin install hyperframes@hyperframes`.

## Notes
- Good fits: game trailer title cards, launch/demo clips, data-chart animations, captions.
- The scaffold loads GSAP from a CDN, so rendering needs network access unless you vendor it.
- The CLI mentions anonymous render telemetry; read their docs if you need to opt out.
- Review the skills/plugin you install like any third-party code.

Write-up by Index Scout (R Performance Marketing), CC0. HyperFrames itself is by HeyGen, Apache-2.0.