HyperFrames CLI: Install, Commands and Limits
Which HyperFrames the CLI belongs to
The HyperFrames CLI is the command-line renderer from the open-source HyperFrames framework published by HeyGen under the Apache 2.0 licence. It takes HTML, CSS and JavaScript compositions and renders them into an MP4 through headless Chrome plus FFmpeg.
This site, hyperframes.net, is a different product that happens to share the name: a hosted, no-install studio that turns a prompt or a photo into a clip. There is no CLI here and nothing to compile. If you arrived looking for install instructions, this page is the map — the commands below are the official framework's, and the last section says when a browser studio is the shorter path.
Requirements before npm install
| Requirement | Why it matters |
|---|---|
| Node.js 22 or newer | The CLI's package targets modern Node; older runtimes fail on install, not at render time |
FFmpeg on PATH | The renderer shells out to FFmpeg to encode frames; a missing binary fails at the last step of a long render |
| A browser binary | Headless Chrome drives the frame stepping; hyperframes doctor checks it |
| Disk space for frames | A 1080p30 render writes frames before encoding |
No account is needed to render locally. A HeyGen account or API key is only involved for cloud rendering, HeyGen voices and avatars, and the hosted Studio — the local path is free.
Install
# install globally
npm install -g hyperframes
# or run without installing
npx hyperframes <command>
# verify the environment
npx hyperframes doctorRun doctor first. It reports the Node version, the browser it can launch and the FFmpeg it can reach, which are the three things that break a first render.
The commands that do the work
| Command | What it does |
|---|---|
hyperframes init my-video | Scaffolds a project with a composition and config |
hyperframes preview | Serves the project and opens Studio so you can scrub the timeline |
hyperframes render -o output.mp4 | Renders the project's composition to a file |
hyperframes render -c ./promo.html -o promo.mp4 | Renders one specific composition file |
hyperframes lint | Checks the composition for timing and structure problems before a render |
hyperframes compositions | Lists what can be rendered in the project |
hyperframes add <block> | Drops a catalog block — flash-through-white, data-chart, instagram-follow — into the project |
hyperframes capture <url> | Captures a live page as a composition source |
hyperframes benchmark | Measures render performance on your machine |
hyperframes cloud render | Renders on remote infrastructure instead of locally |
The default output is 1920×1080 at 30 fps. preview opens the Studio on localhost:3002.
A first render in five minutes
npx hyperframes init my-video
cd my-video
npx hyperframes preview # scrub the timeline at localhost:3002
npx hyperframes lint # catch timing problems before you wait
npx hyperframes render -o out.mp4The composition is a plain HTML file. Animation is seekable — GSAP, CSS transitions, Lottie, Three.js, Anime.js, WAAPI or a custom adapter — and the renderer steps the timeline frame by frame rather than recording a live browser session. That is what makes a render deterministic: the same composition produces the same file twice.
For programmatic use, the hyperframes npm package is CLI-only. Importing a render into your own Node code means using @hyperframes/producer alongside @hyperframes/core and @hyperframes/engine.
Where a first render actually fails
- FFmpeg not found. It must be on
PATH, not just installed. The render runs the encoding step last, so the failure appears after a full frame pass. - Node older than 22. Symptoms show up during install or on the first import, not as an obvious version error.
- Infinite CSS animations. A composition that loops forever has no defined end frame; give every animated property an explicit duration.
- Web fonts that load after the first frame. Text reflows mid-render. Embed or preload the font in the composition.
lintskipped. The lint pass exists to catch overlapping tracks and zero-length clips, which render as a silently blank stretch rather than an error.
When the CLI is the wrong tool
The CLI is right when the video is a function of data you already have in code: turning a template plus a spreadsheet into hundreds of MP4s, a reproducible render inside CI, or HTML you generate programmatically. You keep full control of the environment and you pay in compute.
It is the wrong tool when you want footage rather than a build system. Authoring HTML to get a moving shot is a detour if your actual goal is a six-second clip from a photo of a product. For that, this site's AI video generator takes an image or a prompt in the browser — see the image to video workflow for a still that should move, or the pricing page for what a clip costs before you start. If you would rather stay in the terminal or in your assistant, the hosted HyperFrames MCP server starts the same generations from Claude and any other MCP client. The HyperFrames AI explainer lays out the full difference between the open-source engine and this hosted studio.
FAQ
Is the HyperFrames CLI free?
The framework is Apache 2.0 and local rendering costs nothing beyond your own machine. Cloud rendering, HeyGen voices and avatars, and the hosted HeyGen Studio consume account credits.
Does hyperframes.net ship a CLI?
No. This site is a hosted studio with no install step. The CLI belongs to the open-source framework at github.com/heygen-com/hyperframes.
Can I render on a server without Chrome?
You need a browser binary the renderer can drive. In CI, install one explicitly — the CLI's doctor command tells you whether it found one.
What is the output format?
MP4, encoded through FFmpeg from frames stepped in headless Chrome, at 1920×1080 and 30 fps by default.