HyperFrames 怎么用？两条路径从安装到渲染 MP4

HyperFrames 的用法一句话就能说清：写 HTML，渲染视频。它是由 HeyGen 发起的开源 HTML 转视频框架，把 HTML、CSS、GSAP 动画渲染成确定性的 MP4，专为 AI 编码智能体设计。上手有两条路径：把官方技能装进 Claude Code、Cursor 这类 AI 代理让它们代写，或者自己跑 init、preview、render 三条命令。本文按官方中文文档把两条路径一次讲完，并把官方 troubleshooting 里的报错速查整理成表。

它和剪辑软件、文生视频模型的区别

先分清三样东西，很多人在这一步就走错门：

1. 传统剪辑软件：你拖时间线，它剪素材。
2. Seedance 这类文生视频大模型：你给文字，它生成不可控的画面。
3. HyperFrames：你（或 AI 代理）写网页代码，每一帧都可精确控制，同样输入永远渲染出同样的视频。

适合的场景是数据图表动画、产品介绍、带字幕解说的科普视频这类「结构化内容」；不适合让 AI 凭空编一段实拍感画面，那是文生视频模型的活。

路径一：装进 AI 编码智能体（官方推荐）

前提是你已经在用 Claude Code、Cursor、Codex、Gemini CLI、Google Antigravity 或 GitHub Copilot CLI 中的任意一个。在项目目录执行：

npx skills add heygen-com/hyperframes

这一步不只是装个插件，它教代理学会官方文档之外的那套约定：正确的组合写法、GSAP 时间线注册、Tailwind v4 浏览器运行时样式，以及各家动画适配器的注册表（例如 window.__hfLottie）。官方特别强调，这些模式不在通用 Web 文档里，装技能的意义就是让代理第一次输出就对。

在 Claude Code 里会注册出一组斜杠命令：

1. /hyperframes：创作合成。
2. /hyperframes-cli：开发循环命令（init、lint、预览、渲染）。
3. /hyperframes-media：素材预处理（TTS、转录、去背景）。
4. /tailwind：init --tailwind 项目。
5. /gsap：时间线动画帮助。
6. /animejs、/css-animations、/lottie、/three、/waapi：组合里用到对应运行时时的上下文加载。

如果你用的是 Claude Design 这条线，官方给的是另一条入口：从 GitHub 打开 docs/guides/claude-design-hyperframes.md，下载后附加到 Claude Design 对话里，它会生成一份有效初稿，再拿到任意 AI 编码代理里细化。

官方文档给的示例提示，可以直接抄：

1. 冷启动：「使用 /hyperframes 创建一个 10 秒的产品介绍，深色背景上淡入标题。」
2. 热启动：「使用 /hyperframes 把这份 CSV 转换成动画条形图竞赛。」
3. 迭代：「把标题放大 2 倍，切换深色模式，结尾加淡出。」
4. 格式特定：「用 /hyperframes 做一个 9 分 16 秒的 TikTok 式钩子视频，配弹性字幕并与 TTS 旁白同步。」

想看和 Codex 配合的完整实战，站内已有一篇 Codex + HyperFrames 完整教程：用 AI 写 HTML 生成视频，讲的是组合玩法，本文不重复。

路径二：手动跑通三步

前置准备

1. Node.js 22 及以上：终端跑 node --version 确认，输出 v22.0.0 或更高才算通过。
2. FFmpeg：本地渲染必需，它负责把捕获的帧编码成 MP4。macOS 用 brew install ffmpeg，Ubuntu 用 sudo apt install ffmpeg，Windows 可 winget install ffmpeg。装完用 ffmpeg -version 验证。
3. Docker 可选：不装也能用，装了可以做确定性、可复现的渲染，也是「本地渲染和预览不一致」时的兜底方案。

第一步：初始化项目

npx hyperframes init my-video
cd my-video

交互式向导会让你选示例、导入素材。CI 或代理场景加 --non-interactive --example blank 跳过提问。官方列出的项目结构是：

有现成视频的话加 --video ./intro.mp4，它会自动转录并生成字幕；官方给的完整写法是 npx hyperframes init my-video --example warm-grain --video ./intro.mp4。另外 init 会自动安装 AI 代理技能，所以你随时可以把它交给代理继续。

第二步：浏览器预览

npx hyperframes preview

会启动 HyperFrames Studio 并打开预览，改 index.html 保存即热重载，不用手动刷新。

第三步：编辑与渲染

直接编辑 index.html，记住官方三条规则：

1. 根元素必须带 data-composition-id、data-width、data-height。
2. 定时元素必须有 data-start、data-duration、data-track-index 和 class="clip"。
3. GSAP 时间线必须用 { paused: true } 创建，并注册到 window.__timelines（key 要和 data-composition-id 完全一致）。

官方演示的最小合成长这样：

<div id="root" data-composition-id="my-video"
     data-start="0" data-width="1920" data-height="1080">
  <h1 id="title" class="clip"
      data-start="0" data-duration="5" data-track-index="0"
      style="font-size: 72px; color: white; text-align: center;
             position: absolute; top: 50%; left: 50%;
             transform: translate(-50%, -50%);">
    Hello, Hyperframes!
  </h1>
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
    window.__timelines = window.__timelines || {};
    window.__timelines["my-video"] = tl;
  </script>
</div>

然后渲染：

npx hyperframes render --output output.mp4

成功的预期输出是三行：✔ Capturing frames... 150/150、✔ Encoding MP4...、✔ output.mp4 (1920x1080, 5.0s, 30fps)。官方另有 50 多个即用块（过渡、叠加、数据可视化、特效）可以直接拼，见文档的 Catalog 部分。

完整的命令参数与示例，见 HyperFrames 官方中文文档；组件与 API 细节可以在 GitHub 仓库 按版本对照查阅。

怎么确认自己真的跑通了

官方 CLI 里有三个自查命令，比肉眼判断靠谱：

1. npx hyperframes doctor：检查 Node.js 版本、FFmpeg 可用性、Docker 状态和其他环境要求，有问题会直接报出来。
2. npx hyperframes compositions：列出每个合成解析出的实际时长。如果视频里的画面比预期短，这一步能立刻发现时间线不够长。
3. npx hyperframes info：收集系统与项目详细信息，提 issue 时官方要求你带上它的输出。

另外 npx hyperframes lint 会做结构检查，大部分「动画不生效、元素一直显示」的问题它能直接指出来。

常见报错速查

下面每一条都来自官方 troubleshooting 与 common-mistakes 文档，不是社区猜测：

预览卡顿的三条高频原因（官方从最常见到最不常见排序）：

1. 叠加 backdrop-filter: blur()，尤其是半径超过 32px。建议每个区域最多 2-3 层，单层半径别超 64px。
2. 4K 以上的大图被显示在小区域里。图像解码后的内存是「宽 × 高 × 4 字节」，一张 7000×5000 的 JPEG 解码后约 140MB，跟文件大小无关。
3. 大元素上的 filter: blur()、filter: drop-shadow()，以及大量带动画的 box-shadow、text-shadow。

渲染慢的加速手段：开发期用 --quality draft；用 npx hyperframes benchmark 找本机最佳 worker 数；不需要 30fps 就给 --fps 24；本地模式可加 --gpu 做硬件加速编码。

编码层的四个坑（linter 查不出来）

这四条来自官方 common-mistakes 页面，是「构图看起来坏了」的最常见原因：

1. 别直接给 <video> 元素做尺寸动画。用 GSAP 动 width、height、top、left 可能让浏览器直接停止渲染帧。正确做法是在外面包一层非定时的 <div>，动画 wrapper，让视频用 CSS 100% 填满它。
2. 不要在脚本里控制媒体播放。官方明确媒体播放由框架接管，读取 data-start、data-media-start、data-volume 决定何时播、怎么播。你自己调 video.play()、video.pause() 或改 audio.currentTime，结果是音画不同步。
3. 合成时长要手动延长。如果最后一个 GSAP 动画在 8 秒结束，合成就是 8 秒，哪怕视频源有几分钟。用 tl.set({}, {}, 283) 这类写法把时间线拉到目标时长。
4. 源图尺寸别超过画布 2 倍。1920×1080 的构图，图源控制在 3840×2160 以内就够，批量缩图可以用文档给的 mogrify -path assets/resized -resize 3840x3840\> assets/*.jpg。

还有一个容易被忽略的细节：想要 HDR 输出，源素材必须带 BT.2020 / PQ / HLG 元数据，且输出格式必须是 MP4（--format mov 或 --format webm 会退回 SDR）。需要强制 HDR 就用 --hdr，反之用 --sdr 关掉。

防坑：搜 HyperFrames 时注意同名站

中文搜索结果里混着几个同名但完全不同的产品：hyperframes.top 自称「国产 AI 视频生成平台」，hyperframes.net 和 hyperframes.app 是托管生成服务，它们与 HeyGen 发起的开源框架不是一回事。认准官方入口：GitHub 仓库 heygen-com/hyperframes、官网 hyperframes.dev、中文文档 docs.hyperframes-zh.cn。

值得搭配看的站内内容

1. 用 Codex 实操整个流程：Codex + HyperFrames 完整教程：用 AI 写 HTML 生成视频。
2. 长视频项目要分几天迭代，学会恢复编码会话：Claude Code /resume 怎么用？桌面版新功能与 5 种会话恢复方式详解。
3. 想先找个免费 IDE 环境再上这套流程：腾讯 CodeBuddy 怎么用：安装到 Agent 模式全流程。