HyperFrames 是一个开源框架，用于将 HTML、CSS、媒体和可定位动画转换为确定性的 MP4 视频。您可以使用 CLI 在本地运行，也可以从 AI 编程代理（如 Claude Code）通过技能调用。其核心理念是：编写 HTML，渲染视频，为代理而生。

1. 系统要求

  • Node.js：版本 22+。
  • FFmpeg：用于视频编码。请确保已安装并添加到系统 PATH。
  • （可选）Git LFS：如果从源码完整克隆仓库进行开发，需要安装 Git LFS（仓库使用 LFS 存储测试用的 .mp4 基线文件）。

2. 安装

HyperFrames 提供了两种主要的使用方式：作为 AI 代理的技能（推荐）和作为命令行工具。

2.1 作为 AI 代理技能安装（推荐）

这种方式能让 AI 代理（如 Claude Code、Cursor、Gemini CLI、Codex）通过自然语言指令生成视频。

  1. 安装技能：
    在您的 AI 代理环境中运行：

    1
    npx skills add heygen-com/hyperframes

    注意：skills add 命令会打开一个交互式选择器，让您选择要安装的技能。对于大多数用例，选择 Core Skills 组即可，它包含了核心的路由器和创建流程。非交互式运行或代理应使用 npx hyperframes skills update，它会精确安装核心集。

  2. 从当前最新版本更新技能（推荐以确保使用最新功能）：

    1
    npx hyperframes skills update

  3. 在代理中使用：
    安装后，您可以直接向代理描述需求，例如：

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

    代理会自动调用相应的技能 (/product-launch-video, /faceless-explainer 等) 来规划、编写 HTML、预览并渲染视频。

2.2 作为命令行工具使用（直接操作）

如果您想手动创建视频项目，可以直接使用 CLI。

  1. 初始化项目：

    1
    2
    npx hyperframes init my-video
    cd my-video

    这会创建一个包含示例 index.html 文件的项目目录。

  2. 预览：

    1
    npx hyperframes preview

    这会在浏览器中打开一个实时预览页面，支持热重载。

  3. 渲染为 MP4：

    1
    npx hyperframes render

    渲染完成后，MP4 文件会生成在项目目录中。

3. 核心概念与工作流程

3.1 编写视频（HTML 方式）

您的视频由一个或多个 HTML 文件定义。核心是通过 data-* 属性控制时间线和轨道。

一个简单的示例 (index.html)：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
<!DOCTYPE html>
<html>
<head>
  <style>
    /* 样式定义 */
    body { margin: 0; background: #000; }
    #stage { width: 1920px; height: 1080px; overflow: hidden; }
    .clip { position: absolute; }
    #title { font-size: 80px; color: white; bottom: 100px; width: 100%; text-align: center; }
  </style>
</head>
<body>
  <div id="stage"
       data-composition-id="my-video"
       data-width="1920"
       data-height="1080"
       data-start="0"
       data-duration="10">

    <!-- 背景视频轨道 -->
    <video class="clip"
           data-start="0"
           data-duration="10"
           data-track-index="0"
           src="background.mp4"
           muted playsinline></video>

    <!-- 标题轨道（在 1 秒时出现，持续 4 秒） -->
    <h1 id="title" class="clip"
        data-start="1"
        data-duration="4"
        data-track-index="1">欢迎！</h1>

    <!-- 背景音乐轨道 -->
    <audio data-start="0"
           data-duration="10"
           data-track-index="2"
           data-volume="0.5"
           src="music.mp3"></audio>

    <!-- 动画脚本（使用 GSAP） -->
    <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: 0.8 }, 1);
      // 将时间线暴露给 HyperFrames 引擎
      window.__timelines = window.__timelines || {};
      window.__timelines['my-video'] = tl;
    </script>
  </div>
</body>
</html>

关键属性：

  • data-composition-id：唯一标识合成。
  • data-width / data-height：视频尺寸。
  • data-start / data-duration：元素在时间轴上的开始时间和持续时间（秒）。
  • data-track-index：轨道索引，用于分层（数字越大，层级越高）。
  • class="clip"：标记一个元素为视频片段。

3.2 技能（Skills）

HyperFrames 提供了 20 多个技能，分为三类：

  1. 路由器 (/hyperframes)：首先阅读。它作为能力地图，根据您的请求路由到合适的创建流程。
  2. 创建流程（如 /product-launch-video, /faceless-explainer, /pr-to-video 等）：针对特定视频类型的完整工作流。
  3. 领域技能（如 /hyperframes-animation, /hyperframes-creative, /media-use 等）：原子能力，供创建流程组合使用。

3.3 设计系统 (frame.md)

HyperFrames 引入了 frame.md 概念，这是一个专为视频创作设计的 DESIGN.md 超集。它将 Web 设计令牌（颜色、字体、间距）转化为 AI 代理可直接用于视频合成的指令，确保视觉一致性。

4. 高级功能

4.1 使用目录（Catalog）

您可以从目录中安装可复用的组件或过渡效果：

1
2
npx hyperframes add flash-through-white   # 安装一个着色器过渡
npx hyperframes add data-chart            # 安装一个动画图表

4.2 AWS Lambda 渲染

HyperFrames 支持在 AWS Lambda 上进行分布式渲染，适合大规模或自动化视频生成。请参考项目文档中的相关指南。

4.3 端口现有 Remotion 项目

如果您已有 Remotion (React) 视频项目，可以使用技能 /remotion-to-hyperframes 辅助迁移。

5. 常见问题排查

问题 可能原因 解决方案
npx hyperframes 命令未找到 Node.js 版本过低或未正确安装 确保 Node.js >= 22。可尝试全局安装：npm install -g hyperframes。
预览时页面空白 HTML 文件中的 data-* 属性缺失或路径错误 检查 data-composition-id、data-width/height 是否正确。确保引用的媒体文件（视频、音频）路径存在。
渲染失败或视频卡顿 FFmpeg 未安装或版本不兼容 确认 FFmpeg 已安装并可在命令行中调用 (ffmpeg -version)。
动画未执行 未将 GSAP/其他动画时间线暴露给 window.__timelines 确保在 <script> 中，将动画时间线赋值给 window.__timelines['合成ID']。
AI 代理无法使用 /hyperframes 技能 技能未安装或未更新 运行 npx hyperframes skills update 更新核心技能。确认代理支持技能调用。
克隆源码时提示 LFS 文件缺失 未安装 Git LFS 或未执行 git lfs pull 安装 Git LFS，然后在仓库目录运行 git lfs pull。

6. 总结

HyperFrames 为视频创作提供了一个新颖的、HTML 原生的、对 AI 友好的抽象层。

核心使用路径：

  1. 作为 AI 代理用户：
    • 运行 npx skills add heygen-com/hyperframes 安装技能。
    • 向代理描述您想要的视频（例如：“使用 /hyperframes 创建一个产品发布视频”）。
    • 代理会编写 HTML、预览并最终渲染视频。
  2. 作为 CLI 用户：
    • 运行 npx hyperframes init my-project 创建项目。
    • 编辑 index.html，使用 data-* 属性定义时间线和轨道。
    • 运行 npx hyperframes preview 预览，运行 npx hyperframes render 渲染成 MP4。

建议：对于初次使用者，推荐先通过 AI 代理 + 技能 的方式快速生成一个示例视频，以理解其能力边界。然后可以通过 CLI 手动编辑生成的 HTML，深入了解其底层的“HTML + 时间线”模型。其杀手锏在于将视频创作降维到 HTML 和声明式数据属性，使得大规模、确定性、可脚本化的视频生成成为可能。

项目地址：https://github.com/heygen-com/hyperframes