HTML is now a video format —— 把 HTML、CSS、媒体和可定格动画，编译成确定性的 MP4。

简介

HyperFrames 是由 HeyGen 开源（Apache 2.0）的一套”HTML 转视频”框架。它的核心主张很简单：把 HTML 当成视频的源格式。你像写网页一样写一段 HTML，用 data-* 属性描述时间轴、用 GSAP 描述动画、用 CSS 描述外观，框架负责把它”渲染”成一段逐帧确定（deterministic）的 MP4。

而 HyperFrames Studio（@hyperframes/studio）就是这套框架的浏览器可视化编辑器：实时预览、片段时间轴、播放控制条，改一行 HTML，预览立刻热更新（HMR）。它不是让你手动安装的独立工具——大多数情况下，一条 npx hyperframes preview 就会自动把 Studio 拉起来。

一句话定位：

  • 对人类：一个所见即所得的视频编辑界面，但底层是你能完全掌控的 HTML。
  • 对 AI Agent：HTML 是最适合大模型读写的中间格式，视频从此可以被”vibe-coding”。

它已经在 HeyGen 生产环境使用，社区采用方还包括 tldraw、TanStack 等团队。

它解决什么问题

传统的”代码生成视频”方案（如 Remotion）押注的是 React 组件，需要打包构建、需要前端工程能力。而 HyperFrames 押注的是纯 HTML：

  • 无构建步骤——index.html 本身就能直接播放。
  • Agent 友好——交接物就是一个普通 HTML 文件，大模型读写都不费劲。
  • 确定性渲染——同样的输入，每次渲染逐帧一致，适合自动化内容流水线。

这让”文档转视频””PR 转讲解视频””数据可视化动画”这类需求，第一次可以像写代码一样被版本管理、被 AI 自动化。

核心概念

理解 HyperFrames 只需要抓住四个概念：

概念说明
Composition（合成）一个带 data-composition-id 的容器，对应一段视频或子片段，本质就是一个 HTML 文件
Clip（片段）HTML 里每个带时间属性的元素（文字、图片、视频、音频、子合成）都是一个”片段”
Timeline（时间轴）用 GSAP 构建的动画时间轴，注册到 window.__timelines 上，由播放器统一驱动
Track（轨道）data-track-index 决定同轨道片段不可重叠（注意：它不影响视觉层级，层级用 CSS z-index）

关键的 data-* 属性

所有片段通用：

属性是否必填取值
id是元素唯一 ID
data-start是起始秒数，或引用其他片段 ID（如 "el-1"、"intro + 2"）
data-durationimg / div / 合成必填持续秒数；视频 / 音频默认取媒体时长
data-track-index是整数轨道号，同轨道不可重叠
data-media-start否媒体源的裁剪偏移（秒）
data-volume否0–1，默认 1

合成片段额外用 data-composition-id、data-width / data-height（如 1920×1080 或竖屏 1080×1920）、可选 data-composition-src 指向外部 HTML 子合成。

快速入门

环境要求：Node.js 22+ 与 FFmpeg。

HyperFrames 提供三条上手路径，从”全自动”到”全手动”任选。

路径一：交给 AI 编程助手（最快）

安装官方 skills，然后直接用自然语言描述你想要的视频：

1
npx skills add heygen-com/hyperframes

然后对你的 Agent（Claude Code、Cursor、Gemini CLI、Codex 等支持 skills 的工具）说：

用 /hyperframes，做一个 10 秒的产品介绍：标题淡入、背景视频、轻柔背景音乐。

这套 skills 会教会 Agent 完整的制作闭环：规划 → 写合法 HTML → 接可定格动画 → 加媒体 → lint → 预览 → 渲染。

路径二：用 CLI 手动创建

1
2
3
4
npx hyperframes init my-video    # 初始化项目
cd my-video
npx hyperframes preview          # 浏览器里打开 Studio，热更新预览
npx hyperframes render           # 渲染成 MP4

npx hyperframes preview 启动的就是 HyperFrames Studio——你的合成被加载进一个隔离的 iframe（注入运行时，保证预览路径与生产一致），左侧改 HTML，右侧实时出画面，保存即刷新。

常用命令一览：init（建项目）、preview（Studio 预览）、lint / validate（校验）、render（出片）、transcribe（转写字幕）、tts（文本转语音）。

路径三：把 Studio 嵌进自己的应用

只有当你想把这个编辑器嵌入到自己的产品里时，才需要单独安装：

1
npm install @hyperframes/studio

一个最小可运行的示例

下面是一个标准 index.html：根合成（main index.html）直接把 data-composition-id 放在 <body> 里，不要用 <template> 包裹（<template> 只用于通过 data-composition-src 外链的子合成，否则会隐藏内容、导致渲染失败）。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8" />
  <style>
    [data-composition-id="intro"] {
      background: #0b0f1a;
      color: #f5f7fa;
      font-family: "Inter", sans-serif;
    }
    .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; font-weight: 800; }
    .subtitle { font-size: 42px;  opacity: .8; }
  </style>
</head>
<body>
  <!-- 根合成：1920×1080，时长 6 秒 -->
  <div data-composition-id="intro" data-width="1920" data-height="1080"
       data-start="0" data-duration="6">
    <div class="scene-content">
      <div class="title">HyperFrames</div>
      <div class="subtitle">HTML 现在是一种视频格式</div>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });   // 必须 paused，由播放器接管
      // 先布局后动画：从隐藏状态「入场」到 CSS 里写好的最终位置
      tl.from(".title",    { y: 60, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.2);
      tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.5);
      window.__timelines["intro"] = tl;             // 必须注册，否则不播放
    </script>
  </div>
</body>
</html>

npx hyperframes preview 看效果，npx hyperframes render 出 MP4。注意三个”契约”：所有时间轴 paused: true、每个时间轴都要注册到 window.__timelines、时长由 data-duration 决定而非 GSAP 时间轴长度。

案例：能用它做什么

官方 Showcase 里这些都是 HTML 写出来的成片，给你一些灵感方向：

  • 产品发布 / 功能预告片——标题动效 + 背景视频 + 配乐。
  • PR 讲解视频——动画代码 diff + 旁白 + 字幕，自动化生成”这次改了什么”。
  • 数据可视化——图表竞速（chart race）、地图动画、统计动效。
  • 社交短视频——动感字幕（kinetic captions）、贴纸叠层、卡点配乐。
  • 文档 / PDF / 网页转视频——把一篇说明转成讲解短片。
  • 可复用的动态模板——为内容流水线批量出片。

配套能力让这些案例更落地：

  • frame.md / DESIGN.md——把品牌设计系统”翻译”成镜头语言（颜色、字体、运动规则），让 Agent 不用猜尺寸就能出符合品牌调性的片子。
  • 字幕与配音——transcribe 转写、tts 文本转语音，字幕可按词与音频精确同步（卡拉 OK 式高亮）。
  • 音频反应动画——节拍同步、随音乐脉冲/发光。
  • 转场库——交叉淡化、擦除、揭示，以及 @hyperframes/shader-transitions 的 WebGL 着色器转场。
  • 分布式渲染——@hyperframes/aws-lambda 把渲染搬到 Lambda 上批量并行。

建议用法（最佳实践）

这部分浓缩了官方 skills 里的”硬规则”，照着做能少踩 90% 的坑。

1. 先布局，后动画

先用静态 HTML + CSS 把每个场景”最饱满的一帧”（hero frame）摆好——所有元素都在最终位置、完全可见。然后再用 gsap.from() 让它们从屏外/透明”入场”到这个位置。CSS 的位置才是基准，动画只是描述”如何到达”。

  • .scene-content 用 width:100%; height:100%; padding; flex 撑满场景，绝不要用 position:absolute; top:Npx 定位内容容器（内容超高会溢出）。绝对定位只留给装饰元素。

2. 转场即出场：多场景的铁律

  • 场景之间永远用转场，不要硬切。
  • 每个场景的每个元素都要有入场动画（gsap.from()），不允许元素”凭空出现”。
  • 除最后一个场景外，禁止任何出场动画——转场本身就是出场，上一个场景在转场开始的那一刻必须是完整可见的。只有最后一幕允许淡出（如淡入黑场）。

3. 保持确定性

渲染要逐帧可复现，所以：禁用 Math.random()、Date.now() 及一切基于真实时间的逻辑。需要伪随机就用带种子的 PRNG（如 mulberry32）。同样地，时间轴必须同步构建——不要写在 async/setTimeout/Promise 里，因为捕获引擎在页面加载后会同步读取 window.__timelines。

4. 把媒体交给框架

  • 视频元素必须 muted playsinline，音频永远用独立的 <audio>（视频静音 + 单独音轨）。
  • 不要手动调用 video.play() / audio.play() / seek——播放与定位归框架管。
  • GSAP 只动画视觉属性（opacity、x/y、scale、rotation、颜色、transform 等），不要动画 visibility、display 或视频元素本身的尺寸（要缩放就套一层 wrapper）。
  • 禁止 repeat: -1 的无限循环——会拖垮捕获引擎，请按时长算出有限次数：repeat: Math.ceil(duration / cycleDuration) - 1。

5. 设计先行 + 渲染前必校验

  • 动手写合成前先定义视觉身份（DESIGN.md / 命名风格），别用 #333、Roboto 这种默认值糊弄。
  • 字体直接在 CSS 里写 font-family 即可，编译器会自动内嵌受支持的字体。
  • 出片前跑 npx hyperframes lint 和 npx hyperframes validate——后者默认做 WCAG 对比度审计（截图采样文字背后的背景像素算对比度），不达标会告警。标题 60px+、正文 20px+、数据标签 16px+，数字列用 font-variant-numeric: tabular-nums。

HyperFrames vs Remotion

HyperFramesRemotion
创作模型HTML + CSS + 可定格动画React 组件
构建步骤无，index.html 直接播放需要打包
Agent 交接纯 HTML 文件JSX / React 工程
分布式渲染本地 + AWS LambdaRemotion Lambda（更成熟）
许可证Apache 2.0源码可见的 Remotion License

简单说：追求 Agent 自动化、零构建、纯 HTML 心智，选 HyperFrames；已有成熟 React 体系、需要复杂组件复用，Remotion 仍然很能打。

适用与不适用

适合：程序化/批量出片、AI 自动生成视频、文档/数据转视频、需要版本管理与可复现的内容流水线、前端背景的团队做营销/讲解片。

不太适合：实时拍摄剪辑、强调时间线手剪的传统影视后期、对帧级特效/调色有专业 NLE 需求的场景——这些用 Premiere / DaVinci 这类工具更顺手。

结语

HyperFrames 把视频生产拉进了”代码”的世界：可读、可 diff、可版本化、可被 AI 自动化，而 Studio 给了你一个所见即所得的窗口去观察这一切。对于天天和 HTML、和大模型打交道的开发者来说，它把”做一段视频”的门槛，从”学一套剪辑软件”降到了”写一个网页”。

如果你正在搭内容/营销自动化，或者想让 Agent 帮你批量出讲解视频，非常值得花半小时 npx hyperframes init 跑一遍。

参考资源