hyperframes-helper

Hyperframes 助手

使用 Hyperframes 制作动态图形视频的实用工具包——Hyperframes 是 HeyGen 的开源 HTML 转 MP4 渲染器。提供三个级别的工作量，分别对应三种不同目标。

什么是 Hyperframes

Hyperframes 是一个开源视频合成框架。你编写 HTML/CSS/GSAP，它会将其渲染为确定性的 MP4。输出看起来像动态图形；源文件只是一个网页。因此它适合 Agent 原生使用——大模型一次就能写好，无需折腾 React/Remotion 打包器。

• GitHub： https://github.com/heygen-com/hyperframes
• 文档： https://hyperframes.heygen.com
• 许可证： Apache 2.0——免费、完全本地运行，无需 HeyGen API 密钥

安装 Hyperframes

你只需要 Node.js。Hyperframes 通过 npx 运行：

# Verify Node is available
node --version

# See what Hyperframes can do
npx hyperframes@latest --help

# Scaffold a new project
npx hyperframes@latest init my-video
cd my-video

# Add the official agent skills (gives you /hyperframes, /gsap, /website-to-hyperframes)
npx skills add heygen-com/hyperframes

# Open Studio (live preview at http://localhost:3002)
npx hyperframes@latest preview

# Lint your composition
npx hyperframes@latest lint

# Render to MP4
npx hyperframes@latest render -o output.mp4 --fps 30

首次渲染时会下载 Chrome（约 101 MB），只需下载一次。之后会使用缓存。

这个工具包构建在 Hyperframes 之上——当你确定要使用哪个级别后，就可以使用这一层模式、模板和配方。

---

三个级别

复杂度下限取决于你的需求。选择适合的级别。

---

级别 1 · 网页转视频

最快的方式。你已有网页 / 组件 / 动画 CSS——将其转换为 MP4。

适用场景：

• 你在网上找到一个精美的动画组件，想制作一个 6 秒的循环视频
• 你有一个品牌网站，想把 15 秒的首屏动画做成视频文件
• 你想快速录制一个交互式演示

操作方法：

# In your Hyperframes project
/website-to-hyperframes

官方 Hyperframes 网页转视频技能可端到端完成此操作。它会捕获页面，将其封装为 Hyperframes 合成，然后进行渲染。更多信息请参阅 Hyperframes 文档。

查找优质源 HTML 的途径：

• 21st.dev — 高质量 React 组件示例。许多组件都很适合作为 Hyperframes 场景使用——去掉 React 外层封装，保留 HTML/CSS/动画即可。
• CodePen — 搜索“shader”“particles”“loader”，有很多自包含的动画 CSS 作品。
• Hyperframes 注册表 — 运行 npx hyperframes@latest catalog 可查看 Hyperframes 自带的区块 / 组件。

输出： 一个确定性的 MP4，按你选择的 fps 捕获。

---

级别 2 · 故事板

你要从头制作原创动态图形，并希望在投入实际合成之前先迭代布局。在 Studio 中迭代每轮约需 15 分钟，而迭代故事板 HTML 每轮约需 1 分钟。

适用场景：

• 原创动态图形视频（片头、吸引观众的开场、广告、课程预告）
• 你有创作简报，但还没有明确的镜头列表
• 你想在编写 GSAP 前分享视觉方案

操作方法：

1. 将 templates/storyboard-template.html 复制到项目中，命名为 storyboard.html
2. 填写场景卡片：按比例缩放的 1920×1080 布局预览 + 每个场景的动作说明
3. 在浏览器中打开，并将文件路径分享给审核者
4. 在 HTML 中迭代——拖动预览框中的元素，重写动作说明
5. 确认方案后，再进入实际合成阶段

故事板模板内置：

• 带标题、元信息标签和水平比例时间轴的页眉
• 用于导航的粘性目录
• 场景卡片（双栏布局：缩放后的布局预览 + 说明面板）
• 预设样式的占位元素：视频帧、文本面板、示例卡片、水印、动作箭头
• 与合成模板相同的字体排版和颜色变量

审核者可使用的标注方式：

• 打开文件，内联添加 `` 标签
• 截取页面并绘制箭头
• 直接在聊天中描述：“场景 3 应该 X”

为什么这能节省时间： 每次故事板迭代发现布局错误，都能帮你省下一个 15 分钟的合成—检查—预览周期。五轮故事板迭代相当于一轮合成迭代。

第 3 级 · 引导视频

完全定制制作，以真实摄像机录制为核心。完整的 RoboNuggets 流程——分为三个步骤：

┌──────────────┐    ┌─────────────────┐    ┌───────────────────┐
│ STEP 01      │ ─→ │ STEP 02         │ ─→ │ STEP 03           │
│ Cut the      │    │ Storyboard the  │    │ Add in motion     │
│ Video        │    │ Title Cards     │    │ graphics          │
└──────────────┘    └─────────────────┘    └───────────────────┘

适用场景：

• 对镜讲述的开场和结尾
• 你出镜的课程开场
• 任何需要剪辑真实录制内容并叠加动态图形的视频

步骤 01 · 剪辑视频

分两轮处理——先剪掉静音，再剪掉重录片段。两轮都使用 ffmpeg。

第一轮 — 剪掉静音（templates/silence-cut.sh）

ffmpeg -i input.mkv -af "silencedetect=noise=-30dB:d=0.4" -f null - 2>&1 | grep silence

这会输出所有静音片段。为每段静音的两端各加上 0.04s 的缓冲，构建保留范围，然后使用紧凑的 1s GOP 关键帧重新编码（适用于 Hyperframes）。模板包含完整的 filter_complex trim/atrim/concat 框架。

第二轮 — 转录（templates/transcribe-whisper.py）

pip install faster-whisper
python templates/transcribe-whisper.py input_silence_cut.mp4

输出包含词级时间戳的 *.transcript.json + *.transcript.txt。

为什么使用 faster-whisper 而不是 WhisperX：torchaudio 在 Windows 上不稳定（libtorchaudio 加载错误）。faster-whisper 使用 CTranslate2——无需依赖 torch。

第三轮 — 剪掉重录片段（templates/cut-retakes.py）

根据词级转录识别重录片段。应用保留最后一次规则：重复说同一句话时，只保留最后一次录制，并剪掉之前的所有内容（说到一半停下的片段、早先的尝试、“让我重新开始”之类的标记）。将你的 KEEPS 范围填入脚本并运行。

**替代工具：**如果你想跳过手动处理，video-use 是一款自动化视频编辑 Agent，可以剪掉填充词和说到一半停下的片段。每次运行较慢，可微调的选项较少，但无需编写脚本。

**提示：**提供一份 script-review.html，并排展示“当前脚本与建议的精简脚本”，用红色删除线标出重录片段，用绿色突出最后一次录制，并附上一张带编号的剪辑表（范围、时长、剪掉的内容、原因）。这样审核者就能在重新编码前批准剪辑。

步骤 02 · 为标题卡片制作分镜

这是第 2 级的内容，应用于更大的制作流程中。使用 templates/storyboard-template.html 规划将叠加在剪辑后视频上的标题卡片／叠加场景。

常见的标题卡片样式：

• 悬浮卡片：放在屏幕一侧（右侧或左侧），每个口述节拍配一张，并根据转录内容调整节奏
• 居中大字：用于重要时刻——“重大升级”、“开源”、“免费且开源”
• 动态高亮（弧形下划线、发光文字、脉动边框）
• 品牌角标胶囊（左上角状态胶囊、右上角计数器、左下角品牌胶囊）

可在 templates/recipes.md 中查看可直接复制粘贴的实现方案。

步骤 03 · 添加动态图形

在画面中心位置呈现、并在特定节拍出现的动态图形。常见样式：

• 着色器闪光 — 将 Three.js 片元着色器用作时长 0.5–1s 的转场点缀
• 线框地球仪 — 在透明画布上使用 D3 geoOrthographic 绘制国家轮廓和半色调圆点
• 色度键抠像角色 — 在绿幕上翻转 3D 渲染图标，再通过 SVG feColorMatrix 滤镜抠除背景
• Logo 组合动画 — 各片段依次淡入，然后循环呼吸动画
• 结尾大字 + 图标 — 最后的标语搭配一排品牌标志

每种样式都可以在 templates/recipes.md 中找到可直接复制粘贴的实现方案。

**构图提示：**让每个动态图形从画布中央开始，然后将它滑向一侧，同时让另一侧的标签淡入。三个依次呈现的动态图形就能讲述一个故事，又不会显得拥挤。

---

关键框架规则（lint 易错点）

以下规则不可妥协——每一条如果被忽略，都会导致 Hyperframes lint 报错：

1. 每个定时元素都需要 class="clip" + data-start + data-duration + data-track-index。 无一例外。

2. GSAP 绝不能为 clip 元素添加动画。 框架会管理 clip 的可见性。对 class="clip" 的 div 添加 opacity/visibility 动画会触发 gsap_animates_clip_element 错误。解决方法：为每个场景套上外层 clip-shell，并在里面放置可添加动画的 div。

3. 同一轨道上的 clip 不能重叠（哪怕只有 0.001 秒）。 浮点精度会带来问题——start=23.85, duration=4.55 会在 28.400000002 结束，与 start=28.40 冲突。可以将时长改为 4.54，或移到其他轨道。

4. 视觉上会重叠的元素需要放在不同轨道上。 四张同时可见的示例卡片 → 分别放在轨道 12、13、14、15 上。

5. GSAP 时间轴必须暂停并注册。

   window.__timelines = window.__timelines || {};
   const tl = gsap.timeline({ paused: true });
   // ... tl.from(...) ...
   window.__timelines["main"] = tl;  // matches data-composition-id
   

6. 只能使用确定性逻辑。 不要使用 Math.random()、Date.now() 或 fetch()。渲染采用逐帧 seek。

7. 视频使用 muted + 单独的 <audio> 元素。 通过 <video> 标签播放音频会破坏帧 seek。

8. 源视频需要密集的关键帧（1s GOP）。

   ffmpeg -i in.mp4 -c:v libx264 -preset fast -crf 18 \
     -r 30 -g 30 -keyint_min 30 \
     -force_key_frames "expr:gte(t,n_forced*1)" \
     -c:a aac -b:a 192k -movflags +faststart out.mp4
   

9. 基于 Canvas 的动画必须在时间轴每次更新时重绘。 不要使用 requestAnimationFrame。使用 tl.eventCallback('onUpdate', () => drawCanvas(tl.time()))。

10. clip 元素不严格要求 hard kill。 框架会在 clip 结束时硬切。不要对 clip 元素使用 tl.set(..., {visibility: hidden})。

11. 禁止使用 repeat: -1（无限循环）。 lint 错误：gsap_infinite_repeat。根据保持时长计算有限的重复次数：

    const HOLD = 6.0, CYCLE = 1.6;
    const repeats = Math.max(0, Math.floor(HOLD / CYCLE) - 1);
    tl.to('.element', { ..., repeat: repeats, yoyo: true });
    

12. 多个 <audio> 元素使用相同的 src 会造成回声。 框架会控制 clip 的可见性，但在 Studio 预览中，多个预加载的音频元素仍会同时播放。请使用一个指向预先剪好的干净音频文件的 <audio> clip。

13. 不能为伪元素（::before / ::after）添加 GSAP 动画。 请替换为真实的 DOM 子 div。

14. Studio 自动分配的内联 style="z-index: N" 可能会导致层级反转。 如果在 Studio 编辑后，十六进制背景或暗角效果显示在视频上方，请批量移除内联 z-index：

    import re
    s = open('index.html').read()
    out = re.sub(r' style="z-index: \d+"', '', s)
    open('index.html', 'w').write(out)
    

15. contracted-video 画面的层叠上下文易出问题。 如果 #videoFrame { z-index: 2 }，没有 z-index 的同级浮动文本会被压在它下方。可以为浮动文本设置明确的 z-index ≥ 2，或者移除 videoFrame 的 z-index，并将要置于其后方的元素（例如 shader）放在 DOM 中、videoFrame 之前。

16. z-index: -1 会使元素陷在 body 背景后面。 当 body { background: #000 } 时，z-index: -1 的元素会渲染在 body 背景绘制层后面，因此不可见。请改用 DOM 顺序——将要置于后方的元素放在 DOM 中较前的位置，不要设置 z-index。

多 clip 剪辑模式（可在 Studio 中拖动剪辑点）

Hyperframes Studio 明确无法在源素材中途拆分 clip（根据文档说明）。解决方法：

将未剪辑的源文件保留在磁盘上，然后在时间轴上定义多个 <video> clip，每个 clip 设置不同的 data-media-start。在 Studio 中拖动任意 clip 的左侧手柄，即可实时微调该片段的剪辑边界——无需重新运行 ffmpeg。

<div id="videoFrame">
  <video class="stage-video clip" data-start="0.00" data-duration="2.56"
         data-media-start="2.24" data-track-index="2" muted playsinline preload="auto"
         src="assets/source-uncut.mp4"></video>
  <video class="stage-video clip" data-start="2.56" data-duration="3.74"
         data-media-start="9.12" data-track-index="3" muted playsinline preload="auto"
         src="assets/source-uncut.mp4"></video>
  
</div>

权衡：音频无法用这种方式拆分（规则 12——会产生回声）。请使用 cut-retakes.py 预先剪出一个干净的音频文件，并使用一个 <audio> clip。在 Studio 中拖动视频边界时，需要重新剪辑音频以保持同步。

如果是一次性交付，无需在 Studio 中拖动编辑，请使用单个经 ffmpeg 剪辑的 source.mp4 和单个 <audio> source.mp4——更简单。

Studio 编辑限制（依据官方文档）

Studio 仅支持：

• ✅ 水平拖动片段 → 更新 data-start
• ✅ 在行之间拖动片段 → 更新 data-track-index
• ✅ 拖动右侧手柄 → 更新 data-duration（尾部修剪）
• ✅ 拖动媒体片段的左侧手柄 → 更新 data-start + data-media-start（从素材源头部修剪）
• ✅ 垂直重新排列行 → 更新内联 z-index
• ❌ 从素材中间拆分／剪切片段
• ❌ 修剪非媒体（动画）片段的头部
• ❌ 键盘快捷键
• ❌ 多选
• ❌ 撤销／重做

来源：https://hyperframes.heygen.com/guides/timeline-editing

以最高质量渲染

cd [project] && npx hyperframes@latest render \
  -o renders/final.mp4 \
  --fps 30 --quality high --crf 16 --gpu

• --quality high — 最高质量档位
• --crf 16 — 接近视觉无损（数值越低文件越大、质量越高；标准值为 18-23）
• --gpu — GPU 编码
• 在 16 核处理器上的渲染时间：30 秒的视频合成（含视频 + GSAP）约需 2.5–3 分钟

可以并行运行两次渲染——Hyperframes 每次渲染本来就会启动 5–6 个 Chrome 工作进程，因此两次渲染可以很好地共享资源。

配方

templates/recipes.md 提供了 10 种可直接复制粘贴的模式。掌握基础知识后即可使用：

1. 液态玻璃卡片 — 具有光泽和折射效果的 iOS 风格磨砂背景模糊
2. 脉冲边框 — 卡片边缘的单色旋转渐变
3. 白色发光文字 — 多层 text-shadow，让文字在视频上更易读
4. 弧形下划线 — 在 em 强调文字下方绘制动画 SVG 曲线
5. 色度键 — 通过 SVG feColorMatrix 抠掉绿幕
6. 多片段剪辑 — 上文所示的 data-media-start 模式
7. 脉冲圆环 — 围绕标志向外扩散的同心脉冲
8. 角落注释 — 状态／计数／品牌胶囊装饰
9. D3 地球仪 — 带半色调圆点的线框地球，使用透明画布
10. 像素艺术图标行 — 一行小型角色图标示例（8×8 像素网格）

此工具包中的文件

hyperframes-helper/
├── SKILL.md                          ← this file
└── templates/
    ├── composition-template.html     ← scaffold: tokens, hex mesh, GSAP, watermark
    ├── storyboard-template.html      ← Level 2 storyboard, 5-scene starter
    ├── recipes.md                    ← copy-paste pattern library (10 recipes)
    ├── silence-cut.sh                ← Step 01 / Pass A: ffmpeg silence trim
    ├── transcribe-whisper.py         ← Step 01 / Pass B: faster-whisper transcript
    └── cut-retakes.py                ← Step 01 / Pass <your-project-path> last-take-rule retake removal

Level 3 的地球仪动态图形还需要 Natural Earth 陆地几何数据。下载后，将其封装为 .js 文件中的 window.NE_LAND = ...;，并放入合成项目的 assets/ 文件夹。

参考资料

• Hyperframes GitHub： https://github.com/heygen-com/hyperframes
• Hyperframes 文档： https://hyperframes.heygen.com
• Studio 编辑指南： https://hyperframes.heygen.com/guides/timeline-editing
• video-use（替代视频编辑器）： https://github.com/browser-use/video-use
• 21st.dev（HTML 组件参考）： https://21st.dev
• GSAP 文档： https://gsap.com/docs

---

由 Jay（RoboNuggets）创建。可依据 CC BY 4.0 免费使用，使用时请注明出处。