chill/chill_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
chill_notes/AI工程/HyperFrames_HTML视频引擎研究.md
FNS Service 682e3e52df Update from Sync Service
2026-06-22 11:30:51 +08:00

9.1 KiB
Executable File
Raw Permalink Blame History

HyperFrames — HTML 视频引擎完全研究

研究日期：2026-06-01 官网：https://www.hyperframes.net/zh GitHub：https://github.com/heygen-com/hyperframes 文档：https://hyperframes.mintlify.app/introduction 开发商：HeyGen 许可证：MIT（开源引擎）

一句话概括

用 HTML 写视频。 HyperFrames 是 HeyGen 出品的开源 HTML-to-video 框架，将 HTML composition 直接渲染成 MP4，专为 AI Agent 驱动的视频生产设计。

核心理念

  • 视频的「源代码」就是 HTML 文件
  • 用 data-start、data-duration、data-track-index 等 data attribute 定义时间线
  • 动画用熟悉的 GSAP、Lottie、CSS 等任何可 seek 到指定帧的运行时
  • 确定性渲染：同一输入 → 完全相同的输出帧，可 CI 化、可回归测试
  • 不需要 React，不需要时间线编辑器，不需要专有格式

架构与包

包 作用
@hyperframes/core 类型定义、HTML 解析、composition lint
@hyperframes/engine seek 驱动的帧捕获引擎（headless Chrome）
@hyperframes/producer 捕获 + FFmpeg 编码的完整流水线
@hyperframes/studio 可视化编辑器 UI
hyperframes (CLI) 命令行工具，默认非交互，适合 Agent 自动化

渲染管线

HTML Composition → headless Chrome 逐帧捕获 (beginFrame API) → FFmpeg 编码 → MP4/MOV/WebM

渲染模式：

  • Local Mode：本地 Puppeteer + 系统 FFmpeg，开发迭代快
  • Docker Mode：确定性输出，固定 Chrome 版本 + 字体集，适合 CI/CD

Composition 模型

项目结构

project/
├── index.html          # 根 composition（视频入口）
├── compositions/       # 子 composition（可复用片段）
│   ├── intro-anim.html
│   ├── caption-overlay.html
│   └── outro-title.html
├── assets/             # 媒体素材
│   ├── video.mp4
│   ├── music.mp3
│   └── logo.png
└── meta.json           # 项目元数据

最小示例

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

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

  <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
  <script>
    const tl = gsap.timeline({ paused: true });
    tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
    window.__timelines = window.__timelines || {};
    window.__timelines["demo"] = tl;
  </script>
</div>

三条核心规则

  1. 根元素必须有 data-composition-id、data-width、data-height
  2. 定时元素需要 data-start、data-duration、data-track-index 和 class="clip"
  3. GSAP timeline 必须用 { paused: true } 创建，注册到 window.__timelines

嵌套 Composition

  • 外部文件：用 data-composition-src 引用，内容包在 <template> 里
  • 内联：直接在父 composition 里定义
  • 框架自动管理子 composition 的时间线嵌套

变量系统

  • 在 <html> 上用 data-composition-variables 声明变量（id + type + default）
  • 在实例上用 data-variable-values 传值
  • 在脚本里用 window.__hyperframes.getVariables() 读取
  • 同一个子 composition 可以多次嵌入，每次不同参数

GSAP 动画

HyperFrames 使用 GSAP 作为主要动画运行时。

关键要点

  • Timeline 必须 { paused: true }，框架控制播放
  • 通过 position 参数（第3个参数）做绝对时间定位
  • 只能做视觉属性动画，不能控制媒体播放
  • 支持的方法：to()、from()、fromTo()、set()
  • Timeline 时长 = Composition 时长（最长的动画决定总时长）

常见陷阱

  • ❌ 在脚本里 play/pause/seek 媒体元素
  • ❌ 创建非 paused 的 timeline
  • ❌ 直接在 <video> 元素上动画 width/height（用 div 包装）
  • ❌ 手动嵌套子 timeline

渲染配置

输出选项

参数 可选值 默认
--format mp4, mov, webm, png-sequence mp4
--fps 24, 30, 60 30
--quality draft, standard, high standard
--workers 1-8 或 auto auto
--gpu NVENC, VideoToolbox, AMF, VAAPI, QSV off
--docker 确定性渲染 off
--hdr / --sdr HDR 输出控制 off

环境要求

  • Node.js 22+
  • FFmpeg 7.x
  • Chrome（bundled）
  • Docker（可选，生产渲染推荐）

Agent 集成

这是 HyperFrames 的最大亮点。

为什么对 Agent 友好

  1. LLM 天生擅长生成 HTML — 不需要学新 DSL
  2. CLI 完全非交互，参数驱动，纯文本输出
  3. 可以从文档、网页、GitHub 仓库等现成内容起步
  4. 支持 Claude Code、Cursor、Gemini CLI、Codex 等 AI 编码 Agent

Skills 安装

npx skills add heygen-com/hyperframes

安装后在 Claude Code 中注册为 slash commands：

  • /hyperframes — composition 创作
  • /hyperframes-cli — init, lint, preview, render
  • /hyperframes-media — TTS、转录、背景移除
  • /tailwind — Tailwind v4 样式
  • /gsap — GSAP 时间线动画
  • 以及 /animejs、/css-animations、/lottie、/three、/waapi

示例提示词

Using /hyperframes, create a 10-second product intro with a fade-in title over a dark background.

Summarize the attached PDF into a 45-second pitch video using /hyperframes.

Turn this CSV into an animated bar chart race using /hyperframes.

Make a 9:16 TikTok-style hook video about [topic] using /hyperframes.

使用场景

场景 描述
文档转视频 onboarding、release note、帮助中心 → 解释型视频
网站转视频 产品页、发布文案 → demo、功能讲解
仓库转视频 GitHub README、架构说明 → devrel walkthrough
数据转视频 CSV、看板、指标 → 动态图表叙事
产品 demo 从提示词或 HTML 生成产品演示视频
社交媒体内容 YouTube、TikTok、短视频

Catalog 组件库

50+ 开箱即用的 blocks 和 components：

  • 字幕样式（caption-clip-wipe 等）
  • 社交 overlay
  • Shader 转场
  • 数据可视化图表
  • 电影化特效

安装方式：npx hyperframes add <component-name>

定价

开源引擎

  • 免费，本地渲染不限量
  • Docker 渲染也不收费（用自己的基础设施）

托管 Studio（hyperframes.net）

套餐 价格 积分/月 备注
入门版 $29/月（年付 $87） 500 基础功能
标准版 $99/月（年付 $297） 2,000 优先队列
高级版 $199/月（年付 $597） 8,000 最快速度
试用 免费 30 积分 新用户

积分消耗：4秒视频 = 40积分，15秒视频 = 150积分

免费浏览器工具（视频转换、缩略图、GIF、图片压缩）不扣积分。

Frame Adapters

HyperFrames 通过 Frame Adapter 模式支持多种动画运行时：

  • GSAP — 主要推荐
  • Lottie — 通过 window.__hfLottie 注册
  • CSS Animations — 原生支持
  • Three.js — 3D 场景
  • WAAPI — Web Animations API
  • Anime.js — 轻量动画库

只要运行时能 seek 到某一帧，就能通过适配器接入渲染链路。

竞品对比思考

维度 HyperFrames Remotion After Effects
视频定义方式 HTML + data attributes React + JS 时间线 GUI
Agent 适配 ⭐⭐⭐ 原生设计 ⭐⭐ 需 React ⭐ 无法自动化
确定性渲染 ✅ ✅ ❌
学习曲线 低（会 HTML 就行） 中（需 React） 高
动画运行时 GSAP/Lottie/CSS/任意 CSS/React 状态 内置
渲染依赖 Chrome + FFmpeg Chrome + FFmpeg Adobe
开源 ✅ MIT ✅ MIT ❌

评价

优点：

  • 概念非常清晰 — HTML 即视频，零新 DSL 学习成本
  • Agent 友好设计是杀手级特性，开箱即用的 skills 系统
  • 确定性渲染让视频也能 CI/CD
  • HeyGen 背书，项目活跃
  • 50+ Catalog 组件开箱即用

局限：

  • 适合结构化、信息展示类视频，不适合复杂真人特效
  • 托管 Studio 定价偏贵（相比自建）
  • 依赖 Chrome 逐帧捕获，渲染速度不如原生视频引擎
  • 生态还比较新，社区资源有限

适用人群：

  • 需要批量生成视频的开发者团队
  • 想用 AI Agent 自动化视频生产的人
  • DevRel、产品营销团队
  • 数据可视化视频制作者

快速上手

# 1. 初始化项目
npx hyperframes init my-video
cd my-video

# 2. 浏览器预览
npx hyperframes preview

# 3. 渲染 MP4
npx hyperframes render --output output.mp4

# 4. 环境检查
npx hyperframes doctor

相关链接

Reference in New Issue View Git Blame Copy Permalink