HyperFrames
概览
HyperFrames 是 HeyGen 开发的一个开源(Apache-2.0)框架,可将 HTML、CSS、媒体和动画转换为确定性 MP4 视频——相同的输入始终产生相同的输出。它解析用 data-* 时序属性注释的 HTML 组合,驱动无头 Chrome 定位并捕获每一帧,然后通过 FFmpeg 编码输出。无需构建步骤、不需要 React、也没有按次渲染的费用。它被设计为对智能体友好:CLI 默认非交互式,因此可以无缝集成到自动化内容管线中。
使用此技能可以搭建项目、编写 HTML 组合、通过实时重载预览,并渲染帧精确的视频——包括由 GSAP、CSS、Lottie、Three.js、Anime.js 或 Web Animations API 驱动的动画。
说明
前提条件
在开始之前确认环境:
- Node.js 22+(
node --version) - FFmpeg 在 PATH 中(
ffmpeg -version) - 引擎在首次运行时会自动下载无头 Chrome/Chromium。
搭建项目
npx hyperframes init my-video # 搭建项目(创建 index.html + package.json)
cd my-video
对于已有的 AI 智能体工作区中的智能体管理设置,可以使用以下命令安装技能:
npx skills add heygen-com/hyperframes。
编写组合
组合是纯文本的 index.html 文件。根舞台元素声明画布和组合 id;子元素通过 data-* 属性声明它们出现的时间和持续时间。时间值以秒为单位。
| 属性 | 用途 |
|---|---|
data-composition-id | 命名组合(用于渲染/检查的目标) |
data-start | 元素进入时间轴的时间(秒) |
data-duration | 元素在时间轴上停留的时间(秒) |
data-width / data-height | 画布尺寸(像素,用于舞台元素) |
data-track-index | 堆叠音频或视频的层/轨道顺序 |
data-volume | 音频音量,0.0–1.0 |
预览和渲染
npx hyperframes preview # 使用实时重载的浏览器预览
npx hyperframes render # 在无头 Chrome 中定位每一帧,通过 FFmpeg 编码为 MP4
npx hyperframes lint # 渲染前验证组合结构
npx hyperframes inspect # 打印组合元数据(时长、轨道、尺寸)
分辨率来自舞台上的 data-width/data-height;帧率、输出路径和编码器是渲染参数(请查阅 npx hyperframes render --help 以获取你安装版本的确切标志,因为标志名称会演变)。由于输出是确定性的,对未更改的输入重新渲染可以安全缓存。
使用组件目录
预构建块(过渡、覆盖层、字幕、动画图表、地图、效果)可以安装到项目中:
npx hyperframes add flash-through-white # 一个过渡
npx hyperframes add data-chart # 一个动画图表块
npx hyperframes add instagram-follow # 一个社交覆盖层
在 hyperframes.heygen.com/catalog 浏览完整目录,然后通过名称 add 块。
动画
任何可定位、帧精确的动画都可以使用,因为引擎会确定性地定位每个时间轴位置,而不是实时录制。支持的适配器:GSAP、CSS 动画、Lottie、Three.js、Anime.js、WAAPI 以及自定义帧适配器。避免基于时间的随机性或 Date.now()/挂钟驱动的运动——将动画进度绑定到组合时间轴,以确保定位是可重现的。
智能体 / CI 管线
CLI 是非交互式的,因此典型的自动化流程是:生成/模板化 HTML → hyperframes lint → hyperframes render → 收集 MP4。对于大规模作业,@hyperframes/aws-lambda 包支持跨 Lambda 分布式渲染。
示例
示例 1:渲染一个产品发布组合
index.html:
<div id="stage" data-composition-id="launch"
data-start="0" data-width="1920" data-height="1080">
<video data-start="0" data-duration="6" src="intro.mp4"></video>
<h1 id="title" data-start="1" data-duration="4">发布日</h1>
<audio data-start="0" data-duration="6" data-volume="0.8" src="music.wav"></audio>
</div>
npx hyperframes inspect # 确认:launch,6秒,1920x1080
npx hyperframes lint # 在花费渲染时间前进行验证
npx hyperframes render # 生成一个 1080p MP4
示例 2:一个可定位的 GSAP 标题动画
<div id="stage" data-composition-id="title-card"
data-start="0" data-width="1080" data-height="1080">
<h1 id="headline" data-start="0" data-duration="3">第三季度结果</h1>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
// 将进度绑定到时间轴(引擎定位的暂停补间),而不是实时时间。
const tl = gsap.timeline({ paused: true });
tl.from("#headline", { y: 80, opacity: 0, duration: 1 })
.to("#headline", { scale: 1.05, duration: 2 });
window.__seek = (t) => tl.seek(t); // 引擎每帧调用此函数
</script>
</div>
npx hyperframes preview # 实时迭代,然后:
npx hyperframes render
指南
- 确定性优先。 将所有运动绑定到组合时间轴。在渲染过程中避免使用
Math.random()、Date.now()、实时循环或网络调用——它们会破坏可重现性。 - 渲染前先检查。
hyperframes lint可以廉价地捕获结构和时序错误;渲染是昂贵的步骤。 - 在舞台元素上设置画布。
data-width/data-height位于根组合元素上;子元素的时序(data-start/data-duration)位于每个元素上,单位为秒。 - 验证工具链。 大多数故障可以追溯到缺少 FFmpeg 或 Node < 22,或防火墙阻止的 Chromium 下载。
- 使用
--help查看确切的标志。render/add选项因版本而异;根据安装的 CLI 确认 fps/输出/编码器标志,而不是假设。 - 优先使用目录块。
hyperframes add拉取维护良好、可定位的组件,而不是手动编写过渡和图表。 - 使用 Lambda 扩展。 对于批处理/大型作业,通过
@hyperframes/aws-lambda进行渲染,而不是一个耗时的本地作业。 - 保持媒体文件本地化并提交到版本控制。 通过稳定的路径引用资源;渲染期间的远程获取会破坏确定性和可重现性。