HyperFrames 入门教程

编写 HTML，渲染视频 — 为 AI 代理而生

HyperFrames 是一个开源框架，可以将 HTML 转换为逐帧渲染的确定性视频。你可以用构建网页的方式来定义视频。

为什么选择 HyperFrames？

🎨 对开发者友好

你已掌握这套技术栈：Compositions 是带有 data 属性的 HTML 文件，动画使用 GSAP、Lottie、CSS 或任何可跳转的运行时
无需学习新语言：没有自定义 DSL，没有专有组件系统，不需要 React。只要你会做网页，就能做视频

🤖 对 AI 代理友好

Compositions 是纯 HTML，任何 LLM 都能生成
CLI 默认非交互式，标志驱动，纯文本输出，代理可以脚手架、渲染和检查代码而无需交互提示

⚡ 对自动化流水线友好

本地渲染、Docker 渲染、CI/CD 流水线完美支持

工作原理

┌─────────────┐    ┌──────────────┐    ┌─────────────┐
│  1. 编写 HTML │ → │ 2. 浏览器预览  │ → │ 3. 渲染为 MP4 │
└─────────────┘    └──────────────┘    └─────────────┘

编写 HTML：用 HTML 定义视频，每个元素通过 data 属性设置时间（data-start、data-duration）和布局（data-track-index）
浏览器预览：运行 npx hyperframes preview 在浏览器中实时预览，编辑 HTML 后立即看到变化
渲染为 MP4：运行 npx hyperframes render --output output.mp4 生成最终视频

快速开始（5 分钟）

环境要求

依赖	必须	说明
Node.js 22+	✅	CLI 和开发服务器的运行环境
npm 或 bun	✅	包管理器
FFmpeg	✅	本地渲染的视频编码
Docker	❌	可选，用于确定性、可复现的渲染

步骤 1：创建项目

# 交互式创建（会引导你选择示例和导入媒体）
npx hyperframes init my-video
cd my-video

# 或非交互式创建（适合 CI 或 AI 代理）
npx hyperframes init my-video --non-interactive --example blank

项目结构：

my-video/
├── meta.json          # 项目元数据（名称、ID、创建日期）
├── index.html         # 根 composition — 视频的入口点
├── compositions/      # 子 compositions（通过 data-composition-src 加载）
│   ├── intro.html
│   └── captions.html
└── assets/            # 媒体文件（视频、音频、图片）
    └── video.mp4

步骤 2：预览

npx hyperframes preview

这会启动 HyperFrames Studio 并在浏览器中打开你的 composition。编辑 index.html 后会自动热重载。

步骤 3：编辑 composition

打开 index.html，一个最小的 composition 示例：

<div id="root"
     data-composition-id="my-video"
     data-start="0"
     data-width="1920"
     data-height="1080">

  <!-- 1. 定义一个带时间的文本片段在轨道 0 -->
  <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>

  <!-- 2. 加载 GSAP 用于动画 -->
  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>

  <!-- 3. 创建一个暂停的时间线并注册 -->
  <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>

步骤 4：渲染为 MP4

npx hyperframes render --output output.mp4

预期输出：

✔ Capturing frames... 150/150
✔ Encoding MP4...
✔ output.mp4 (1920x1080, 5.0s, 30fps)

核心概念

三条规则必须记住

规则 1：根元素

必须包含 data-composition-id、data-width 和 data-height：

<div id="root"
     data-composition-id="my-video"
     data-width="1920"
     data-height="1080">
  <!-- 内容 -->
</div>

规则 2：带时间元素

需要 data-start、data-duration、data-track-index 和 class="clip"：

<h1 class="clip"
    data-start="0"
    data-duration="5"
    data-track-index="0">
  标题文本
</h1>

属性	说明	示例
`data-start`	开始时间（秒）	`data-start="2"`
`data-duration`	持续时间（秒）	`data-duration="3"`
`data-track-index`	轨道索引（用于分层）	`data-track-index="1"`

规则 3：GSAP 时间线

必须使用 { paused: true } 创建并注册到 window.__timelines：

const tl = gsap.timeline({ paused: true });
tl.from("#title", { opacity: 0, duration: 1 }, 0);

window.__timelines = window.__timelines || {};
window.__timelines["my-video"] = tl;

数据属性速查表

属性	位置	说明
`data-composition-id`	根元素	视频的唯一标识符
`data-width`	根元素	视频宽度（像素）
`data-height`	根元素	视频高度（像素）
`data-start`	子元素	开始时间（秒）
`data-duration`	子元素	持续时间（秒）
`data-track-index`	子元素	图层顺序
`data-composition-src`	子元素	引用子 composition
`class="clip"`	子元素	标记为时间元素

常见任务

添加视频背景

<video id="bg-video" class="clip"
       data-start="0"
       data-duration="10"
       data-track-index="0"
       src="intro.mp4"
       muted playsinline>
</video>

添加音频

<audio id="bg-music"
       data-start="0"
       data-duration="10"
       data-track-index="2"
       data-volume="0.5"
       src="music.wav">
</audio>

使用 AI 代理（推荐）

安装 HyperFrames skills 后，告诉你的 AI 代理你想要什么视频：

npx skills add heygen-com/hyperframes

然后在 AI 代理中输入：

使用 /hyperframes 创建一个 10 秒的产品介绍视频，标题在深色背景上淡入，配有轻微的背景音乐。

示例提示词：

类型	提示词
从零开始	“使用 `/hyperframes`，创建一个 10 秒的产品介绍，带有深色背景上淡入的标题和轻微的背景音乐。”
基于上下文	“查看这个 GitHub 仓库 https://github.com/heygen-com/hyperframes 并用 `/hyperframes` 解释其用途和架构。”
格式特定	“用 `/hyperframes` 制作一个 9:16 的 TikTok 风格视频，内容关于 [主题]，配合 TTS 旁白同步的动态字幕。”
迭代修改	“把标题放大 2 倍，切换到暗色模式，并在结尾添加淡出效果。”

包列表

包	说明
@hyperframes/core	类型、HTML 解析、运行时和 composition linter — 所有功能的基础
@hyperframes/engine	可跳转的页面转视频捕获引擎，在无头 Chrome 中逐帧捕获
@hyperframes/producer	完整的渲染流水线，将捕获和 FFmpeg 编码合并为单个 API 调用
@hyperframes/studio	用于交互式构建和预览时间线的可视化 composition 编辑器 UI
hyperframes (CLI)	用于创建、预览和渲染 compositions 的命令行工具

下一步

📚 浏览组件目录 — 50+ 开箱即用的组件
🎬 快速入门 — 60 秒内构建和渲染你的第一个视频
🎨 GSAP 动画 — 为视频添加淡入、滑入、缩放和自定义动画
🐳 渲染 — 探索渲染选项：质量预设、Docker 模式、GPU 加速
💻 CLI — 完整的命令行文档

📖 完整文档索引：https://hyperframes.mintlify.app/llms.txt
🌐 GitHub：https://github.com/heygen-com/hyperframes

目录