快速开始
从零到渲染好的 MP4——可以通过 AI Agent 提示，也可以手动创建项目。
方式一：使用 AI 编程 Agent（推荐）
安装 HyperFrames Skills，然后描述你想要的视频：
npx skills add heygen-com/hyperframes
这将教会你的 Agent（Claude Code、Cursor、Gemini CLI、Codex、Google Antigravity、GitHub Copilot CLI）如何编写正确的合成、GSAP 时间轴、Tailwind v4 浏览器运行时样式以及官方适配器动画。在 Claude Code 中，Skills 会注册为斜杠命令——/hyperframes 用于合成编写，/hyperframes-cli 用于开发循环命令（init、lint、preview、render），/hyperframes-media 用于资产预处理（TTS、转录、背景移除），/tailwind 用于 init --tailwind 项目，/gsap 用于时间轴动画帮助，以及 /animejs、/css-animations、/lottie、/three 或 /waapi（当合成使用这些运行时时）。调用斜杠命令会显式加载 Skill 上下文，从而在第一次就产生正确的输出。
ℹ️ Note
Claude Design 使用不同的入口路径。在 GitHub 上打开
docs/guides/claude-design-hyperframes.md，点击下载按钮（↓）保存，然后附加到你的 Claude Design 聊天中。它会生成一个有效的初稿，你可以在任何 AI 编程 Agent 中进行优化。详情请参阅 Claude Design 指南。
试试看：示例提示
将以下任意提示复制到你的 Agent 中即可开始。
- 冷启动——描述你想要的内容
使用
/hyperframes，创建一个 10 秒的产品介绍视频，深色背景上带有淡入标题和柔和的背景音乐。
- 热启动——将现有内容转化为视频
请查看这个 GitHub 仓库 https://github.com/heygen-com/hyperframes，使用
/hyperframes向我介绍它的用途和架构。 > 使用/hyperframes将这份 PDF 摘要转化为一个 45 秒的推介视频。 > 使用/hyperframes将这份 CSV 数据转化为动态柱状图竞赛视频。
- 特定格式
使用
/hyperframes制作一个 9:16 竖屏 TikTok 风格的钩子视频，主题为 话题，包含与 TTS 旁白同步的弹跳字幕。
- 迭代——像视频编辑一样与 Agent 交互
把标题放大 2 倍，切换到深色模式，并在结尾添加淡出效果。 > 在 0:03 处添加一个下方三分之一字幕条，显示我的名字和头衔。
Agent 会自动处理脚手架搭建、动画和渲染。更多提示模式请参阅提示指南，多段落视频的 7 步结构（设计、脚本、分镜……）请参阅流水线指南。
💡 Tip
Skills 编码了 HyperFrames 特有的模式——例如定时元素上必须的
class="clip"、GSAP 时间轴注册、适配器注册表（如window.__hfLottie）以及data-*属性的语义——这些内容在通用的 Web 文档中找不到。使用 Skills 可以从一开始就生成正确的合成。
方式二：手动创建项目
前提条件
- Node.js 22+ — CLI 和开发服务器的运行时
- FFmpeg — 本地渲染的视频编码器
安装 Node.js 22+
Hyperframes 需要 Node.js 22 或更高版本。检查你的版本：
node --version
v22.0.0 # or any version >= 22
安装 FFmpeg
本地视频渲染（将捕获的帧编码为 MP4）需要 FFmpeg。
brew install ffmpeg
sudo apt install ffmpeg
# Download from https://ffmpeg.org/download.html
# or install via winget:
winget install ffmpeg
验证安装：
ffmpeg -version
ffmpeg version 7.x ...
创建你的第一个视频
搭建项目脚手架
npx hyperframes init my-video
cd my-video
这将启动一个交互式向导，引导你完成示例选择和媒体导入。如需跳过提示（例如在 CI 中或由 Agent 操作），使用 --non-interactive：
npx hyperframes init my-video --non-interactive --example blank
所有可用示例请参阅示例。
生成的项目结构如下：
my-video/ meta.json index.html compositions/ intro.html captions.html assets/ video.mp4
| 路径 | 用途 |
|---|---|
meta.json | 项目元数据（名称、ID、创建日期） |
index.html | 根合成——你的视频入口文件 |
compositions/ | 通过 data-composition-src 加载的子合成 |
assets/ | 媒体文件（视频、音频、图片） |
如果你有源视频，可以通过 --video 传入以自动转录和生成字幕：
npx hyperframes init my-video --example warm-grain --video ./intro.mp4
hyperframes init 会自动安装 AI Agent Skills，因此你可以随时将工作交接给 AI Agent。
在浏览器中预览
npx hyperframes preview
这将启动 Hyperframes Studio 并在浏览器中打开你的合成。编辑 index.html 后会自动重载。
💡 Tip
开发服务器支持热重载——保存 HTML 文件后预览会即时更新，无需手动刷新。
编辑合成
使用你的 AI 编程 Agent（Claude Code、Cursor 等）打开项目——Skills 已自动安装，Agent 知道如何创建和编辑合成。
或者直接编辑 index.html——这是一个最简合成：
<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%;
ransform: 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 });
l.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
渲染为 MP4
npx hyperframes render --output output.mp4
✔ Capturing frames... 150/150
✔ Encoding MP4...
✔ output.mp4 (1920x1080, 5.0s, 30fps)
你的视频已保存在 output.mp4。用任意媒体播放器打开即可。
依赖总结
| 依赖项 | 必需 | 说明 |
|---|---|---|
| Node.js 22+ | 是 | CLI 和开发服务器的运行时 |
| npm 或 bun | 是 | 包管理器 |
| FFmpeg | 是 | 本地渲染的视频编码器 |
| Docker | 否 | 可选——用于确定性、可复现的渲染 |