HyperFrames tutorial: HTML to MP4 with an AI agent

HyperFrames is an open-source framework from HeyGen that turns HTML, CSS and animations into video. You build a page the size of the frame, say when each element is on screen, and the renderer steps through time in a headless Chrome and encodes the frames with FFmpeg. It is released under Apache 2.0.

This tutorial makes a five-second title card. We ran every command here with HyperFrames 0.8.192.

Step 1: set up

• Node.js 22 or newer (node -v to check)
• FFmpeg on your PATH (brew install ffmpeg, winget install ffmpeg or apt install ffmpeg)
• Chrome comes with the first render. If a render says Chrome is missing, run npx hyperframes browser ensure.

npx hyperframes init my-video
cd my-video

The project holds an index.html, a hyperframes.json and a package.json with dev, check and render scripts. init also writes CLAUDE.md and AGENTS.md, so an agent you start in the folder knows how the project works.

Step 2: write the composition

Replace index.html with this. The root element sets the frame and the length. Every child with the clip class says when it appears (data-start), how long it stays (data-duration) and its row in the timeline (data-track-index). Times are in seconds.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=1920, height=1080" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <style>
      html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: #111216; }
      #root { position: relative; width: 100%; height: 100%; color: #f5f5f2; font-family: sans-serif; }
      .clip { position: absolute; left: 160px; }
      #title { top: 380px; font-size: 160px; font-weight: 800; letter-spacing: -0.04em; }
      #sub { top: 620px; font-size: 48px; color: #ff5b2e; }
    </style>
  </head>
  <body>
    <div id="root" data-composition-id="main" data-start="0" data-duration="5"
         data-width="1920" data-height="1080">
      <h1 id="title" class="clip" data-start="0" data-duration="5" data-track-index="0">Ship it today.</h1>
      <p id="sub" class="clip" data-start="1" data-duration="4" data-track-index="1">Version 2 is out</p>
    </div>
    <script>
      const tl = gsap.timeline({ paused: true })
      tl.from('#title', { y: 60, duration: 0.6, ease: 'power3.out' }, 0)
      tl.from('#sub', { x: -40, opacity: 0, duration: 0.5, ease: 'power2.out' }, 1)
      tl.to('#root', { opacity: 0, duration: 0.4 }, 4.6)
      window.__timelines['main'] = tl
    </script>
  </body>
</html>

• The timeline is created paused and registered on window.__timelines under the composition’s id. HyperFrames seeks it to each frame’s time, so the video never depends on how fast your machine is.
• GSAP is one option. The README also lists CSS animations, the Web Animations API, Lottie, three.js and Anime.js.
• The title is on screen at 0 seconds and only slides into place. check warns when the first frame is empty, because social players use it as the thumbnail.

Step 3: preview and check

npx hyperframes preview
npx hyperframes check

preview opens the project in your browser with live reload. check lints the file, plays it in headless Chrome, and reports layout problems, text that fails contrast and craft issues such as the empty first frame. Fix what it finds before you render.

To look at single moments, save stills: npx hyperframes snapshot --at 0.3,1.6,4 -o snapshots writes a PNG for each time.

Step 4: render

npx hyperframes render --quality draft -o renders/intro.mp4

Our run wrote a five-second 1920×1080 H.264 MP4 at 30 frames a second. Some options worth knowing:

• --quality draft for quick checks, delivery for the final file.
• --fps 60 for smoother motion. Without it, the root’s data-fps is used, or 30.
• --format webm or --format mov for video with transparency, and --format gif for a short loop.
• --resolution portrait for 1080×1920, if your layout is built for it.

Fonts and audio

HyperFrames bundles some font families, and npx hyperframes docs compositions lists them. For any other font, add an @font-face that points at a file in the project, so every render uses the same one.

Sound is an <audio> element on the timeline, with the same data-start, data-duration and data-track-index, plus data-volume. The renderer mixes it into the MP4. Use only music you have a license for.

<audio src="assets/track.mp3" data-start="0" data-duration="5" data-track-index="2" data-volume="0.5"></audio>

Hand it to an agent

Because a composition is plain HTML, any coding agent can write one. There are two ways to give it the know-how:

• HyperFrames’ own skills. npx hyperframes skills update installs them for Claude Code, Codex, Cursor, Gemini CLI and other agents. Then ask, for example, “Using /hyperframes, create a 15-second intro about our launch.”
• A Lookbk video skill. It adds a finished design on top: a template, a brief your agent fills in, scripts that check it, and a version of HyperFrames pinned so the result doesn’t change under you.

video

Launch Scene KitClaude CodeCodexCursor+3 more agents

Free

video

Kinetic Title DropClaude CodeCodexCursor+3 more agents

video

Changelog ReelClaude CodeCodexCursor+3 more agents

Kinetic Title Drop is free. How to make videos with Claude Code walks through a first render with it, and the Launch Films series builds full launch videos from your real screens.

Common problems

• The render hangs, or shows a still frame, with an error about GSAP

  Chrome couldn’t load GSAP from cdn.jsdelivr.net. Run npm i gsap@3.14.2, copy node_modules/gsap/dist/gsap.min.js into assets/vendor/, and point the <script src> at it.

• check reports text out of the frame or overlapping

  Shorten the text or make it smaller. The frame is a fixed size, so long words don’t wrap the way they would on a web page.

• Motion looks jerky in the MP4 but fine in the browser

  Something moves on real time instead of the timeline, such as a setInterval or your own requestAnimationFrame loop. Drive it from the paused timeline.