用 HTML 直接出视频：开源框架 HyperFrames 上手指南

用 HTML 直接出视频：开源框架 HyperFrames 上手指南

官网文档：https://hyperframes.heygen.com/
Playground / Studio：https://www.hyperframes.dev/
GitHub：https://github.com/heygen-com/hyperframes
npm：https://www.npmjs.com/package/hyperframes

这篇文章讲什么

做短视频、产品发布片、动效讲解，过去常见两条路：

一条是打开剪辑软件一点一点拖时间轴；

另一条是上 Remotion 这类「用 React 写视频」的框架。

前者对程序员不友好，后者又要求 JSX、打包、组件树——对AI 编程代理（coding agents）来说，门槛也不低。

HyperFrames 换了个思路：你写 HTML / CSS，加上可 seek 的动画，它帮你稳定输出确定性 MP4。

一句话：Write HTML. Render video. Built for agents.

它是 HeyGen 开源的 HTML→MP4 框架，协议Apache-2.0，本地 CLI、Agent Skills、Studio / Playground 都能用。

下面按「为什么值得试 → 环境准备 → 三步出片 → Agent 用法 → 核心能力 → 适合谁 → FAQ」写清楚，方便你照着做一遍。

一、它到底解决什么问题

1想用代码出视频，又不想上 React
组合就是普通 HTML 文件 +data-*时间属性，浏览器里能直接预览，没有强制 bundler。

2要给 AI Agent 用
Agent 本来就会写 HTML。CLI 默认非交互，Skills 教它规划、写合法 composition、lint、preview、render。装上/hyperframes路由，一句「帮我做 10 秒产品介绍」就能走完整流程。

3要确定性输出（同一输入 → 同一 MP4）
渲染走 headless Chrome 逐帧 seek，再用 FFmpeg 编码。适合 CI、回归测试、自动化内容流水线——跑两遍 hash 可以对上。

4动画库想自由选
官方适配 GSAP、CSS Animation、Lottie、Three.js、Anime.js、WAAPI，也可以接自定义 frame adapter。不是锁死在某一套时间轴格式里。

5本地免费开源，没有按次渲染费
Apache-2.0；也可选 HeyGen 云渲染或自建 AWS Lambda，看你的规模。

二、安装前先看这几条（避免踩坑）

项目

要求

运行时

Node.js ≥ 22

编码器

FFmpeg

（本机 PATH 可用）

协议

Apache-2.0

包名

hyperframes

（npm）

可选

Docker（环境更可控时用--docker渲染）

检查环境可以先跑：

class="language-bash">node -v          "color:#6a9955"># 应 ≥ v22
ffmpeg -version  "color:#6a9955"># 能输出版本信息即可

官方文档入口：https://hyperframes.heygen.com/introduction
快速开始：https://hyperframes.heygen.com/quickstart

三、完整上手：三步从零到 MP4 步骤 1：脚手架

class="language-bash">npx hyperframes init my-video
cd my-video

init会生成 composition（常见是comp.html/index.html）和package.json。项目就是普通前端目录，没有神秘黑盒。

也可以全局安装后再用：

class="language-bash">npm install -g hyperframes
hyperframes init hello-video

Composition 本质是 HTML。根节点声明画幅与时长，子节点用data-start/data-duration等声明时间。官方 quickstart 风格示例：

class="language-html">
 


 "1920" 
  data-height= 
 "1080" 
  data-duration= 
 "5" 
  data-fps= 
 "60" 
 > 

 
   



 "0" 
  data-duration= 
 "5" 
   
 class 
 = 
 "bg" 
 > 

 

 
"1" data-duration="4" data-fade="in">Hello, friend. 

 
 

一段 5 秒片子：标题在第 1 秒淡入，一直到结尾。

预览（热更新 + 时间轴控件）：

class="language-bash">npx hyperframes preview
"color:#6a9955"># 或：hyperframes preview comp.html
"color:#6a9955"># → 浏览器打开本地预览地址（常见 localhost:5173）

这时你可以拖时间轴、改 HTML/CSS，立刻看到画面变化——和写网页的心智几乎一样。

步骤 3：渲染成 MP4

class="language-bash">npx hyperframes render
"color:#6a9955"># 或指定输出：
npx hyperframes render --output final.mp4
"color:#6a9955"># 指定别的 composition：
npx hyperframes render --composition compositions/intro.html --output intro.mp4

省略--output时，结果一般落在renders/目录。需要可控 Chrome / 字体环境时：

class="language-bash">npx hyperframes render --docker --output final.mp4

渲染前建议过一遍检查：

class="language-bash">npx hyperframes lint
npx hyperframes check

输出不只 MP4：还支持 MOV、WebM、GIF、PNG 序列等（按文档--output/ 格式选项选）。透明通道场景优先 WebM 或 ProRes MOV，而不是默认不透明 MP4。

四、给 AI 编程代理用（Skills / Plugin）

这是 HyperFrames 和「又一个 HTML 渲染器」拉开差距的地方。

1）通用 Skills（含 OpenCode 等）

class="language-bash">npx skills add heygen-com/hyperframes

交互选择器默认不要全勾：先装Core Skills就够。非交互 / Agent 场景更推荐：

class="language-bash">npx hyperframes skills update

这会从当前main装齐核心集；路由 skill/hyperframes会在需要时再按需拉取具体创作工作流。

2）Claude Code 插件

class="language-bash">claude plugin marketplace add heygen-com/hyperframes
claude plugin install hyperframes"color:#6a9955">#c586c0">@hyperframes

装好后可在插件市场里给hyperframesmarketplace 开自动更新，然后用/hyperframes:hyperframes或路由/hyperframes。

3）试一句 Prompt

Using /hyperframes, create a 10-second product intro with a fade-in title, a background video, and subtle background music.

Skills 会带着 Agent 走完整生产环：策划 → 写合法 HTML → 接 seekable 动画 → 加媒体 → lint → preview → render。

4）常见创作工作流（装上后按需调用）

Skill

适合场景

/product-launch-video

产品站 / 发布片 / 站点 Tour（约 30–90 秒甜区）

/faceless-explainer

概念讲解、无真人出镜的说明片

/pr-to-video

GitHub PR → changelog / 功能演示片

/motion-graphics

短动效、Logo sting、数据击中（常 <10 秒）

/music-to-video

跟拍音乐节奏的视觉片

/embedded-captions

//talking-head-recut

口播字幕、下三分之一条、信息浮层

/general-video

更长、多场景、自由组合的兜底工作流

Showcase 成品可看：https://hyperframes.heygen.com/showcase
Catalog 可复用积木：https://hyperframes.heygen.com/catalog/blocks/data-chart

五、突出功能与特点 1. HTML-native，无强制构建

index.html能直接播；预览和渲染读的是同一套 composition，心智成本低。

2. 确定性渲染

同一输入、同一帧、同一输出。适合自动化和「内容工厂」：脚本改文案 → CI 出片。

3. Agent-first CLI + Skills

非交互默认、路由 skill、创作工作流拆开——不是事后塞个「AI 按钮」。

4.frame.md：把设计系统翻译给镜头

品牌常有design.md，但那是给网页的。frame.md把 token / 规则改写成「镜头友好」的规格，方便 Agent 按同一视觉系统出片。模板浏览：https://www.hyperframes.dev/design

5. Catalog 积木

转场、社交浮层、图表、地图等可npx hyperframes add 装进项目，少从零手搓。

6. 本地 / Docker / Lambda / 云渲染

本机迭代；Docker 锁环境；AWS Lambda 做分布式；HeyGen 也可托管云渲染——按阶段选型。

7. 和 Remotion 的定位差异（简表）

HyperFrames

Remotion

作者模型

HTML + CSS + seekable 动画

React 组件

构建

可不打包，HTML 即预览

通常需要 bundler

Agent 交接

纯 HTML 文件

JSX / React 工程

协议

Apache-2.0

Remotion 许可（另议）

详细对比：https://hyperframes.heygen.com/guides/hyperframes-vs-remotion

六、适合谁用？不适合谁？

比较适合
- 会一点 HTML/CSS，想用代码批量出片的人
- 已经在用 Claude Code / Cursor / Codex 等 Agent，想让 Agent「直接做视频」的人
- 产品发布、PR 演示、无脸讲解、短动效、数据可视化短片等场景
- 需要 CI 里稳定出同一条片的团队

暂时不太适合
- 完全不想碰代码、只想拖拽时间轴的剪辑师（更适合传统 NLE 或偏可视化的工具）
- 机器暂时升不到 Node 22、也装不了 FFmpeg 的环境
- 深度依赖 Remotion 生态、且团队已全部 React 化的项目（除非你在评估迁移；官方有/remotion-to-hyperframes单向移植 skill）

七、常见问题速答

Q：一定要会 React 吗？
A：不需要。核心作者模型是 HTML + CSS + 动画适配器。

Q：和直接用 Puppeteer 录屏有什么区别？
A：HyperFrames 面向「可 seek 的时间轴 + 确定性逐帧」，不是随便录一段页面播放。动画必须按框架约定写成可寻址，才能帧对齐、可复现。

Q：免费商用吗？
A：开源协议是 Apache-2.0，无 per-render 收费门槛；具体以仓库 LICENSE 与你使用的云服务条款为准。

Q：只有命令行吗？
A：不只。有 Studio / Playground（https://www.hyperframes.dev/），也有文档站与 Catalog；CLI 适合 Agent 与自动化。

Q：动画一定要用 GSAP 吗？
A：不是。GSAP、CSS、Lottie、Three.js、Anime.js、WAAPI 等都有适配路径，也可自定义。

Q：出片慢怎么办？
A：先本机小分辨率迭代；稳定后再拉长分辨率 / 时长；大批量可看 Docker 或 Lambda / 云渲染路径。

八、建议你这样试第一次（15 分钟验收）

1 确认 Node ≥ 22、FFmpeg 可用

2npx hyperframes init demo && cd demo

3npx hyperframes preview，改一行标题文字，确认热更新

4npx hyperframes render --output demo.mp4，用播放器打开

5 （可选）npx skills add heygen-com/hyperframes，用/hyperframes让 Agent 生成一支 5–10 秒片

这五步走通，你就已经掌握 HyperFrames 的主循环了。

结尾

视频不一定非要「打开剪辑软件才算开始」。如果你本来就会写网页——或者你的 Agent 会——HTML 可以直接变成 MP4。

HyperFrames 把「网页心智」接到「视频产出」上，特别适合想把发布片、讲解片、动效件塞进自动化流水线的人。

文档：https://hyperframes.heygen.com/introduction
Playground：https://www.hyperframes.dev/
GitHub：https://github.com/heygen-com/hyperframes
Discord：https://discord.gg/EbK98HBPdk

我是爱玩的果果，平时爱捣鼓各种 AI 工具，专挑能直接上手、不绕弯子的分享给你。

在下面小程序卡片里，可以领取HyperFrames：HTML 直接出 MP4。点一下就能跳转查看，链接清单都整理好了。