# HyperFrames — HTML 视频引擎完全研究
> 研究日期：2026-06-01
> 官网：https://www.hyperframes.net/zh
> GitHub：https://github.com/heygen-com/hyperframes
> 文档：https://hyperframes.mintlify.app/introduction
> 开发商：HeyGen
> 许可证：MIT（开源引擎）
---
## 一句话概括
**用 HTML 写视频。** HyperFrames 是 HeyGen 出品的开源 HTML-to-video 框架，将 HTML composition 直接渲染成 MP4，专为 AI Agent 驱动的视频生产设计。
---
## 核心理念
- 视频的「源代码」就是 HTML 文件
- 用 `data-start`、`data-duration`、`data-track-index` 等 data attribute 定义时间线
- 动画用熟悉的 GSAP、Lottie、CSS 等任何可 seek 到指定帧的运行时
- **确定性渲染**：同一输入 → 完全相同的输出帧，可 CI 化、可回归测试
- 不需要 React，不需要时间线编辑器，不需要专有格式
---
## 架构与包
| 包 | 作用 |
|---|---|
| `@hyperframes/core` | 类型定义、HTML 解析、composition lint |
| `@hyperframes/engine` | seek 驱动的帧捕获引擎（headless Chrome） |
| `@hyperframes/producer` | 捕获 + FFmpeg 编码的完整流水线 |
| `@hyperframes/studio` | 可视化编辑器 UI |
| `hyperframes (CLI)` | 命令行工具，默认非交互，适合 Agent 自动化 |
### 渲染管线
```
HTML Composition → headless Chrome 逐帧捕获 (beginFrame API) → FFmpeg 编码 → MP4/MOV/WebM
```
渲染模式：
- **Local Mode**：本地 Puppeteer + 系统 FFmpeg，开发迭代快
- **Docker Mode**：确定性输出，固定 Chrome 版本 + 字体集，适合 CI/CD
---
## Composition 模型
### 项目结构
```
project/
├── index.html # 根 composition（视频入口）
├── compositions/ # 子 composition（可复用片段）
│ ├── intro-anim.html
│ ├── caption-overlay.html
│ └── outro-title.html
├── assets/ # 媒体素材
│ ├── video.mp4
│ ├── music.mp3
│ └── logo.png
└── meta.json # 项目元数据
```
### 最小示例
```html
Welcome to Hyperframes
```
### 三条核心规则
1. **根元素**必须有 `data-composition-id`、`data-width`、`data-height`
2. **定时元素**需要 `data-start`、`data-duration`、`data-track-index` 和 `class="clip"`
3. **GSAP timeline** 必须用 `{ paused: true }` 创建，注册到 `window.__timelines`
### 嵌套 Composition
- **外部文件**：用 `data-composition-src` 引用，内容包在 `` 里
- **内联**：直接在父 composition 里定义
- 框架自动管理子 composition 的时间线嵌套
### 变量系统
- 在 `` 上用 `data-composition-variables` 声明变量（id + type + default）
- 在实例上用 `data-variable-values` 传值
- 在脚本里用 `window.__hyperframes.getVariables()` 读取
- 同一个子 composition 可以多次嵌入，每次不同参数
---
## GSAP 动画
HyperFrames 使用 GSAP 作为主要动画运行时。
### 关键要点
- Timeline 必须 `{ paused: true }`，框架控制播放
- 通过 position 参数（第3个参数）做绝对时间定位
- 只能做视觉属性动画，**不能**控制媒体播放
- 支持的方法：`to()`、`from()`、`fromTo()`、`set()`
- **Timeline 时长 = Composition 时长**（最长的动画决定总时长）
### 常见陷阱
- ❌ 在脚本里 play/pause/seek 媒体元素
- ❌ 创建非 paused 的 timeline
- ❌ 直接在 `