HyperFrames 中文文档
快速入门

简介

编写 HTML，渲染视频，为 AI Agent 而生。

Hyperframes 是一个开源框架，能够将 HTML 转换为确定性的逐帧渲染视频——让你像构建网页一样定义视频。

效果展示

这是一个完全用 HTML 定义的视频：

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

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

<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>

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

运行 npx hyperframes render --output demo.mp4 即可生成一个确定性的逐帧捕获 MP4 文件。相同的输入，每次输出完全一致。无需时间轴编辑器，无需专有格式，只需 HTML。

  • 观看展示作品 可以观看、阅读、运行和二次创作的 HyperFrames 视频成品——产品发布、网站转视频演示、UI 展示和视觉特效实验。
  • 浏览组件库 50 多个开箱即用的组件——社交叠加层、着色器转场、数据可视化和影视特效。一条命令即可安装。
  • 快速开始 从零到渲染视频，只需不到 5 分钟。

为什么选择 Hyperframes？

面向开发者

你已经熟悉这套技术栈。 合成就是带有 data 属性的 HTML 文件。动画可以使用 GSAP、Lottie、CSS 或任何支持帧定位的运行时。没有自定义 DSL，没有专有组件系统，不需要 React。如果你能构建网页，就能构建视频。

面向 AI Agent

Agent 天然理解 HTML。 大多数视频工具需要复杂的 API 或拖拽界面，Agent 无法操作。Hyperframes 的合成就是普通的 HTML 文档——这是 LLM 最擅长生成的格式。CLI 默认非交互模式——所有输入通过参数传递，纯文本输出，遇到错误立即退出——因此 Agent 可以在无需提示或解析的情况下驱动每条命令。

面向自动化流水线

设计上即保证确定性。 渲染流水线基于帧定位，不依赖挂钟时间。frame = floor(time * fps)——每一帧通过 Chrome 的 beginFrame API 独立捕获，并由 FFmpeg 编码。相同的输入始终产生完全一致的输出，使 CI 测试和批量渲染更加可靠。

💡 Tip

Hyperframes 从设计之初就面向 AI Agent 集成。合成是任何 LLM 都能生成的普通 HTML。CLI 默认非交互模式——通过参数驱动，纯文本输出——因此 Agent 可以在没有交互提示的情况下完成脚手架搭建、渲染和代码检查。添加 --human-friendly 可使用交互式终端 UI。详情请参阅 CLI。

工作原理

编写 HTML

将你的视频定义为 HTML 文档。每个元素通过 data 属性控制时序（data-start、data-duration）和布局（data-track-index）。使用 GSAP、Lottie、CSS 过渡或通过 Frame Adapter 模式集成任何支持帧定位的运行时来添加动画。

在浏览器中预览

运行 npx hyperframes preview 在浏览器中打开实时预览。编辑 HTML 后即时看到变更——无需构建步骤，无需编译。

渲染为 MP4

运行 npx hyperframes render --output output.mp4 生成最终视频。引擎在无头 Chrome 中逐帧定位，通过 beginFrame 捕获画面，并将结果通过 FFmpeg 编码。可在本地或 Docker 中运行，确保输出完全可复现。

核心包

  • @hyperframes/core 类型定义、HTML 解析、运行时和合成代码检查器——所有其他模块的基础。
  • @hyperframes/engine 支持帧定位的页面到视频捕获引擎。在无头 Chrome 中加载 HTML 并逐帧捕获。
  • @hyperframes/producer 完整的渲染流水线，将捕获和 FFmpeg 编码组合为一次 API 调用。
  • @hyperframes/studio 可视化合成编辑器 UI，用于交互式构建和预览时间轴。
  • hyperframes (CLI) 用于创建、预览和渲染合成的命令行工具。

下一步

  • 展示作品 从成品视频和产品发布项目中获取灵感。
  • 快速开始 60 秒构建并渲染你的第一个视频
  • 合成 了解每个视频背后的基于 HTML 的数据模型
  • GSAP 动画 使用 GSAP 添加时间轴驱动的动画
  • 渲染 在本地、Docker 或 CI 流水线中渲染

快速开始

在两分钟内创建、预览和渲染你的第一个 Hyperframes 视频。