## 项目概述
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 手动安装：**
```bash
npx hyperframes init my-video
cd my-video
npx hyperframes preview # 在浏览器中预览，支持实时重载
npx hyperframes render # 渲染为 MP4
```
**使用 AI 编码代理：**
```bash
npx skills add heygen-com/hyperframes --full-depth
```
然后描述你想要的视频，例如：
> 使用 /hyperframes，创建一个 10 秒的产品介绍，包含淡入标题、背景视频和微妙的背景音乐。
## 典型使用方法
**定义视频为 HTML：**
```html
```
**渲染：**
```bash
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](https://hyperframes.heygen.com/deploy/aws-lambda)。
- **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`，音频使用单独的 `