Up to 50% off yearly plansSee yearly prices

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

Updated · 9 min read

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.

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 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 wantAdd
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 seeWhyFix
"No composition found"index.html has no root with data-composition-id, width and heightAdd them, or start again with npx hyperframes init
"FFmpeg not found"FFmpeg is missing or not on the PATHInstall it, then run npx hyperframes doctor
lint reports root_composition_missing_html_wrapperindex.html is a bare fragment, with no doctype, html or body elementWrap the composition in a whole HTML document
The animation is staticThe timeline is not paused, or is registered under another idCreate it with paused: true and register it under the composition's id
Every render takes about 45 seconds longerA composition never registers a timeline, so the renderer waits for oneAdd data-no-timeline to it
A video freezes while its box movesIts width, height, top or left is animated directlyAnimate a wrapper element instead
Media plays out of syncA script calls play(), pause() or sets currentTimeRemove it; HyperFrames owns playback
The render looks different from the previewFonts, remote media or the machineCheck fonts and media, or render with --docker
Claude Code does not see the skillThe session started before the installStart a new session or run /reload-plugins
A brand font renders in a system faceHyperFrames 0.9.20 did not find the family named in index.htmlName 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 download. It is an older copy, and npx hyperframes skills update installs the current one. Not every AdAnt video skill uses HyperFrames: 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.

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.

The studio dispatch

One useful idea on AI-made ads, every other week. No fluff.