hyperframes
Frameworkheygen-com/hyperframes
HTML-based video rendering framework for AI agents.
Overview
Hyperframes lets developers compose videos using HTML and CSS, with deterministic rendering via headless Chrome. It includes a CLI for previewing and exporting MP4 files, and provides first-class integration with AI coding agents through skill plugins. Supports animation runtimes like GSAP, Lottie, and CSS animations via its Frame Adapter pattern.
README Preview
\n \n \n \n \n \n\n\n\n \n \n \n \n \n\n\nWrite HTML. Render video. Built for agents.\n\n\n \n\n\nHyperframes is an open-source video rendering framework that lets you create, preview, and render HTML-based video compositions — with first-class support for AI agents.\n\n## Quick Start\n\n### Option 1: With an AI coding agent (recommended)\n\nInstall the HyperFrames skills, then describe the video you want:\n\n```bash\nnpx skills add heygen-com/hyperframes\n```\n\nThis teaches your agent (Claude Code, Cursor, Gemini CLI, Codex) how to write correct compositions, GSAP timelines, Tailwind v4 browser-runtime styles, and first-party adapter animations. In Claude Code, the skills register as slash commands — invoke `/hyperframes` to author compositions, `/hyperframes-cli` for the dev-loop commands (init, lint, preview, render), `/hyperframes-media` for asset preprocessing (TTS, transcription, background removal), `/tailwind` for `init --tailwind` projects, `/gsap` for timeline animation help, or the adapter skills (`/animejs`, `/css-animations`, `/lottie`, `/three`, `/waapi`) when a composition uses those runtimes.\n\nFor Claude Design, open [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md) on GitHub and click the download button (↓) to save it, then attach the file to your Claude Design chat. It produces a valid first draft; refine in any AI coding agent. See the [Claude Design guide](https://hyperframes.heygen.com/guides/claude-design).\n\nFor Codex specifically, the same skills are also exposed as an [OpenAI Codex plugin](./.codex-plugin/plugin.json) — sparse-install just the plugin surface:\n\n```bash\ncodex plugin marketplace add heygen-com/hyperframes --sparse .codex-plugin --sparse skills --sparse assets\n```\n\nFor Claude Code, the repo also ships a [Claude Code plugin manifest](./.claude-plugin/plugin.json): test it locally with `claude --plugin-dir .`. The m
FAQ (5)
TroubleshootingWhy do GSAP tweens not show in rendered video after 1700 seconds in hyperframes?
Known bug in hyperframes 0.6.52: GSAP tweens with start time > ~1700s (absolute) are not applied during render. Workaround: restructure animations so tweens start at time 0 and use duration to control visibility, or split the composition into shorter segments. A continuous tween from t=0 works correctly. Track issue #1107 for a permanent fix.
TroubleshootingWhy does a white or black bar appear at the bottom of my rendered video after upgrading HyperFrames to v0.6.11?
This is a known regression in HyperFrames v0.6.11+ (including latest v0.6.31). For the first ~37 seconds of a 1080x1920 portrait composition, the bottom strip is not covered by the video element. The only current workaround is to downgrade to v0.6.10, which renders correctly. Use: npx --yes hyperframes@0.6.10 render --output out.mp4. Track issue #1009 for a permanent fix.
TroubleshootingWhy are tl.set() changes ignored in Hyperframes preview when the root timeline has zero duration?
This affects Hyperframes CLI before v0.8.107. A set-only root timeline has zero duration, so the preview runtime wraps it in a paused duration-floor timeline but incorrectly leaves the author's root timeline paused; therefore seeking never renders its tl.set() values.
Fix: upgrade to Hyperframes CLI v0.8.107 or newer:
npx hyperframes@latest previewOr pin the fixed release:
npx hyperframes@0.8.107 previewThe duration-floor wrapper now activates the held root timeline, matching the existing nested-composition behavior.
Temporary workaround on older versions: unpause the root timeline before seeking, for example:
window.__timelines.main.paused(false);
__player.seek(0.5);Adding any non-zero-duration tween also avoids the fallback path.
TroubleshootingHow do I fix "Fatal JavaScript invalid size error 268435456" when running hyperframes render on a large compiled HTML file?
Upgrade HyperFrames to v0.8.137 or newer; release v0.8.137 includes PR #5098, which processes HTML in bounded chunks and prevents the regex match array from exceeding V8's 2^27-slot limit.
Steps:
1. Upgrade:
npm install hyperframes@latest
or run directly with:
npx hyperframes@latest render --output out.mp4
2. If you cannot upgrade immediately, pin the last known-good release:
npx hyperframes@0.8.75 render --output out.mp4
3. As a project-level workaround, reduce compiled HTML size by declaring @font-face rules once in the root composition instead of repeating them in every sub-composition. Repeated local font declarations are inlined separately as base64 and can create very large index.html files.
Increasing Node's heap size will not prevent this crash because V8 aborts while building the internal regex result array; it is not a catchable out-of-memory exception.
TroubleshootingWhy do Docker-rendered videos have shifted or paler colors compared to macOS renders?
This was caused by Debian's FFmpeg 5.1.9 encoding colors with the BT.601 matrix while tagging the output as BT.709. Upgrade Hyperframes to v0.8.81 or later; the fix was confirmed on v0.8.143, where Docker and macOS outputs match within 1–2 color levels. If you cannot upgrade, replace Debian FFmpeg in the Docker image with a current static FFmpeg build such as 8.1, or try adding out_color_matrix=bt709 explicitly to the encode filters. Separately, if the background updater modifies the global package during a render, set HYPERFRAMES_NO_UPDATE_CHECK=1 and HYPERFRAMES_NO_AUTO_INSTALL=1; that issue was fixed in v0.8.83.