HyperFrames is HeyGen’s open-source video engine that turns an HTML document into a rendered video file. You write a composition as HTML and CSS, animate it with a GSAP timeline, and the renderer steps that timeline frame by frame in a headless browser, capturing each frame and encoding them to MP4. Its own one-line description is “Write HTML. Render video. Built for agents.” It was open-sourced on 2026-03-10 under Apache-2.0 and, five months later, sits at roughly 41,600 GitHub stars and ~904,000 npm downloads a month.

This guide covers what the engine actually does, the one design constraint that explains all its odd behaviour, the failure modes that cost us the most time shipping a product on it, and how to get HyperFrames output without writing HTML at all.

The core idea: video as a seekable document

Most programmatic-video tools ask you to describe a video as a data structure. HyperFrames asks you for a web page.

That sounds like a gimmick until you notice what it buys. A browser already has a layout engine, a typography engine, SVG, WebGL, video decoding and a mature animation library. Rebuilding any one of those inside a video tool is a career; borrowing all of them costs an <iframe>. So the composition is a document, and the animation is a GSAP timeline attached to it.

The renderer then does something that is not screen recording. It never plays your animation in real time. Instead it:

  1. loads the composition in a headless browser,
  2. pauses the GSAP timeline,
  3. seeks it to the exact time of frame n,
  4. screenshots the result,
  5. repeats for every frame, and
  6. hands the frames to FFmpeg to encode.

This is the whole engine in six steps, and every strange rule you will run into follows from step 3.

Why “seekable” is the constraint that matters

Because the renderer jumps the timeline to arbitrary times rather than playing through it, your composition must produce the correct picture at any time value, in any order, with no history.

That is a much stronger requirement than “the animation looks right”. It is what makes rendering deterministic — the same composition and the same frame number always produce identical pixels — and determinism is what allows frames to be split across parallel workers, which is how the same project renders locally or on AWS Lambda without changing.

It also means a composition can be completely wrong while previewing perfectly, because previewing plays forward and rendering does not.

Six ways a composition renders wrong with no error

This is the part that is not in anyone’s quickstart, and it is where we lost the most time integrating HyperFrames into ViralMint’s Motion Graphics mode. Every item below produces a broken video with no warning, no exception and no failed build — the render succeeds and the output is wrong.

1. A fromTo whose destination omits opacity. If an element starts at opacity: 0 and the destination object never sets opacity: 1, it previews correctly and renders invisible on a cold worker. This is the single most common cause of “my text is missing”.

2. fromTo back-renders its start pose. An element you intended to appear at 3 seconds is already on screen at frame 0, wearing its “from” state, because seeking to time 0 applies that pose.

3. A tl.set() at position 0 may not have applied at frame 0. The set and the first captured frame race; sometimes the frame wins.

4. Relative values ("+=") with a second writer. Relative tweens accumulate from wherever the property currently is. Seek out of order and “wherever it currently is” stops being predictable.

5. An SVG draw-on measured before its d attribute is set. The path length reads as zero, the stroke animation is silently dead, and the shape simply never draws.

6. Geometry measured inside a tween callback. Callbacks re-run on every seek, so a measurement taken there is recomputed thousands of times against a moving target.

There is a seventh, subtler one: Math.random() breaks determinism. Two workers rendering adjacent frame ranges produce different “random” values and the seam is visible. The fix is a seeded PRNG — we use mulberry32 with integer-frame quantisation — so imperfection stays reproducible rather than being banned outright.

If you take one thing from this article: when a HyperFrames render looks wrong, don’t debug the animation. Ask what in it isn’t seekable.

What good motion actually requires

HeyGen’s own documentation is unusually opinionated about motion craft, and the summary line is worth quoting: “nothing stops, the camera acts, action overlaps, and imperfection stays reproducible.”

In practice that means a few things that separate output which reads as designed from output which reads as generated:

  • Nothing ever fully stops. A frozen final second is the clearest tell of cheap motion; elements keep a 1–2% breathing idle.
  • The camera is an actor. One continuous, slow move across the scene, not a static frame with things moving inside it.
  • Action overlaps. Supporting elements start before the focal element finishes; entrances ease out, exits ease in.
  • One idea per 1.5–4 seconds. Faster reads as a demo reel; slower reads as a screensaver.

None of that is enforced by the engine. It is the difference between a composition that technically renders and one worth publishing, which is why the authoring step matters as much as the rendering step.

Using HyperFrames without writing code

HyperFrames is explicitly “built for agents” — the intended workflow is that you prompt a coding agent, it writes the composition, and you render it with the CLI:

npx skills add heygen-com/hyperframes --full-depth
npx hyperframes preview
npx hyperframes render --output video.mp4

That is a good developer workflow and a poor one for anybody else. It assumes Node, a coding agent subscription, comfort reading GSAP, and the patience to learn the six failure modes above the hard way.

ViralMint replaces the authoring step with AI Compose. You describe the video in plain language — “a kinetic-typography hook that counts up to 1M subscribers in my brand teal” — and a cloud model writes the real composition (layout, palette, beat timing, GSAP tweens) into an embedded HyperFrames studio that live-reloads so you see it immediately. The important part is what you get back: editable code, not a template. You can open the composition, change a colour, retime a beat, or rewrite a scene by hand, and the studio is the same one a developer would use.

Rendering still happens on your own machine — headless Chrome plus FFmpeg, exactly as described above — so there is no per-second cloud render bill and no watermark. Each AI Compose costs $0.10 from prepaid credits and each finished render imports for $0.03, with no subscription. The engine installs on demand as a plugin (a portable Node runtime plus the pinned package) rather than shipping inside the app.

Two honest limits worth knowing. Rendering at the 4K supersample presets is genuinely slower — in our measurements a verification render took about 35 seconds versus 11 at 1080p — which is why draft renders skip it. And AI Compose is a cloud call, so it is the one step in the pipeline that is not local.

HyperFrames vs the alternatives

vs Remotion. Remotion is the established programmatic-video framework and describes video as React components. The practical difference is licensing: Remotion is free for individuals and companies up to three people, and from four people requires a paid Company License — $0.01 per render with a $100/month minimum, or $25/month per seat. HyperFrames is Apache-2.0 with no team-size threshold.

vs After Effects. After Effects is a far deeper tool with decades of ecosystem behind it. HyperFrames’ advantage is that a composition is text: it diffs, it version-controls, it can be generated and edited by a model, and it renders headlessly in CI. If your work is bespoke keyframe animation, After Effects wins. If it is the same motion design regenerated with different content, a document beats a project file.

vs template sites. Canva and Renderforest are faster for a one-off and produce output that looks like everyone else’s, because it is everyone else’s. A HyperFrames composition starts from your brief.

Where to start

If you write code, start with the official HyperFrames quickstart — and read the seekability section above first; it will save you an afternoon.

If you don’t, install ViralMint, open Motion Graphics, and describe what you want. Same engine, same local render, no HTML.