把视频当成前端构建：HyperFrames 使用教程
一句话
HyperFrames 用 HTML 写视频：一个 index.html 定义整段视频，用 data-* 属性控制时序、GSAP 时间线驱动动画、CSS 管外观，然后一条命令渲成 MP4。官方介绍只有六个词——“Write HTML. Render video. Built for agents.”
它解决什么
想做个十五秒的产品视频，前端开发者通常有三条路：去学 After Effects、把活外包给动效设计师、或者干脆放弃每个版本都配视频。三条路都别扭——你明明天天在写 HTML/CSS，却为了几个转场要去学一套陌生的时间线软件。
更要命的是，剪辑软件做出来的视频是个黑箱。你没法 git diff 两个版本差在哪，没法在 CI 里自动出片，更没法让 AI agent 去拖一个 GUI 时间线。
HyperFrames 把这件事翻译回开发者的母语。视频的源码就是 HTML，时序写在标签的 data-* 属性里，动画是一段 GSAP，样式是 CSS。源码进 git，改动能 review，出片靠 CLI，而且——这是它专门强调的——同样的输入，渲出来逐帧一模一样。
心智模型：把视频当成一次前端构建
这是理解 HyperFrames 最快的一把钥匙。你已经会的那套前端工程，几乎一一对应：
| 前端工程 | HyperFrames |
|---|---|
index.html 源码 | 视频的 composition，也是 index.html |
| 类型检查 / lint | npx hyperframes lint——查缺失的 data-composition-id、轨道重叠、没注册的时间线 |
| 视觉回归测试 | npx hyperframes inspect——headless Chrome 沿时间线扫一遍，报文字溢出容器/画布 |
| 热重载 dev server | npx hyperframes preview——改文件浏览器实时刷新 |
| production build | npx hyperframes render——产出 MP4 |
| 可复现构建 | 确定性渲染，--docker 可做到字节级一致 |
记住这条主线：HTML 是源，CLI 是工具链，MP4 是构建产物。 后面所有命令都挂在这根线上。
快速上手
前提：Node.js 22+ 和 FFmpeg。装不确定就先跑 npx hyperframes doctor，它会检查 Chrome、FFmpeg、Node、内存够不够。
1. 起项目
npx hyperframes init my-video
cd my-video
init 不只是建个空目录——它铺好文件结构、拷贝媒体、用 Whisper 转写音频、还顺手装上给 AI 编码用的 skills。别手动建文件，用它。想从模板起步，挑一个：
npx hyperframes init my-video --example warm-grain
可选模板有 blank、warm-grain、swiss-grid、vignelli、kinetic-type、product-promo、nyt-graph 等。
2. 写 / 改 index.html
这是你花时间最多的地方。一个 composition 就是带 data-* 时序属性的 HTML：每个片段用 data-start、data-duration 声明什么时候出现、持续多久，动画交给一段 GSAP 时间线，样子用 CSS 写。
3. 边看边改
npx hyperframes preview
浏览器自动打开 studio，改 HTML 它实时刷新。渲染前先过两道关：
npx hyperframes lint # 结构错误
npx hyperframes inspect # 文字有没有溢出容器或画布
4. 出片
npx hyperframes render # 标准 MP4
npx hyperframes render --quality draft # 迭代时用，快
npx hyperframes render --fps 60 --quality high # 最终交付
迭代用 draft，审片用 standard，交付用 high。--fps 60 会让渲染时间翻倍，别在草稿阶段开。
dev loop 命令速查
日常 90% 就这几条，顺序是固定的：起 → 查 → 看 → 渲。
| 命令 | 作用 |
|---|---|
npx hyperframes init <name> | 脚手架建项目（可带 --example、--video、--audio） |
npx hyperframes lint | 查结构错误：缺 id、轨道重叠、时间线没注册 |
npx hyperframes inspect | 用 headless Chrome 沿时间线扫文字/元素溢出 |
npx hyperframes preview | 热重载预览（默认 3002 端口，--port 改） |
npx hyperframes render | 渲成 MP4（--quality/--fps/--format webm/--docker） |
npx hyperframes doctor | 渲染失败先跑它，查环境 |
记住：lint 和 inspect 在 preview 之前跑。结构和文字溢出这类问题，等渲出来才发现就太晚了。
必学的一个原则：先布局，后动画
这是新手最容易栽的坑，也是 HyperFrames 文档反复强调的一条。
错误做法：把元素摆在动画的起点状态（在屏幕外、缩成 0、透明），然后 tween 到你”以为”它该在的位置。问题是，最终落点是猜的，元素重叠了你也看不见，直到视频渲出来才发现。
正确做法：先把元素摆在它最该被看见的那一帧——完全入场、位置正确、还没开始退场。这一帧用纯静态 HTML+CSS 写死，先不碰 GSAP。
/* scene-content 撑满整个场景，用 padding 把内容推到位 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title { font-size: 120px; }
注意：内容容器要用 width/height: 100% + padding 填满场景，别用 position: absolute; top: Npx——绝对定位的内容容器，一旦内容变高就溢出。绝对定位只留给装饰元素。
静态布局对了，再加动画。入场用 gsap.from()（从屏幕外/透明，动到 CSS 里的位置），退场用 gsap.to()（从 CSS 位置，动到屏幕外）：
// 入场：动到 CSS 写好的位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
// 退场：从那个位置离开
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
一句话记牢：CSS 位置是地面真相，tween 只描述怎么走到那里。 顺序反了，你就是在盲猜布局。
进阶一瞥
跑通上面这套之后，三个方向值得知道它们存在：
- 参数化渲染。在
<html>根上用data-composition-variables声明变量（标题、颜色等），渲染时--variables '{"title":"Q4 报告"}'覆盖默认值。同一个 composition 能批量出几十个只换文案的视频——这是流水线的基础。 - 资产流水线。
npx hyperframes tts用 Kokoro 把文字转成旁白，transcribe用 Whisper 出逐词字幕，remove-background用 u2net 抠出透明视频做叠层。三者能串起来：配音 → 转写 → 字幕。 - 动画适配器。除 GSAP 外，Anime.js、Three.js 也能接入，关键是让动画”可被时间线 seek”——即确定性、逐帧可复现，而不是按真实时间自由播放。
几个坑
- 环境：渲染失败，先
npx hyperframes doctor。十有八九是 FFmpeg 没装、Chrome 缺失、或内存不够。 - 别跳过 inspect：带气泡、卡片、字幕、紧凑排版的 composition 尤其要跑，文字溢出肉眼在 preview 里容易漏。确实是入场/退场动画需要的溢出，给元素标
data-layout-allow-overflow。 - 确定性是用来上 CI 的：既然同样输入产出逐帧相同，你就能在 CI 里渲视频、用
--docker保证字节级一致。这正是它跟剪辑软件的根本区别——视频成了可复现的构建产物。
下一步
npx hyperframes docs 打开官方文档。仓库在 github.com/heygen-com/hyperframes，README 里有 “HyperFrames vs Remotion”、Catalog、Stack 等章节值得一读。要让 AI agent 直接上手，npx skills add heygen-com/hyperframes 把技能装进去。