跳到主要内容

Hyperframes

使用 HyperFrames 创建基于 HTML 的视频合成、动画标题卡、社交叠加层、带字幕的真人出镜视频、音频反应视觉效果以及着色器过渡效果。HTML 是视频的真实来源（source of truth）。当用户希望从 HTML 合成中渲染出 MP4/WebM 视频、希望在媒体上动画化文本/Logo/图表、需要同步音频的字幕、需要 TTS 旁白，或希望将网站转换为视频时，请使用此技能。

技能元数据​

来源可选 — 使用 hermes skills install official/creative/hyperframes 安装
路径optional-skills/creative/hyperframes
版本1.0.0
作者heygen-com
许可证Apache-2.0
平台linux, macos, windows
标签creative, video, animation, html, gsap, motion-graphics
相关技能manim-video, meme-generation

参考：完整 SKILL.md​

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理所看到的指令。

HyperFrames

HTML 是视频的真实来源。合成是一个 HTML 文件，其中包含用于定时的 data-* 属性、用于动画的 GSAP 时间轴以及用于外观的 CSS。HyperFrames 引擎逐帧捕获页面，并使用 FFmpeg 编码为 MP4/WebM。

作为 manim-video 的补充： 对于数学/几何解释器（方程、3B1B 风格），请使用 manim-video。对于动态图形、带字幕的真人出镜、产品导览、社交叠加层、着色器过渡以及任何由真实视频/音频媒体驱动的内容，请使用 hyperframes。

何时使用​

  • 用户要求从文本、脚本或网站渲染视频
  • 动画标题卡、下三分之一字幕条（lower thirds）或排版介绍
  • 带字幕的旁白视频（TTS + 与波形同步的字幕）
  • 音频反应视觉效果（节拍同步、频谱条、脉冲发光）
  • 场景间过渡（交叉淡入淡出、擦除、着色器扭曲、闪白）
  • 社交叠加层（Instagram/TikTok/YouTube 风格）
  • 网站到视频的流程（捕获 URL，制作宣传片）
  • 任何必须确定性渲染为视频文件的 HTML/CSS/JS 动画

不要将此技能用于：

  • 纯数学/方程动画（→ manim-video）
  • 图像生成或模因（→ meme-generation，图像模型）
  • 实时视频会议或流媒体

快速参考​

npx hyperframes init my-video               # scaffold a project
cd my-video
npx hyperframes lint                        # validate before preview/render
npx hyperframes preview                     # live-reload browser preview (port 3002)
npx hyperframes render --output final.mp4   # render to MP4
npx hyperframes doctor                      # diagnose environment issues

渲染标志：--quality draft|standard|high · --fps 24|30|60 · --format mp4|webm · --docker（可复现） · --strict。

完整 CLI 参考：references/cli.md。

设置（一次性）​

bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"

该脚本：

  1. 验证是否安装了 Node.js >= 22 和 FFmpeg（如果未安装，则打印修复说明）。
  2. 全局安装 hyperframes CLI（npm install -g hyperframes@>=0.4.2）。
  3. 通过 Puppeteer 预缓存 chrome-headless-shell — 这对于通过 Chrome 的 HeadlessExperimental.beginFrame 捕获路径进行高质量渲染是必需的。
  4. 运行 npx hyperframes doctor 并报告结果。

如果设置失败，请参阅 references/troubleshooting.md。

流程​

1. 编写 HTML 前的规划​

在接触代码之前，从高层面阐述：

  • 内容 — 叙事弧线、关键时刻、情感节奏
  • 结构 — 合成、轨道（视频/音频/叠加层）、持续时间
  • 视觉标识 — 颜色、字体、运动特征（爆发式 / 电影感 / 流畅 / 技术感）
  • 主帧（Hero frame） — 对于每个场景，最多元素同时可见的时刻。这是你首先构建的静态布局。

视觉标识门禁（硬门禁）。 在编写任何合成 HTML 之前，必须定义视觉标识。切勿使用默认或通用颜色编写合成（#333、#3b82f6、Roboto 表明跳过了此步骤）。按顺序检查：

  1. 项目根目录下有 DESIGN.md 吗？ → 使用其确切的颜色、字体、运动规则和“禁止事项”约束。

  2. 用户指定了风格吗（例如“瑞士脉冲”、“黑暗科技感”、“奢侈品牌”）？ → 生成一个最小的 DESIGN.md，包含 ## Style Prompt、## Colors（3-5 个带有角色的十六进制颜色）、## Typography（1-2 个字体系列）、## What NOT to Do（3-5 个反模式）。

  3. 以上皆无？ → 在编写任何 HTML 之前询问 3 个问题：

    • 情绪？（爆发式 / 电影感 / 流畅 / 技术感 / 混乱 / 温暖）
    • 浅色还是深色画布？
    • 有任何品牌颜色、字体或视觉参考吗？

    然后根据答案生成 DESIGN.md。每个合成的调色板和排版都必须追溯回 DESIGN.md 或明确的用户指示。

2. 搭建骨架​

npx hyperframes init my-video --non-interactive

模板：blank、warm-grain、play-mode、swiss-grid、vignelli、decision-tree、kinetic-type、product-promo、nyt-graph。传递 --example <name> 以选择一个模板，传递 --video clip.mp4 或 --audio track.mp3 以使用媒体素材进行初始化。

3. 先布局，后动画​

首先编写**主视觉帧（hero frame）**的静态 HTML+CSS——此时不要使用 GSAP。.scene-content 容器必须填满场景（width:100%; height:100%; padding:Npx），并使用 display:flex + gap。使用内边距将内容向内推挤——切勿在内容容器上使用 position: absolute; top: Npx（当内容高度超过剩余空间时会导致溢出）。

只有在主视觉帧看起来正确之后，再添加 gsap.from() 入场动画（动画至 CSS 定义的位置）和 gsap.to() 退场动画（从该位置动画离开）。

请参阅 references/composition.md 以获取完整的数据属性架构和构图规则。

4. 使用 GSAP 制作动画​

每个构图必须：

  • 注册其时间轴：window.__timelines["<composition-id>"] = tl
  • 初始暂停：gsap.timeline({ paused: true })——由播放器控制播放
  • 使用有限的 repeat 值（禁止 repeat: -1——这会破坏捕获引擎）。计算方式：repeat: Math.ceil(duration / cycleDuration) - 1。
  • 具有确定性——禁止使用 Math.random()、Date.now() 或基于墙钟时间的逻辑。如果需要伪随机性，请使用 seeded PRNG（种子伪随机数生成器）。
  • 同步构建——在时间轴构建周围禁止使用 async/await、setTimeout 或 Promise。

请参阅 references/gsap.md 以获取核心 GSAP API（tweens、eases、stagger、timelines）。

5. 场景之间的过渡​

多场景构图需要过渡。规则如下：

  1. 场景之间始终使用过渡——禁止硬切（jump cuts）。
  2. 每个场景的元素始终使用入场动画（gsap.from(...)）。
  3. 除最后一个场景外，切勿使用退场动画——过渡本身就是退场。
  4. 最后一个场景可以淡出。

使用 npx hyperframes add <transition-name> 安装着色器过渡效果（flash-through-white、liquid-wipe 等）。完整列表：npx hyperframes add --list。

6. 音频、字幕、TTS、音频反应式视觉效果、高亮​

  • 音频： 始终使用独立的 <audio> 元素（视频需设置为 muted playsinline）。
  • TTS（文本转语音）： npx hyperframes tts "Script text" --voice af_nova --output narration.wav。使用 --list 列出可用声音。声音 ID 的首字母编码语言（a/b=英语，e=西班牙语，f=法语，j=日语，z=普通话等）——CLI 会自动推断音素化区域设置；仅在需要覆盖时传递 --lang。非英语音素化需要在系统中全局安装 espeak-ng。
  • 字幕： npx hyperframes transcribe narration.wav → 生成单词级转录文本。根据转录文本的语气选择样式（hype / corporate / tutorial / storytelling / social ——参见 references/features.md 中的表格）。语言规则： 除非确认音频为英语，否则切勿使用 .en Whisper 模型——.en 会将非英语音频翻译而非转录。每个字幕组在其退场动画后必须有一个强制的 tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) 清除操作——否则字幕组会泄漏并显示在后续组中。
  • 音频反应式视觉效果： 预提取音频频段（低音/中音/高音），并在时间轴内通过 for 循环 tl.call(draw, [], f / fps) 每帧采样——单个长 tween 不会对音频产生反应。映射关系：低音 → scale（脉冲），高音 → textShadow/boxShadow（发光），整体振幅 → opacity/y/backgroundColor。避免均衡器条形图的陈词滥调——让内容引导视觉，音频驱动其行为。
  • 标记式高亮： 用于强调文本的高亮、圆圈、爆发、涂鸦、素描效果是确定性的 CSS+GSAP 实现——参见 references/features.md#marker-highlighting。完全可.seekable（可跳转），无动画 SVG 滤镜。
  • 场景过渡： 每个多场景构图必须使用过渡（禁止硬切）。从 CSS 原语（推滑、模糊交叉淡入淡出、缩放穿过、交错块）或通过 npx hyperframes add 使用的着色器过渡（flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split 等）中选择。情绪和能量表位于 references/features.md#transitions。不要在同一个构图中混合使用 CSS 和着色器过渡。

7. Lint、验证、检查、预览、渲染​

npx hyperframes lint              # catches missing data-composition-id, overlapping tracks, unregistered timelines
npx hyperframes validate          # WCAG contrast audit at 5 timestamps
npx hyperframes inspect           # visual layout audit — overflow, off-frame elements, occluded text
npx hyperframes preview           # live browser preview
npx hyperframes render --quality draft --output draft.mp4    # fast iteration
npx hyperframes render --quality high --output final.mp4     # final delivery

hyperframes validate 会对每个文本元素背后的背景像素进行采样，并对对比度低于 4.5:1（大文本为 3:1）的情况发出警告。hyperframes inspect 是布局方面的辅助工具——它在多个时间戳运行页面，并标记静态 lint 无法发现的问题（例如仅在 4.5 秒时超出安全区域的字幕、标题为最长变体时溢出的卡片、最终位于过渡着色器后面的元素）。特别是在包含对话气泡、卡片、字幕或紧凑排版的构图上运行 inspect。

8. 网站转视频（如果用户提供 URL）​

使用 references/website-to-video.md 中的 7 步捕获到视频工作流：capture → DESIGN.md → SCRIPT.md → storyboard → composition → render → deliver。

常见陷阱​

  • HeadlessExperimental.beginFrame' wasn't found — Chromium 147+ 已移除此协议。确保你使用的是 hyperframes@>=0.4.2（自动检测并回退到截图模式）。应急方案：export PRODUCER_FORCE_SCREENSHOT=true。参见 hyperframes#294 和 references/troubleshooting.md。
  • 系统 Chrome（而非 chrome-headless-shell） — 渲染会挂起 120 秒然后超时。运行 npx puppeteer browsers install chrome-headless-shell（setup.sh 会执行此操作）。hyperframes doctor 会报告将使用哪个二进制文件。
  • 任何地方的 repeat: -1 — 会破坏捕获引擎。始终计算有限的重复次数。
  • 对稍后进入的剪辑元素使用 gsap.set() — 页面加载时该元素尚不存在。请在时间轴内使用 tl.set(selector, vars, timePosition)，位置在剪辑的 data-start 处或之后。
  • 内容文本中的 <br> — 强制换行不知道渲染字体的宽度，因此自然换行 + <br> 会导致双重换行。使用 max-width 让文本自然换行。例外情况：简短的显示标题，其中每个单词故意独占一行。
  • 动画化 visibility 或 display — GSAP 无法对这些属性进行补间动画。使用 autoAlpha（同时处理可见性和不透明度）。
  • 调用 video.play() 或 audio.play() — 框架拥有播放控制权。切勿自行调用这些方法。
  • 异步构建时间轴 — 捕获引擎在页面加载后同步读取 window.__timelines。切勿将时间轴构建包裹在 async、setTimeout 或 Promise 中。
  • ** standalone index.html 被 <template> 包裹** — 这会向浏览器隐藏所有内容。只有通过 data-composition-src 加载的子组合才使用 <template>。
  • 使用视频承载音频 — 始终使用静音的 <video> + 单独的 <audio>。

验证​

在渲染前后执行以下操作：

  1. Lint + 验证 + 检查通过： npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect（lint 捕获结构问题，validate 捕获对比度问题，inspect 捕获视觉布局/溢出问题 — 如果出现警告，请参阅 troubleshooting.md）。
  2. 动画编排 — 对于新组合或重大动画更改，运行动画映射。npx hyperframes init 将技能脚本复制到项目中，因此路径是项目本地的： 
    node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
      --out <composition-dir>/.hyperframes/anim-map
    输出单个 animation-map.json，包含每个补间的摘要、ASCII 甘特图时间轴、交错检测、死区（>1 秒无动画）、元素生命周期以及标志（offscreen、collision、invisible、paced-fast <0.2s、paced-slow >2s）。扫描摘要和标志 — 修复或证明每个问题的合理性。小幅编辑可跳过此步骤。
  3. 文件存在且非零大小： ls -lh final.mp4。
  4. 持续时间匹配 data-duration： ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。
  5. 视觉检查： 提取组合中间的一帧：ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。
  6. 如果预期有音频，则检查音频是否存在： ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1。

如果 hyperframes render 失败，请运行 npx hyperframes doctor 并在报告时附上其输出。

参考资料​

  • composition.md — 数据属性、时间轴契约、不可协商的规则、排版/资源规则
  • cli.md — 每个 CLI 命令（init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark）
  • gsap.md — HyperFrames 的 GSAP 核心 API（补间、缓动、交错、时间轴、matchMedia）
  • features.md — 字幕、TTS、音频反应、标记高亮、过渡（按需加载）
  • website-to-video.md — 7 步捕获到视频工作流
  • troubleshooting.md — OpenClaw 修复、环境变量、常见渲染错误