319 lines
9.1 KiB
Markdown
Executable File
319 lines
9.1 KiB
Markdown
Executable File
# 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
|
||
<div id="root" data-composition-id="demo"
|
||
data-start="0" data-width="1920" data-height="1080">
|
||
|
||
<h1 id="title" class="clip"
|
||
data-start="1" data-duration="4" data-track-index="1"
|
||
style="font-size: 72px; color: white;">
|
||
Welcome to 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["demo"] = tl;
|
||
</script>
|
||
</div>
|
||
```
|
||
|
||
### 三条核心规则
|
||
|
||
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` 引用，内容包在 `<template>` 里
|
||
- **内联**：直接在父 composition 里定义
|
||
- 框架自动管理子 composition 的时间线嵌套
|
||
|
||
### 变量系统
|
||
|
||
- 在 `<html>` 上用 `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
|
||
- ❌ 直接在 `<video>` 元素上动画 width/height（用 div 包装）
|
||
- ❌ 手动嵌套子 timeline
|
||
|
||
---
|
||
|
||
## 渲染配置
|
||
|
||
### 输出选项
|
||
|
||
| 参数 | 可选值 | 默认 |
|
||
|---|---|---|
|
||
| `--format` | mp4, mov, webm, png-sequence | mp4 |
|
||
| `--fps` | 24, 30, 60 | 30 |
|
||
| `--quality` | draft, standard, high | standard |
|
||
| `--workers` | 1-8 或 auto | auto |
|
||
| `--gpu` | NVENC, VideoToolbox, AMF, VAAPI, QSV | off |
|
||
| `--docker` | 确定性渲染 | off |
|
||
| `--hdr` / `--sdr` | HDR 输出控制 | off |
|
||
|
||
### 环境要求
|
||
|
||
- **Node.js 22+**
|
||
- **FFmpeg 7.x**
|
||
- Chrome（bundled）
|
||
- Docker（可选，生产渲染推荐）
|
||
|
||
---
|
||
|
||
## Agent 集成
|
||
|
||
这是 HyperFrames 的最大亮点。
|
||
|
||
### 为什么对 Agent 友好
|
||
|
||
1. LLM 天生擅长生成 HTML — 不需要学新 DSL
|
||
2. CLI 完全非交互，参数驱动，纯文本输出
|
||
3. 可以从文档、网页、GitHub 仓库等现成内容起步
|
||
4. 支持 Claude Code、Cursor、Gemini CLI、Codex 等 AI 编码 Agent
|
||
|
||
### Skills 安装
|
||
|
||
```bash
|
||
npx skills add heygen-com/hyperframes
|
||
```
|
||
|
||
安装后在 Claude Code 中注册为 slash commands：
|
||
- `/hyperframes` — composition 创作
|
||
- `/hyperframes-cli` — init, lint, preview, render
|
||
- `/hyperframes-media` — TTS、转录、背景移除
|
||
- `/tailwind` — Tailwind v4 样式
|
||
- `/gsap` — GSAP 时间线动画
|
||
- 以及 `/animejs`、`/css-animations`、`/lottie`、`/three`、`/waapi`
|
||
|
||
### 示例提示词
|
||
|
||
```
|
||
Using /hyperframes, create a 10-second product intro with a fade-in title over a dark background.
|
||
|
||
Summarize the attached PDF into a 45-second pitch video using /hyperframes.
|
||
|
||
Turn this CSV into an animated bar chart race using /hyperframes.
|
||
|
||
Make a 9:16 TikTok-style hook video about [topic] using /hyperframes.
|
||
```
|
||
|
||
---
|
||
|
||
## 使用场景
|
||
|
||
| 场景 | 描述 |
|
||
|---|---|
|
||
| **文档转视频** | onboarding、release note、帮助中心 → 解释型视频 |
|
||
| **网站转视频** | 产品页、发布文案 → demo、功能讲解 |
|
||
| **仓库转视频** | GitHub README、架构说明 → devrel walkthrough |
|
||
| **数据转视频** | CSV、看板、指标 → 动态图表叙事 |
|
||
| **产品 demo** | 从提示词或 HTML 生成产品演示视频 |
|
||
| **社交媒体内容** | YouTube、TikTok、短视频 |
|
||
|
||
---
|
||
|
||
## Catalog 组件库
|
||
|
||
50+ 开箱即用的 blocks 和 components：
|
||
- 字幕样式（caption-clip-wipe 等）
|
||
- 社交 overlay
|
||
- Shader 转场
|
||
- 数据可视化图表
|
||
- 电影化特效
|
||
|
||
安装方式：`npx hyperframes add <component-name>`
|
||
|
||
---
|
||
|
||
## 定价
|
||
|
||
### 开源引擎
|
||
- **免费**，本地渲染不限量
|
||
- Docker 渲染也不收费（用自己的基础设施）
|
||
|
||
### 托管 Studio（hyperframes.net）
|
||
|
||
| 套餐 | 价格 | 积分/月 | 备注 |
|
||
|---|---|---|---|
|
||
| 入门版 | $29/月（年付 $87） | 500 | 基础功能 |
|
||
| 标准版 | $99/月（年付 $297） | 2,000 | 优先队列 |
|
||
| 高级版 | $199/月（年付 $597） | 8,000 | 最快速度 |
|
||
| 试用 | 免费 | 30 积分 | 新用户 |
|
||
|
||
积分消耗：4秒视频 = 40积分，15秒视频 = 150积分
|
||
|
||
免费浏览器工具（视频转换、缩略图、GIF、图片压缩）不扣积分。
|
||
|
||
---
|
||
|
||
## Frame Adapters
|
||
|
||
HyperFrames 通过 Frame Adapter 模式支持多种动画运行时：
|
||
- **GSAP** — 主要推荐
|
||
- **Lottie** — 通过 `window.__hfLottie` 注册
|
||
- **CSS Animations** — 原生支持
|
||
- **Three.js** — 3D 场景
|
||
- **WAAPI** — Web Animations API
|
||
- **Anime.js** — 轻量动画库
|
||
|
||
只要运行时能 seek 到某一帧，就能通过适配器接入渲染链路。
|
||
|
||
---
|
||
|
||
## 竞品对比思考
|
||
|
||
| 维度 | HyperFrames | Remotion | After Effects |
|
||
|---|---|---|---|
|
||
| 视频定义方式 | HTML + data attributes | React + JS | 时间线 GUI |
|
||
| Agent 适配 | ⭐⭐⭐ 原生设计 | ⭐⭐ 需 React | ⭐ 无法自动化 |
|
||
| 确定性渲染 | ✅ | ✅ | ❌ |
|
||
| 学习曲线 | 低（会 HTML 就行） | 中（需 React） | 高 |
|
||
| 动画运行时 | GSAP/Lottie/CSS/任意 | CSS/React 状态 | 内置 |
|
||
| 渲染依赖 | Chrome + FFmpeg | Chrome + FFmpeg | Adobe |
|
||
| 开源 | ✅ MIT | ✅ MIT | ❌ |
|
||
|
||
---
|
||
|
||
## 评价
|
||
|
||
**优点：**
|
||
- 概念非常清晰 — HTML 即视频，零新 DSL 学习成本
|
||
- Agent 友好设计是杀手级特性，开箱即用的 skills 系统
|
||
- 确定性渲染让视频也能 CI/CD
|
||
- HeyGen 背书，项目活跃
|
||
- 50+ Catalog 组件开箱即用
|
||
|
||
**局限：**
|
||
- 适合结构化、信息展示类视频，不适合复杂真人特效
|
||
- 托管 Studio 定价偏贵（相比自建）
|
||
- 依赖 Chrome 逐帧捕获，渲染速度不如原生视频引擎
|
||
- 生态还比较新，社区资源有限
|
||
|
||
**适用人群：**
|
||
- 需要批量生成视频的开发者团队
|
||
- 想用 AI Agent 自动化视频生产的人
|
||
- DevRel、产品营销团队
|
||
- 数据可视化视频制作者
|
||
|
||
---
|
||
|
||
## 快速上手
|
||
|
||
```bash
|
||
# 1. 初始化项目
|
||
npx hyperframes init my-video
|
||
cd my-video
|
||
|
||
# 2. 浏览器预览
|
||
npx hyperframes preview
|
||
|
||
# 3. 渲染 MP4
|
||
npx hyperframes render --output output.mp4
|
||
|
||
# 4. 环境检查
|
||
npx hyperframes doctor
|
||
```
|
||
|
||
---
|
||
|
||
## 相关链接
|
||
|
||
- 官网：https://www.hyperframes.net/zh
|
||
- GitHub：https://github.com/heygen-com/hyperframes
|
||
- 文档：https://hyperframes.mintlify.app/introduction
|
||
- Catalog：https://hyperframes.mintlify.app/catalog
|
||
- 定价：https://www.hyperframes.net/zh/pricing
|
||
- 使命：https://www.hyperframes.net/zh/mission
|