HyperFrames GitHub 仓库指南：安装教程与 Remotion 对比

HyperFrames 是 HeyGen 开源的 HTML 转视频框架：你用普通的 HTML data 属性描述时间轴，渲染器在 headless Chrome 里逐帧 seek，再用 FFmpeg 编码成确定性 MP4。你要找的仓库是 github.com/heygen-com/hyperframes——TypeScript 编写，Apache-2.0 许可，自 2026 年 3 月创建以来已积累约 78,000 stars，截至本文撰写仍在活跃开发。

它的口号 "Write HTML. Render video. Built for agents." 概括了整个赌注：AI 编码代理本来就精通写 HTML，所以对「代理生成的视频」来说，HTML——而不是 React 组件、也不是私有时间轴格式——是上手最快的创作格式。

这篇教程覆盖完整的实操路径：装什么、项目在磁盘上长什么样、真实渲染产出了什么，以及与 Remotion 的坦诚对比，让你在投入一个周末之前先选对工具。

HyperFrames 是什么？

HyperFrames 把一个 HTML 文件变成视频。一个 composition 就是一个普通的网页：可见元素携带 data-start、data-duration、data-track-index 属性声明它们何时出现，一条暂停的 GSAP（或 CSS、Lottie、Three.js、Anime.js、WAAPI）时间轴声明它们如何运动。渲染器并不录屏——它在 headless Chrome 里把页面跳转到每一精确帧、截图，再用 FFmpeg 编码。因为每一帧都是 seek 出来的而不是「录」出来的，相同输入永远产出相同视频，这也是它能进入 CI 流水线和回归测试的原因。

这套架构与 Remotion 相同——两者都用 headless 浏览器渲染网页、用 FFmpeg 编码。区别在于你写什么，对比部分会回到这一点。

项目年轻但并非实验品：HeyGen 在生产环境使用它，tldraw 和 TanStack 也在仓库的 adopters 名单里。

来源：github.com/heygen-com/hyperframes，访问于 2026 年 11 月 3 日。

环境要求

走 CLI 路线需要：

• Node.js 22 或更新（npm 包声明 engines: node >= 22）
• FFmpeg 在 PATH 中（macOS：brew install ffmpeg；Ubuntu：sudo apt install ffmpeg）

不需要安装项目级依赖：composition 就是纯 HTML 文件，hyperframes init 脚手架的项目里连 node_modules 都没有——CLI 本身通过 npx 运行。

安装路径一：手动用 CLI

试水最快的方式只有一条命令：

npx hyperframes init my-video
cd my-video

我在一台 Mac（Node 24、FFmpeg 8.1）上用 hyperframes 0.9.7 实际跑过。脚手架生成了六个文件、零依赖：

my-video/
├── index.html          # composition——一支 10 秒、1920×1080 的示例片
├── hyperframes.json    # registry 与路径配置
├── package.json        # dev / check / render / publish 脚本
├── AGENTS.md           # 给编码代理的说明
├── CLAUDE.md
└── meta.json

一个值得知道的细节：init 还会把 HyperFrames 的 agent skills 链接进你本机已安装的编码代理目录，之后在这个文件夹里打开的代理天然懂这套框架的规则。

起始的 index.html 很有教学价值。根元素声明整部影片：

<div id="root"
     data-composition-id="main"
     data-start="0" data-duration="10"
     data-width="1920" data-height="1080">
  <h1 id="title" class="clip"
      data-start="0" data-duration="10" data-track-index="0">Title</h1>
</div>

再注册一条暂停的 GSAP 时间轴供渲染器 seek：

<script>
  const tl = gsap.timeline({ paused: true });
  window.__timelines["main"] = tl;
</script>

渲染前先跑一次 lint：

npm run check

在脚手架上这一步零错误通过，带一条警告（占位标题全程不动，检查器提示首帧静态；如果影片本来就该静止，可加 data-no-timeline），对比度检查 5/5 通过 WCAG AA。检查器在你浪费一次渲染之前就把布局、动效、对比度、工艺、音频规则全查一遍。

npm run dev 在浏览器里打开带热重载的预览；npm run render 输出 MP4。

安装路径二：交给你的编码代理

如果你在 Claude Code、Codex、Cursor、Copilot 或 Gemini CLI 里工作，官方预设的用法是让代理来建视频。有两种安装形态（这一节基于官方文档，我逐条核对了命令，但没有在每种代理里逐一实测）：

Claude Code 插件：

claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes@hyperframes

之后以 /hyperframes:hyperframes 调用。

独立 skills（任意文件夹、任意代理）：

npx skills add heygen-com/hyperframes     # 交互式选择器：选 Core Skills
npx hyperframes skills update             # 非交互：只装核心集

核心集是四个 skill：/hyperframes（渲染契约，最先读）、/hyperframes-cli、/hyperframes-registry（约 450 个块的目录）、/media-use（音乐、配音、素材）。另有四个按需安装，包括用来迁移存量 Remotion 代码的 /remotion-to-hyperframes。

然后直接开口，用 README 的原例：

Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and subtle background music.

不碰终端的两个选项

有两条路完全绕开终端。Studio 桌面应用（macOS、Windows、Linux）让代理跑在实时预览旁边——你输入想要什么，回答几个问题，然后指着画面改；需要免费注册 HeyGen 账号。还有一个 Claude.ai 或 ChatGPT 的 connector，在你的 HeyGen 账号里构建并渲染视频，代价是交出本地项目文件夹。框架本身免费且 Apache-2.0；虚拟形象、生成素材等 HeyGen 媒体只在你明确要求时才消耗 HeyGen 积分。

让 composition 真正渲染的三条规则

HTML composition 一旦违反契约就会「安静地失败」，所以值得把文档点名的三条规则背下来：

1. 每个可见元素带 class="clip"，以及 id、data-start、data-duration、data-track-index。
2. 动画时间轴必须以暂停态创建——渲染器靠 seek 驱动它，它绝不能自己播。
3. 时间轴要注册到 window.__timelines 上，键名与根元素 data-composition-id 同名。漏掉这条，你只会得到一张不动的帧。

稍复杂的效果别手搓：npx hyperframes add data-chart 会把现成块（共约 450 个——转场、叠加层、动态文字、字幕、图表、地图）以可编辑源码的形式装进项目。

来源：hyperframes.heygen.com 目录页，访问于 2026 年 11 月 3 日。

渲染：一次真实运行的结果

脚手架原封不动，我跑了 npm run render：

◇  renders/smoke-test_2026-11-03_17-38-07.mp4
   29.0 KB · 10.0s video · rendered in 19.1s
   screenshot capture · hardware gpu · compile 8.5s · extract 0.0s · audio 0.0s · probe 0.0s · setup 1.6s · capture 8.8s · encode 0.1s · assemble 0.1s

输出是 1920×1080 的 H.264 MP4，300 帧、30 fps，由 8 个并行 worker 截取——一支十秒视频在一台笔记本上不到二十秒渲染完成，当然这只是极简 composition。带视频素材和更长时长的真实项目会更久，但机制不变：逐帧 seek、截图、编码。

确定性是这里低调的杀手锏。同一份 index.html 每次都渲染出相同的视频——渲染器 seek 出的每一帧与机器负载无关——所以你可以 diff 两次渲染、在 CI 里抓住视觉回归、用换数据的方式复渲染产品化模板而不必逐帧人检。

HyperFrames vs Remotion：该选哪个？

两者都用 headless Chrome 加 FFmpeg 从网页渲染视频，都带可视化编辑器，都提供 AWS Lambda 渲染（HyperFrames 额外有本地、HeyGen 托管云和 Google Cloud Run 路径）。真正的区别：

	HyperFrames	Remotion
你写什么	纯 HTML + CSS + 可 seek 动画	React 组件，帧号的纯函数
构建步骤	无——index.html 直接可播	需要打包器
动画模型	渲染器 seek 暂停时间轴（GSAP、Lottie、WAAPI…）	useCurrentFrame()——你按帧算值
存量网页素材	几乎原样可用	需改写为 React
许可	Apache-2.0，无席位数限制	个人与 ≤3 人公司免费；超过需付费
生态	新（2026 年 3 月）	更老牌，模板、教程、生产案例多得多

许可方面，引用 Remotion 自己许可页的数字（2026 年 11 月核对）：三人及以下免费；超过后从 Company License 起付费，自动化路线按每渲染 $0.01、每月 $100 起收，创作者席位每月 $25，企业协议每月 $500 起。HyperFrames 没有对应门槛——Apache-2.0、无按渲染收费——这对代理商、SaaS 开发者和任何要把渲染嵌进产品的人最要紧。

对 Remotion 的优势也要说透。它更成熟：更多有答案的问题、更多模板、久经考验的 Lambda 渲染器。如果你的团队本来就写 React，组件、设计系统、图表库零成本平移，而且纯函数心智模型（interpolate(frame, [0, 15, 75, 90], …)）确实比一条可能被悄悄违反的时间轴契约更好推理。

在代理创作这条路上，HyperFrames 是更有立场的一方：它自带教会代理框架规则的 skills，CLI 默认非交互，而且纯 HTML 显然比带打包器的 JSX 工程更容易让代理写对。HeyGen 自己的指南报告了一次单轮实验——同一提示、各自跑一遍、Claude Code 执行——HyperFrames 一轮略快（11m50s 对 12m30s）、写了 4 个 HTML 文件而非 10 个 TypeScript 文件、零安装而非约 950 MB 的 node_modules。把它当框架作者的个案轶事看，别当 benchmark；他们自己的结论是：真正持久的差别是你最后手里拿着什么——能直接在浏览器里打开的 HTML 文件，还是一个 React 工程。

选 HyperFrames，如果你想让代理制作并持续迭代视频、手里有现成 HTML/动画素材、需要 Apache-2.0 给三人以上的团队或产品兜底、或者 CI 里的确定性渲染是硬需求。

选 Remotion，如果你的团队泡在 React 里、想要最大的模板与社区生态、或者眼下就需要最成熟的无服务器渲染路径。

要迁移存量 Remotion 代码，/remotion-to-hyperframes skill 会把 useCurrentFrame/interpolate 映射为时间轴 tween，拒绝不适合的模式（React 状态机、异步元数据），并靠逐帧对比两个版本来自检。

它在 AI 视频工作流里的位置

代码渲染视频和 AI 生成视频解决的是不同的活儿，分清两者最省时间。HyperFrames 给你确定性、品牌精确的产出——文字、Logo、图表、时间点分毫不差，每次运行完全一致，适合产品介绍、讲解片和自动化流水线。AI 生成给你的是「创作出的素材」——模板里不存在的物理运动、角色和场景。一个实用的分工是两者并用：生成的片段当素材，代码渲染负责包装、字幕和品牌。生成侧我们另有覆盖：prompt 转视频工具、搭建 AI 视频内容流水线和代理式水果视频工作流。

想不写代码就做水果视频？

如果你的目标是水果题材短视频而不是渲染流水线，AI Fruit 用提示词、图片和模板直接生成水果主题视频——不写 HTML、不装 FFmpeg。开始创作 →