heygen-com/hyperframes · 上手攻略

仓库：heygen-com/hyperframes
链接：https://github.com/heygen-com/hyperframes
分类：ai · video · agent-tool
作者：Tom
更新：2026-07-05

这是什么

HyperFrames 是 HeyGen 开源的HTML 到 MP4 视频渲染框架，stars 33K+（另有同名仓库差异），周增 +651。核心能力：用写网页的方式定义视频——视频即 HTML，动画即 seekable 动画，渲染引擎通过 headless Chrome seek 到指定帧并用 FFmpeg 编码输出确定性 MP4。

设计上深度面向 AI Agent：21 个可安装的 Agent Skill 让 AI 编程助手（Claude Code、Cursor、Gemini CLI、Codex 等）能够直接生成视频，支持无人工干预的 CI 流水线渲染。Apache 2.0 许可证，无商业授权门槛。

解决什么问题

传统视频制作工具（Premiere、After Effects、Final Cut）依赖 GUI 操作，无法被 AI Agent 编程控制；Remotion 虽然可以用代码生成视频，但强依赖 React 和打包工具链，Agent 难以直接介入。HyperFrames 的核心价值：用 Agent 最擅长的 HTML 来定义视频，无需打包、所见即所得、确定性渲染，让"描述视频内容→AI 生成 HTML→自动渲染出片"的 Agent 视频工作流成为可能。

快速安装

环境要求

Node.js 22+（官网 https://nodejs.org）
FFmpeg（brew install ffmpeg macOS / apt install ffmpeg Ubuntu）

安装步骤

# 安装 CLI（npm）
npm install -g hyperframes

# 或使用 npx（无需全局安装）
npx hyperframes --version

# 初始化新项目
npx hyperframes init my-video
cd my-video

# 浏览器实时预览
npx hyperframes preview

# 渲染为 MP4
npx hyperframes render --output output.mp4

AI Agent Skill 安装

# 安装全套 21 个 HyperFrames skill（路由 + 所有领域 skill）
npx skills add heygen-com/hyperframes --all

# 或只安装主路由 skill（推荐先装）
npx skills add heygen-com/hyperframes

# 按需安装单个 skill（bare name，无前导 /）
npx skills add heygen-com/hyperframes --skill product-launch-video

Skill 列表：/hyperframes（主路由）、/product-launch-video、/website-to-video、/faceless-explainer、/pr-to-video、/embedded-captions、/talking-head-recut、/motion-graphics、/music-to-video、/slideshow、/general-video、/remotion-to-hyperframes、/hyperframes-core、/hyperframes-animation、/hyperframes-keyframes、/hyperframes-creative、/hyperframes-media、/media-use、/hyperframes-cli、/hyperframes-registry、/figma。

核心用法

基本 HTML 视频组成

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <!-- 加载 GSAP 用于动画 -->
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
</head>
<body>
  <div id="stage"
    data-composition-id="launch"
    data-start="0"
    data-width="1920"
    data-height="1080">

    <!-- 视频轨道 -->
    <video class="clip" data-start="0" data-duration="6"
           data-track-index="0" src="intro.mp4" muted playsinline></video>

    <!-- 文字轨道：1s 后出现，持续 4s -->
    <h1 id="title" class="clip" data-start="1" data-duration="4"
        data-track-index="1" style="font-size:72px;color:white;">
      Launch Day
    </h1>

    <!-- 音频轨道 -->
    <audio data-start="0" data-duration="6"
           data-track-index="2" data-volume="0.5" src="music.wav"></audio>

    <script>
      // 绑定 GSAP 时间线（paused=true，等待渲染器驱动）
      const tl = gsap.timeline({ paused: true });
      tl.from("#title", { opacity: 0, y: 40, duration: 0.8 }, 1);
      window.__timelines = window.__timelines || {};
      window.__timelines.launch = tl;
    </script>
  </div>
</body>
</html>

核心数据属性速查

属性	作用
`data-composition-id`	视频组合的唯一 ID
`data-start`	该元素开始时间（秒）
`data-duration`	持续时长（秒）
`data-track-index`	轨道编号（0=视频，1=字幕/文字，2=音频…）
`data-width` / `data-height`	输出分辨率（默认 1920×1080）
`data-volume`	音量（音频轨道）

命令速查

# 初始化项目
npx hyperframes init my-video

# 浏览器预览（热重载）
npx hyperframes preview

# 本地渲染 MP4
npx hyperframes render --output demo.mp4

# 安装现成 blocks（Catalog）
npx hyperframes add flash-through-white    # 闪光过渡
npx hyperframes add instagram-follow        # 社交关注组件
npx hyperframes add data-chart              # 动态图表

# 查看 Catalog
# https://hyperframes.heygen.com/catalog

# AWS Lambda 分布式渲染
npx hyperframes lambda deploy
npx hyperframes render --lambda --output batch.mp4

21 个 Skill 使用场景

Skill	何时用
/product-launch-video	有产品页/文档/PR → 生成产品介绍视频
/website-to-video	任意网站 URL → 网站导览视频
/faceless-explainer	纯文本/主题 → 无真人出镜的讲解视频
/pr-to-video	GitHub PR → 代码变更演示视频
/embedded-captions	已有真人视频 → 添加字幕
/talking-head-recut	已有访谈视频 → 加图文叠加包装
/motion-graphics	需要无旁白的纯设计动画（Logo、Lower-third）
/music-to-video	一段音乐 → 音画同步视频
/slideshow	PPT/Keynote → 可交互演示文稿
/general-video	以上都不匹配时的通用兜底

典型适用场景

① AI Agent 自动生成产品发布视频 接入 Claude Code 或 Codex 后，直接说"用 HyperFrames 做一个 30 秒的产品介绍视频，包含标题淡入、产品 Demo 播放和背景音乐"，Agent 即可生成 HTML → 渲染 → 输出 MP4，全流程无需人工介入。

② PR / Release changelog 视频 /pr-to-video Skill 读取 GitHub PR 内容，自动生成变更说明视频，适合自动化发布流水线。

③ 数据可视化视频自动化 接入 CI 后，每次数据更新自动渲染新的图表视频，适合日报、周报自动化生成。

④ 营销内容批量生产 同一 frame.md 设计系统 + 不同脚本 → 批量生成多语言/多产品线的营销视频。

坑与注意

Node.js 22+ 强制要求：低版本 Node 不兼容，报错请先 node -v 确认。
FFmpeg 必须安装：headless Chrome 负责帧捕获，FFmpeg 负责编码，两者缺一不可；渲染时报"ffmpeg not found"先检查 PATH。
GSAP timeline 必须 paused: true：HyperFrames 渲染器在 seek 时会手动控制时间线推进，带 paused: false 的 timeline 在 seek 场景下行为不确定。
window.__timelines 全局注册：每个 composition 内的 JS 必须把 timeline 对象注册到此全局变量，渲染器才能正确驱动。
Lottie/Three.js 兼容性：这些库本身是"墙钟动画"（wall-clock based），seek 时行为因实现而异，官方推荐优先使用 GSAP（seek-safe）。
Git LFS 陷阱：完整克隆（含 golden regression test 文件）约 240MB+，仅需源码时设置 GIT_LFS_SKIP_SMUDGE=1。
--human-friendly vs 非交互模式：Agent 使用默认非交互 CLI（所有参数通过 flags），添加 --human-friendly 才会启动交互式终端 UI。
Remotion 项目迁移：/remotion-to-hyperframes Skill 仅为单向迁移，迁移后仍需手动调整动画逻辑。

与同类对比

工具	编程模型	Agent 友好度	许可证	动画能力
HyperFrames	HTML + data attrs + GSAP	⭐⭐⭐⭐⭐ 原生支持 Skill	Apache 2.0	GSAP/CSS/Lottie/Three.js
Remotion	React 组件 + JSX	⭐⭐⭐ 需 React 知识	Remotion License（商业有条件）	React / CSS
FFmpeg CLI	命令行参数	⭐ 不友好	LGPL/GPL	无（仅编码）
Runway/Pika 等 AI 视频	Web UI	⭐ 不友好	专有 SaaS	AI 生成
剪映/CapCut	GUI	⭐ 不友好	专有	有限

HyperFrames 的核心差异：唯一将 HTML 原生作为创作语言、无需打包步骤、Agent Skill 体系完整落地的视频生成框架，Remotion 是最近竞品但 React 门槛和打包依赖是 Agent 集成的主要障碍。

一句话推荐结论

如果你需要让 AI Agent 自动化生成视频，或希望用"写 HTML"的方式批量生产营销视频内容，HyperFrames 是当前 Agent 友好度最高、确定性最强、生产可用性最佳的框架，Apache 2.0 无商业限制，值得在内容自动化流水线中落地。

数据来源：GitHub README、hyperframes.heygen.com 官方文档。Node.js 22+ 和 FFmpeg 为明确环境要求，建议在安装前确认版本。HyperFrames 仍活跃迭代中，示例代码以 README 最新版本为准。