heygen-com / hyperframes

heygen-com/hyperframes

open_in_new前往仓库

编写HTML，渲染视频。专为智能体打造。

项目概览

项目概述

HyperFrames 是一个开源框架，用于将 HTML、CSS、媒体和可搜索动画转换为确定性的 MP4 视频。它由 HeyGen 开发，旨在让 AI 代理能够轻松编写 HTML 并渲染视频。项目采用 TypeScript 编写，遵循 Apache-2.0 许可证。

核心功能

  • HTML 原生：使用 HTML 文件定义视频，无需 React 或专有时间线格式。
  • 确定性渲染：相同的输入产生相同的帧和输出，适合 CI 和自动化。
  • 无构建步骤：index.html 可直接在浏览器中预览。
  • 适配器动画：支持 GSAP、CSS、Lottie、Three.js、Anime.js、WAAPI 等。
  • 代理友好：提供 CLI 和技能，AI 编码代理可轻松使用。
  • 云渲染：支持 HeyGen 托管云渲染和 AWS Lambda 分布式渲染。
  • 组件目录：提供可复用的块和组件，如转场、叠加、字幕、图表等。
  • frame.md：将设计系统转换为适合视频的 DESIGN.md 超集。

适用与不适用场景

适用场景：

  • 产品发布视频、功能公告。
  • PR 讲解视频，带动画代码差异、旁白和字幕。
  • 数据可视化、图表竞赛、地图动画。
  • 社交媒体视频，带动态字幕、叠加和音乐。
  • 文档转视频、PDF 转视频、网站导览讲解。
  • 自动化内容管道中的可重用动态图形。

不适用场景：

  • 需要复杂交互式视频（如游戏）的场景。
  • 需要实时流媒体或直播的场景。
  • 需要非确定性动画（如基于真实时间的动画）的场景。
  • 需要大量外部资源且无法内联或公开访问的场景。

技术架构与依赖

  • 语言：TypeScript
  • 运行时：Node.js 22+，FFmpeg
  • 核心包：hyperframes（CLI）、@hyperframes/core（类型、解析器、运行时）、@hyperframes/engine（使用 Puppeteer 和 FFmpeg 的捕获引擎）、@hyperframes/producer（渲染管道）、@hyperframes/studio（编辑器 UI）、@hyperframes/player（Web 组件）、@hyperframes/shader-transitions（WebGL 着色器）、@hyperframes/aws-lambda（AWS Lambda 渲染）。
  • 依赖：GSAP、Puppeteer、FFmpeg、Bun（开发工具）。

安装与快速开始

要求：Node.js 22+，FFmpeg。

使用 CLI 手动安装：

npx hyperframes init my-video
cd my-video
npx hyperframes preview      # 在浏览器中预览，支持实时重载
npx hyperframes render       # 渲染为 MP4

使用 AI 编码代理：

npx skills add heygen-com/hyperframes --full-depth

然后描述你想要的视频，例如：

使用 /hyperframes，创建一个 10 秒的产品介绍，包含淡入标题、背景视频和微妙的背景音乐。

典型使用方法

定义视频为 HTML：

<div id="stage" data-composition-id="launch" data-start="0" data-width="1920" data-height="1080">
  <video class="clip" data-start="0" data-duration="6" 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">Launch day</h1>
  <audio data-start="0" data-duration="6" data-track-index="2" data-volume="0.5" src="music.wav"></audio>
  <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: 40, duration: 0.8 }, 1);
    window.__timelines = window.__timelines || {};
    window.__timelines.launch = tl;
  </script>
</div>

渲染：

npx hyperframes render -o output.mp4

默认 1920x1080 / 30fps，可使用 --fps 60 或 --resolution 4k 覆盖。

配置与部署要点

  • 本地渲染：使用 CLI 在本地渲染，需要 Node.js 22+ 和 FFmpeg。
  • 云渲染：使用 HeyGen 托管云渲染（cloud render）或 AWS Lambda（lambda deploy / render / progress）。
  • AWS Lambda 部署：参考文档 AWS Lambda rendering。
  • Git LFS：开发时克隆完整仓库需要安装 Git LFS，因为包含约 240 MB 的测试视频文件。
  • 技能安装：使用 npx skills add heygen-com/hyperframes --full-depth 安装技能，或使用 npx hyperframes skills update 安装核心技能集。

限制、风险与许可证

  • 许可证：Apache 2.0，无按渲染收费或商业使用门槛。
  • 确定性：必须避免 Math.random()、Date.now()、setInterval 等非确定性操作，否则渲染结果可能不一致。
  • 媒体规则：视频必须 muted playsinline，音频使用单独的 <audio> 元素，避免 Base64 媒体（除非是 Send-to 流程）。
  • 已知问题：HyperShader 浏览器模式存在异步捕获竞态条件，向后拖动可能显示空白。
  • 风险：依赖外部 CDN（如 jsdelivr）加载运行时和 GSAP，可能受网络影响。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、CONTRIBUTING.md、docs/AGENTS.md、docs/guides/claude-design-hyperframes.md、docs/guides/claude-design-send-to-hyperframes.md、docs/guides/open-design-hyperframes.md。
  • 分析时间：2026-08-11（基于最新发布版本 v0.7.106 的日期）。