> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperframes-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速入门

> 在两分钟内创建、预览和渲染您的第一个HyperFrames视频。

从零到渲染 MP4——通过提示您的 AI 代理或手动启动项目。

## 选项 1：使用 AI 编码智能体（推荐）

安装 HyperFrames 技能，然后描述您想要的视频：

```bash theme={null}
npx skills add heygen-com/hyperframes
```

这会教您的代理（Claude Code、Cursor、Gemini CLI、Codex、[Google Antigravity](/guides/antigravity)、[GitHub Copilot CLI](/guides/copilot-cli)）如何编写正确的组合、GSAP 时间线、Tailwind v4 浏览器运行时样式和第一方适配器动画。在 Claude Code 中，技能注册为斜杠命令 — `/hyperframes` 用于合成创作，`/hyperframes-cli` 用于开发循环命令（init、lint、预览、渲染），`/hyperframes-media` 用于资产预处理（TTS、转录、背景去除），`/tailwind` 用于 `init --tailwind` 项目，`/gsap` 用于时间线动画help，以及 `/animejs`、`/css-animations`、`/lottie`、`/three` 或 `/waapi`（当组合使用这些运行时时）。调用斜杠命令显式加载技能上下文，这会在第一次产生正确的输出。

<Note>
  克劳德设计公司采用了不同的进入路径。在 GitHub 上打开 [`docs/guides/claude-design-hyperframes.md`](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/claude-design-hyperframes.md)，单击下载按钮 (↓) 保存它，然后附加到您的 Claude Design 聊天记录。它会生成有效的初稿，您可以在任何人工智能编码代理中进行完善。请参阅[克劳德设计指南](/guides/claude-design)。
</Note>

### 尝试一下：示例提示

将其中任何内容复制到您的代理中即可开始。

<CardGroup cols={1}>
  <Card title="冷启动——描述你想要什么">
    > 使用 `/hyperframes` 创建一个 10 秒的产品介绍，并在深色背景和微妙的背景音乐上淡入标题。
  </Card>

  <Card title="热启动——将现有上下文转化为视频">
    > 查看此 GitHub 存储库 [https://github.com/heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) 并使用 `/hyperframes` 向我解释其用途和架构。

    > 使用 `/hyperframes` 将随附的 PDF 总结为 45 秒的推介视频。

    > 使用 `/hyperframes` 将此 CSV 转换为动画条形图竞赛。
  </Card>

  <Card title="格式特定">
    > 使用 `/hyperframes` 制作一个关于 \[主题] 的 9 分 16 秒的 TikTok 式挂钩视频，并带有与 TTS 旁白同步的弹性字幕。
  </Card>

  <Card title="迭代——像视频编辑器一样与代理交谈">
    > 将标题放大 2 倍，切换到深色模式，并在末尾添加淡出效果。

    > 在 0:03 添加下三分之一，写上我的名字和头衔。
  </Card>
</CardGroup>

代理处理脚手架、动画和渲染。请参阅 [提示指南](/guides/prompting) 了解更多模式，或参阅 [管道指南](/guides/pipeline) 了解 AI 代理在多节拍视频中遵循的 7 步结构（设计、脚本、故事板……）。

<Tip>
  技能对 HyperFrames 特定的模式进行编码，例如定时元素上所需的 `class="clip"`、GSAP 时间线注册、适配器注册表（例如 `window.__hfLottie` 和 `data-*` 属性语义），这些模式不在通用 Web 文档中。使用技巧从一开始就可以产生正确的作品。
</Tip>

## 选项 2：手动启动项目

### 先决条件

* **Node.js 22+** — CLI 和开发服务器的运行时
* **FFmpeg** — 用于本地渲染的视频编码

<Accordion title="安装说明">
  <Steps>
    <Step title="安装 Node.js 22+">
      Hyperframes 需要 Node.js 22 或更高版本。检查您的版本：

      ```bash theme={null}
      node --version
      ```

      ```bash Expected output theme={null}
      v22.0.0   # or any version >= 22
      ```
    </Step>

    <Step title="安装 FFmpeg">
      本地视频渲染需要 FFmpeg（将捕获的帧编码为 MP4）。

      <CodeGroup>
        ```bash macOS theme={null}
        brew install ffmpeg
        ```

        ```bash Ubuntu / Debian theme={null}
        sudo apt install ffmpeg
        ```

        ```bash Windows theme={null}
        # Download from https://ffmpeg.org/download.html
        # or install via winget:
        winget install ffmpeg
        ```
      </CodeGroup>

      验证安装：

      ```bash theme={null}
      ffmpeg -version
      ```

      ```bash Expected output theme={null}
      ffmpeg version 7.x ...
      ```
    </Step>
  </Steps>
</Accordion>

### 创建您的第一个视频

<Steps>
  <Step title="搭建项目脚手架">
    ```bash theme={null}
    npx hyperframes init my-video
    cd my-video
    ```

    这将启动一个交互式向导，引导您完成示例选择和媒体导入。要跳过提示（例如在 CI 中或来自代理），请使用 `--non-interactive`：

    ```bash theme={null}
    npx hyperframes init my-video --non-interactive --example blank
    ```

    有关所有可用示例，请参阅[示例](/examples)。

    这会生成一个项目结构，如下所示：

    <Tree>
      <Tree.Folder name="my-video" defaultOpen>
        <Tree.File name="meta.json" />

        <Tree.File name="index.html" />

        <Tree.Folder name="compositions" defaultOpen>
          <Tree.File name="intro.html" />

          <Tree.File name="captions.html" />
        </Tree.Folder>

        <Tree.Folder name="assets" defaultOpen>
          <Tree.File name="video.mp4" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree>

    | 小路              | 目的                              |
    | --------------- | ------------------------------- |
    | `meta.json`     | 项目元数据（名称、ID、创建日期）               |
    | `index.html`    | 根构成——视频的入口点                     |
    | `compositions/` | 通过 `data-composition-src` 加载子组合 |
    | `assets/`       | 媒体文件（视频、音频、图像）                  |

    如果您有源视频，请使用 `--video` 传递它以进行自动转录和字幕：

    ```bash theme={null}
    npx hyperframes init my-video --example warm-grain --video ./intro.mp4
    ```

    `hyperframes init` 自动安装 AI 代理技能，因此您可以随时将其交给您的 AI 代理。
  </Step>

  <Step title="在浏览器中预览">
    ```bash theme={null}
    npx hyperframes preview
    ```

    这将启动 Hyperframes Studio 并在浏览器中打开您的合成。编辑为 `index.html` 自动重新加载。

    <Tip>
      开发服务器支持热重载 - 保存您的 HTML 文件并立即更新预览，无需手动刷新。
    </Tip>
  </Step>

  <Step title="编辑构图">
    使用您的 AI 编码智能体（Claude Code、Cursor 等）打开项目 — 技能会自动安装，您的代理知道如何创建和编辑作品。

    或者直接编辑 `index.html` — 这是一个最小的组成：

    ```html index.html theme={null}
    <div id="root" data-composition-id="my-video"
         data-start="0" data-width="1920" data-height="1080">

      <!-- 1. Define a timed text clip on track 0 -->
      <h1 id="title" class="clip"
          data-start="0" data-duration="5" data-track-index="0"
          style="font-size: 72px; color: white; text-align: center;
                 position: absolute; top: 50%; left: 50%;
                 transform: translate(-50%, -50%);">
        Hello, Hyperframes!
      </h1>

      <!-- 2. Load GSAP for animation -->
      <script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>

      <!-- 3. Create a paused timeline and register it -->
      <script>
        const tl = gsap.timeline({ paused: true });
        tl.from("#title", { opacity: 0, y: -50, duration: 1 }, 0);
        window.__timelines = window.__timelines || {};
        window.__timelines["my-video"] = tl;
      </script>
    </div>
    ```

    要记住的三个规则：

    * **根元素**必须具有 `data-composition-id`、`data-width` 和 `data-height`
    * **定时元素**需要 `data-start`、`data-duration`、`data-track-index` 和 `class="clip"`
    * **GSAP 时间线** 必须使用 `{ paused: true }` 创建并在 `window.__timelines` 上注册
  </Step>

  <Step title="渲染为 MP4">
    ```bash theme={null}
    npx hyperframes render --output output.mp4
    ```

    ```bash Expected output theme={null}
    ✔ Capturing frames... 150/150
    ✔ Encoding MP4...
    ✔ output.mp4 (1920x1080, 5.0s, 30fps)
    ```

    您的视频现在位于 `output.mp4`。使用任何媒体播放器打开它。
  </Step>
</Steps>

## 需求总结

| 依赖性             | 必需的 | 笔记                |
| --------------- | --- | ----------------- |
| **Node.js** 22+ | 是的  | CLI 和开发服务器的运行时    |
| **npm** 或面包     | 是的  | 包管理器              |
| **FFmpeg**      | 是的  | 用于本地渲染的视频编码       |
| **码头工人**        | 不   | 可选 — 用于确定性、可重现的渲染 |

## 后续步骤

<CardGroup cols={2}>
  <Card title="浏览目录" icon="grid-2" href="/catalog/blocks/data-chart">
    50 多个即用型块 — 过渡、叠加、数据可视化和效果
  </Card>

  <Card title="GSAP动画" icon="wand-magic-sparkles" href="/guides/gsap-animation">
    为您的视频添加淡入淡出、幻灯片、缩放和自定义动画
  </Card>

  <Card title="示例" icon="rocket" href="/examples">
    从 Warm Grain 和 Swiss Grid 等内置示例开始
  </Card>

  <Card title="渲染" icon="film" href="/guides/rendering">
    探索渲染选项：质量预设、Docker 模式和 GPU 加速
  </Card>
</CardGroup>