好奇心花园🪴

搜索

SearchSearch

最近的笔记

Hyperframes

2026年5月24日15分钟阅读

{/* This page is auto-generated from the skill’s SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Hyperframes

使用 HyperFrames 创建基于 HTML 的视频合成、动画标题卡片、社交媒体叠加层、带字幕的访谈视频、音频响应式视觉效果和着色器过渡。HTML 是视频的真相来源。当用户想要从 HTML 合成获得渲染的 MP4/WebM、想要在媒体上动画化文字/标志/图表、需要与音频同步的字幕、想要 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

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

HyperFrames

HTML 是视频的真相来源。合成是一个 HTML 文件，带有用于定时的 data-* 属性、用于动画的 GSAP 时间线和用于外观的 CSS。HyperFrames 引擎逐帧捕获页面并使用 FFmpeg 编码为 MP4/WebM。

作为 manim-video 的补充： 使用 manim-video 处理数学/几何解说（方程、3B1B 风格）。使用 hyperframes 处理运动图形、带字幕的访谈、产品导览、社交媒体叠加、着色器过渡以及任何由真实视频/音频媒体驱动的内容。

何时使用

  • 用户要求从文本、剧本或网站渲染视频
  • 动画标题卡片、下三分之一或排印开场
  • 带字幕的旁白视频（TTS + 与波形同步的字幕）
  • 音频响应式视觉效果（节拍同步、频谱条、脉冲发光）
  • 场景到场景的过渡（交叉淡入淡出、擦拭、着色器扭曲、闪白过渡）
  • 社交媒体叠加层（Instagram/TikTok/YouTube 风格）
  • 网站到视频流水线（捕获 URL，生成宣传片）
  • 任何必须确定性地渲染到视频文件的 HTML/CSS/JS 动画

不要将此技能用于：

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

快速参考

npx hyperframes init my-video               # 搭建项目
cd my-video
npx hyperframes lint                        # 在预览/渲染前验证
npx hyperframes preview                     # 实时重载浏览器预览（端口 3002）
npx hyperframes render --output final.mp4   # 渲染为 MP4
npx hyperframes doctor                      # 诊断环境问题

渲染标志：--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 之前做好规划

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

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

视觉身份关卡（硬关卡）。 在编写任何合成 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. 先布局再动画

先编写关键帧的静态 HTML+CSS —— 不要 GSAP。.scene-content 容器必须填充场景（width:100%; height:100%; padding:Npx），使用 display:flex + gap。使用内边距将内容向内推 —— 永远不要在内容容器上使用 position: absolute; top: Npx（当内容高于剩余空间时会溢出）。

只有在关键帧看起来正确后，才添加 gsap.from() 入场（动画到CSS 位置）和 gsap.to() 出场（从 CSS 位置动画出去）。

完整的 data-attribute 模式和合成规则请参阅 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() 或时钟逻辑。如果需要伪随机性，使用种子 PRNG。
  • 同步构建 —— 不要在时间线构建中使用 async/await、setTimeout 或 Promise。

核心 GSAP API（补间、缓动、交错、时间线）请参阅 references/gsap.md。

5. 场景间的过渡

多场景合成需要过渡。规则：

  1. 始终在场景之间使用过渡 —— 不要跳切。
  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 "脚本文本" --voice af_nova --output narration.wav。使用 --list 列出声音。声音 ID 的第一个字母编码语言（a/b=英语、e=西班牙语、f=法语、j=日语、z=普通话等）—— CLI 自动推断音素化器区域设置；仅传递 --lang 以覆盖。非英语音素化需要在系统范围内安装 espeak-ng。
  • 字幕： npx hyperframes transcribe narration.wav → 单词级转录。根据转录基调选择风格（炒作/企业/教程/讲故事/社交——请参阅 references/features.md 中的表格）。语言规则： 除非音频确认是英语，否则永远不要使用 .en whisper 模型 —— .en 翻译非英语音频而不是转录。每个字幕组必须在其退场补间后有一个硬性的 tl.set(el, { opacity: 0, visibility: "hidden" }, group.end) 终止 —— 否则字幕组会泄露到后续字幕中。
  • 音频响应式视觉效果： 预提取音频频段（低音/中音/高音）并在时间线内使用 for 循环的 tl.call(draw, [], f / fps) 逐帧采样 —— 单个长时间补间不会对音频做出反应。映射低音 → scale（脉冲）、高音 → textShadow/boxShadow（发光）、整体振幅 → opacity/y/backgroundColor。避免均衡器条形图的陈词滥调 —— 让内容引导视觉，音频驱动其行为。
  • 标记式高亮： 高亮、圆圈、爆发、涂鸦、草图效果用于文字强调，是确定性的 CSS+GSAP —— 请参阅 references/features.md#marker-highlighting。完全可搜索，无需动画 SVG 滤镜。
  • 场景过渡： 每个多场景合成必须使用过渡（无跳切）。从 CSS 原语（推送滑动、模糊交叉淡入、缩放穿越、交错块）或着色器过渡（flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split 等）中通过 npx hyperframes add 选择。情绪和能量表位于 references/features.md#transitions。不要在同一个合成中混合 CSS 和着色器过渡。

7. 检查、验证、审查、预览、渲染

npx hyperframes lint              # 捕获缺少 data-composition-id、重叠轨道、未注册的时间线
npx hyperframes validate          # 在 5 个时间点进行 WCAG 对比度审计
npx hyperframes inspect           # 视觉布局审计 —— 溢出、帧外元素、被遮挡的文字
npx hyperframes preview           # 实时浏览器预览
npx hyperframes render --quality draft --output draft.mp4    # 快速迭代
npx hyperframes render --quality high --output final.mp4     # 最终交付

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

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

使用 references/website-to-video.md 中的 7 步捕获到视频工作流：捕获 → DESIGN.md → SCRIPT.md → 故事板 → 合成 → 渲染 → 交付。

陷阱

  • 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。
  • 独立的 index.html 包裹在 <template> 中 —— 对浏览器隐藏所有内容。只有通过 data-composition-src 加载的子合成使用 <template>。
  • 使用视频播放音频 —— 始终使用静音 <video> + 单独的 <audio>。

验证

渲染前后：

  1. Lint + validate + inspect 通过： 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.2 秒、paced-slow >2 秒）。扫描摘要和标志 —— 修复或证明每个。小编辑时跳过。
  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 修复、环境变量、常见渲染错误

关系图谱

反向链接