项目简介
Hyperframes 允许开发者用 HTML 和 CSS 制作视频，通过无头 Chrome 确定性渲染导出 MP4。它内置 CLI 支持预览和渲染，并提供技能插件与 AI 编程代理深度集成。支持 GSAP、Lottie 等动画运行时，采用帧适配器模式。
README 预览
\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
常见问题 (5)
故障排除为什么在 hyperframes 中，GSAP tweens 在 1700 秒后不会在渲染的视频中显示？
已知 hyperframes 0.6.52 中的错误：起始时间 > 约1700秒（绝对）的GSAP补间动画在渲染期间不会被应用。解决方法：重新组织动画，使补间从时间0开始，并使用持续时间控制可见性，或者将合成拆分为较短片段。从t=0开始的连续补间可以正常工作。关注 issue #1107 以获取永久修复。
故障排除将HyperFrames升级到v0.6.11后，为什么我渲染的视频底部会出现白色或黑色的条？
这是HyperFrames v0.6.11+（包括最新的v0.6.31）中的一个已知回归问题。在1080x1920纵向构图的开始约37秒内，底部条带未被视频元素覆盖。目前唯一的解决方法是降级到v0.6.10，该版本能正确渲染。使用：npx --yes hyperframes@0.6.10 render --output out.mp4。关注问题#1009以获取永久修复。
故障排除为什么当根时间轴的时长为零时，tl.set() 的更改在 Hyperframes 预览中会被忽略？
这会影响 v0.8.107 之前的 Hyperframes CLI。仅包含 set 的根时间轴时长为零，因此预览运行时会将其包装在一个已暂停的 duration-floor 时间轴中，但却错误地将作者的根时间轴保持为暂停状态；因此 seek 操作永远无法渲染其 tl.set() 的值。
修复方法：升级到 Hyperframes CLI v0.8.107 或更新版本：
npx hyperframes@latest preview或者固定使用修复版本：
npx hyperframes@0.8.107 previewduration-floor 包装器现在会激活被持有的根时间轴，与现有的嵌套组合行为保持一致。
旧版本的临时解决方案：在 seek 之前取消根时间轴的暂停状态，例如：
window.__timelines.main.paused(false);
__player.seek(0.5);添加任何非零时长的 tween 也可以避免进入该回退路径。
故障排除如何修复在运行 hyperframes render 处理大型编译后的 HTML 文件时出现的 "Fatal JavaScript invalid size error 268435456" 错误？
将 HyperFrames 升级到 v0.8.137 或更高版本；v0.8.137 版本包含 PR #5098，该改动以有界分块的方式处理 HTML，可防止正则表达式匹配数组超过 V8 的 2^27 槽位上限。
步骤：
1. 升级：
npm install hyperframes@latest
或直接运行：
npx hyperframes@latest render --output out.mp4
2. 如果无法立即升级，请固定到最后一个已知正常的版本：
npx hyperframes@0.8.75 render --output out.mp4
3. 作为项目级的变通方案，可在根合成中只声明一次 @font-face 规则，而不是在每个子合成中重复声明，以此减小编译后 HTML 的体积。重复的本地字体声明会被分别以 base64 形式单独内联，可能生成非常大的 index.html 文件。
增大 Node 的堆内存无法防止此崩溃，因为 V8 是在构建内部正则表达式结果数组时中止的；这并不是一个可捕获的内存不足异常。
故障排除为什么与 macOS 渲染的视频相比，Docker 渲染的视频颜色会偏移或偏淡？
这是由于 Debian 的 FFmpeg 5.1.9 使用 BT.601 矩阵对颜色进行编码，却将输出标记为 BT.709 所导致的。请将 Hyperframes 升级到 v0.8.81 或更高版本；该修复已在 v0.8.143 上得到确认，Docker 和 macOS 的输出在 1–2 个色阶范围内一致。如果无法升级，请将 Docker 镜像中的 Debian FFmpeg 替换为当前的静态 FFmpeg 构建版本（例如 8.1），或者尝试在编码过滤器中显式添加 out_color_matrix=bt709。另外，如果后台更新程序在渲染过程中修改了全局包，请设置 HYPERFRAMES_NO_UPDATE_CHECK=1 和 HYPERFRAMES_NO_AUTO_INSTALL=1；该问题已在 v0.8.83 中修复。