# HyperFrames Tutorial: Set Up Claude Code and Render Your First MP4

> To use HyperFrames, install Node.js 22 or later and FFmpeg, add HeyGen's plugin or skills to Claude Code, and ask for a video using /hyperframes. The agent writes an HTML page with timed clips and a paused animation timeline. Run npx hyperframes preview to watch it, npx hyperframes check to catch errors, and npx hyperframes render to make the MP4.

By Iris Tu, Founder of AdAnt. Updated 2026-11-15.
Canonical: https://adant.ai/guides/hyperframes-tutorial

This tutorial takes HyperFrames, HeyGen's open-source HTML-to-video framework, from an empty folder to a rendered MP4. Every command comes from HeyGen's README on GitHub and its documentation at hyperframes.heygen.com, read the day this guide is dated. The notes on what went wrong come from building AdAnt's own video skills on it. For what HyperFrames is and real videos made with it, see [HyperFrames](https://adant.ai/guides/hyperframes-ai-video).

## What do you need before you start?

**Node.js 22 or later, FFmpeg, and a coding agent that reads skills.** HeyGen's README lists the first two as the requirements. HyperFrames draws each frame in headless Chrome and FFmpeg encodes the frames into the video. One command checks the machine:

```bash
npx hyperframes doctor
```

It reports the CLI version, Node.js, FFmpeg, FFprobe, Chrome and Docker, and marks what is missing. If FFmpeg is the problem, HeyGen's troubleshooting page gives `brew install ffmpeg` on macOS and `sudo apt install ffmpeg` on Ubuntu or Debian.

For the agent, HeyGen's README names Claude Code, Codex, Cursor, Gemini CLI and IBM Bob, and says other agents that support skills work too. Claude Code's usage bills to your own Claude or Anthropic Console account, as HeyGen's Claude Code page points out. HyperFrames itself is Apache 2.0, with no per-render fees.

## Step 1: How do you install HyperFrames in Claude Code?

**Add HeyGen's plugin, or install its standalone skills in your project folder.** The plugin is the route HeyGen recommends for Claude Code:

```bash
claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes
```

Then start a new Claude Code session, or run `/reload-plugins` in the current one. With the plugin, the entry skill is `/hyperframes:hyperframes`.

Standalone skills suit Codex, Cursor and other agents as well. Run this in the project folder and choose Core Skills in the picker:

```bash
npx skills add heygen-com/hyperframes
```

Or install the core set for your user with no picker, which also suits a script or CI job: `npx hyperframes skills update`. It installs the skills from the release tag that matches your CLI version, so the skills and the CLI agree. With standalone skills, the entry skill is `/hyperframes`.

The core set is six skills: `/hyperframes` holds the render contract and the work loop, `/hyperframes-cli` the commands, `/hyperframes-registry` about 450 ready-made blocks such as transitions, captions and charts, and `/media-use` music, voice and footage. The other two, `/reverse-any-video` and `/style-sampling`, need the paid HyperFrames Pro plan.

## Step 2: How do you start a HyperFrames project?

**Ask your agent for a video, or scaffold the folder yourself with `init`.** This is HeyGen's first prompt for Claude Code, typed in an empty folder:

```text
Using /hyperframes:hyperframes, make a 10-second product intro for https://example.com.
```

With standalone skills, write `/hyperframes` instead, and swap the URL for the page the video should show. The agent builds the project in the folder, checks it and opens a local preview. For a longer film that tells a story, it first offers three storylines to pick from.

To start by hand:

```bash
npx hyperframes init my-video
cd my-video
```

`init` scaffolds a blank composition. It writes an `AGENTS.md` and an identical `CLAUDE.md` that tell a coding agent which commands preview, check and render the video, and it installs the core skills if they are missing. Its `package.json` scripts, `npm run dev`, `npm run check` and `npm run render`, call the exact CLI version that made the project. Add `--resolution portrait` for a vertical video, `--video video.mp4` to start from a clip (it transcribes the audio with Whisper and adds captions), or `--non-interactive` in a script or CI job.

## Step 3: What goes in the HTML page?

**A whole HTML document with a root element that names the video's id, length and size, timed clips inside it, and one paused animation timeline registered on the page.** Here is a four-second title card. We ran it through `lint`, `check` and `render` with HyperFrames 0.9.56, the latest release on the day this guide is dated, and it rendered to MP4:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <script src="https://cdn.jsdelivr.net/npm/gsap@3.15.0/dist/gsap.min.js"></script>
    <style>
      html, body { margin: 0; width: 1920px; height: 1080px; overflow: hidden; background: #000; }
      #root { display: flex; align-items: center; justify-content: center; }
      #title { color: #fff; font: 600 96px sans-serif; }
    </style>
  </head>
  <body>
    <div id="root" data-composition-id="intro" data-start="0" data-duration="4"
         data-width="1920" data-height="1080">
      <h1 id="title" class="clip" data-start="0" data-duration="4" data-track-index="0">
        Launch day
      </h1>
    </div>
    <script>
      const tl = gsap.timeline({ paused: true });
      tl.from("#title", { opacity: 0.2, y: 40, duration: 0.8 }, 0);
      window.__timelines = window.__timelines || {};
      window.__timelines["intro"] = tl;
    </script>
  </body>
</html>
```

Save it as `index.html` in the project folder, in place of the one `init` wrote. The README on GitHub shows the composition alone, a bare div, but as a project's `index.html` that fails `lint`: HeyGen's lint rules count a page with no doctype, html or body element as an error.

The title is already on screen at frame 0 and fades up from there. When we first started it from nothing at half a second, `check` passed with a craft warning, because the first frame is the thumbnail on social players.

## What rules does a HyperFrames page have to follow?

**Time comes from data attributes and a paused timeline, never from the page's own clock.** HeyGen's docs and lint rules come down to five:

- Every timed element carries `data-start` and `data-duration` in seconds, and `class="clip"`. The class is how HeyGen's browser editor and lint recognise a clip, and `lint` warns when it is missing.
- The timeline is created paused and registered under the same id as `data-composition-id`. One that plays on its own, or sits under another name, renders as a still picture.
- Nothing reads the clock. HeyGen's determinism rules ban `Date.now()`, unseeded `Math.random()` and fetching mid-render, because the renderer works out frame 90's time as 90 / fps and seeks every animation there.
- Media is described, not driven. Never call `play()` or `pause()` or set `currentTime`; to move a video, animate an element that wraps it.
- Files live in the project. Put images, video and sound in the `assets/` folder and point at them by relative path, such as `assets/logo.png`. A nested composition still writes paths from the project root.

GSAP is the usual choice, but the README lists CSS, Lottie, Three.js, Anime.js and the Web Animations API too, or your own frame adapter.

## Step 4: How do you preview and check the video?

**Run `preview` to watch and edit it in the browser, then `lint` and `check` before any render.**

```bash
npx hyperframes preview
npx hyperframes lint
npx hyperframes check
npx hyperframes snapshot --at 1.5,3
```

`preview` starts a local server with live reload and opens the browser editor, where you can also change the video by hand. `lint` reads the HTML without a browser, so it is fast. Its errors must be fixed before rendering, and its warnings are likely problems. `check` opens the page in a browser and sweeps it for runtime errors, failed requests, layout faults such as clipped or overflowing text, WCAG AA contrast and HeyGen's craft warnings. `snapshot` saves the frames at the times you name as PNGs, so you can look at a moment without a full render.

In AdAnt's [UI Card Promo](https://adant.ai/skills/ui-card-promo) skill, `npx hyperframes check` is the gate before every render. It runs beside the skill's own audit, which fails any text that is unbound from the data file, too small, clipped or out of frame.

## Step 5: How do you render HyperFrames to MP4?

**Run `render` in the project folder.** It writes an MP4 at the composition's frame rate, which is 30 fps unless `data-fps` says otherwise.

```bash
npx hyperframes render --output final.mp4
```

Without `--output`, the file goes under `renders/`. The flags people reach for, from HeyGen's rendering guide:

| You want | Add |
|---|---|
| A faster review copy | `--quality draft` |
| A larger master | `--quality high` |
| A higher frame rate | `--fps 60` |
| A transparent web overlay | `--format webm` |
| A ProRes file for editing | `--format mov` |
| A short looping preview | `--format gif --fps 15` |
| The same pixels on any machine | `--docker` |

Rendering never plays the video. For each frame the engine computes the time with integer math, seeks every animation to it and captures the pixels in headless Chrome. FFmpeg then encodes the frames and mixes in the sound from the page's audio and video elements. A slow machine takes longer, but it makes the same file. Fonts and Chrome versions still differ between computers, so HeyGen suggests Docker when the result must match to the pixel.

## What are the common HyperFrames errors and how do you fix them?

**Most come from a missing attribute or a script that fights the renderer, and `lint` names many of them.** From HeyGen's troubleshooting page, plus one we hit:

| What you see | Why | Fix |
|---|---|---|
| "No composition found" | `index.html` has no root with `data-composition-id`, width and height | Add them, or start again with `npx hyperframes init` |
| "FFmpeg not found" | FFmpeg is missing or not on the PATH | Install it, then run `npx hyperframes doctor` |
| `lint` reports `root_composition_missing_html_wrapper` | `index.html` is a bare fragment, with no doctype, html or body element | Wrap the composition in a whole HTML document |
| The animation is static | The timeline is not paused, or is registered under another id | Create it with `paused: true` and register it under the composition's id |
| Every render takes about 45 seconds longer | A composition never registers a timeline, so the renderer waits for one | Add `data-no-timeline` to it |
| A video freezes while its box moves | Its width, height, top or left is animated directly | Animate a wrapper element instead |
| Media plays out of sync | A script calls `play()`, `pause()` or sets `currentTime` | Remove it; HyperFrames owns playback |
| The render looks different from the preview | Fonts, remote media or the machine | Check fonts and media, or render with `--docker` |
| Claude Code does not see the skill | The session started before the install | Start a new session or run `/reload-plugins` |
| A brand font renders in a system face | HyperFrames 0.9.20 did not find the family named in `index.html` | Name each family in an inline style block in `index.html` |

When a render fails, HeyGen's order is `npx hyperframes doctor`, then `lint` and `check`, then a retry. For a bug report, HeyGen asks for the exact error, the steps to reproduce it, the HyperFrames version and your operating system.

## How do you get the same render next month?

**Render through the project's own scripts, which pin the CLI, and use Docker when pixels must match.** The `package.json` that `init` writes runs one exact version, as `npx --yes hyperframes@<version> render`, so `npm run render` uses the same CLI next month as it does today. A bare `npx hyperframes` runs a project's installed copy if there is one, or else fetches the latest release, so its output can change under you.

To see which version a project is on, open its `package.json`. To move it up on purpose, the scaffold's `AGENTS.md` gives two commands:

```bash
npx hyperframes@latest upgrade --project . --check
npx hyperframes@latest upgrade --project .
```

The first shows the change and the second rewrites the pins. Then run `npx hyperframes skills update`, which installs the skills from the release tag that matches the CLI, so the skills and the renderer agree. Set `HYPERFRAMES_SKIP_SKILLS=1` when something else manages the skills, such as a copy pinned to one commit.

Docker removes the machine: HeyGen's determinism page says it pins the Chromium version, the font set and the FFmpeg encoder. AdAnt's UI Card Promo example takes the same approach as the scaffold and pins an exact version in its own `package.json`.

The CLI has usage telemetry: command names, render performance and system details. `npx hyperframes telemetry disable` turns it off.

AdAnt, an AI social media marketing team, ships HeyGen's official skill at a pinned commit as the free [HyperFrames: HTML to Video](https://adant.ai/skills/hyperframes-html-to-video) download. It is an older copy, and `npx hyperframes skills update` installs the current one. Not every AdAnt video skill uses HyperFrames: [Narrated Explainer](https://adant.ai/skills/narrated-explainer) ships its own Playwright renderer so it can cue every picture to a word in the voiceover. For the other ways to turn a page into a video, see [HTML to video](https://adant.ai/guides/html-to-video).

## Frequently asked questions

### Do I need the HyperFrames Studio app?

No. The Studio app is free for Mac, Windows and Linux and runs your agent beside a live preview, but it needs a free HeyGen account. The CLI and a coding agent make the same kind of project in a folder on your computer.

### Can I use HyperFrames without Claude Code?

Yes. HeyGen's skills also work in Codex, Cursor, Gemini CLI and other agents that read skills, and you can write the page yourself and run init, preview and render by hand. In Claude.ai or ChatGPT, HeyGen's connector builds and renders the video in your HeyGen account, without a project folder.

### Why is my first HyperFrames render slow?

The first check or render downloads a headless Chrome and its bundled fonts into a cache folder. If every render is about 45 seconds slower than it should be, a composition probably registers no timeline: add data-no-timeline to it.

### How do I make a vertical video?

Start the project with npx hyperframes init my-video --resolution portrait, which sets 1080x1920. Without a data-fps attribute, the CLI renders at 30 fps.

### Is HyperFrames free?

The framework is Apache 2.0, and its README says there are no per-render fees. Two of its core skills, Reverse Any Video and Style Sampling, need the paid HyperFrames Pro plan.
