hyperframes

HyperFrames

HTML 是视频的事实来源。一个合成由 HTML 文件构成，其中使用 data-* 属性设置时间，使用 GSAP 时间轴控制动画，并使用 CSS 定义外观。HyperFrames 引擎逐帧捕获页面，并使用 FFmpeg 编码为 MP4/WebM。

与 manim-video 互为补充： 数学/几何讲解（公式、3B1B 风格）请使用 manim-video。动态图形、带字幕的真人出镜视频、产品导览、社交媒体叠加效果、着色器转场，以及任何由真实视频/音频媒体驱动的内容，请使用 hyperframes。

适用场景

• 用户要求根据文本、脚本或网站渲染视频
• 动态标题卡、字幕条或字体动画片头
• 带字幕的旁白视频（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 preview (long-lived server, port 3002)
npx hyperframes render --output final.mp4   # render to MP4
npx hyperframes doctor                      # diagnose environment issues

preview 是一个长期运行的 Next.js 服务，会让 Chrome 渲染工作进程保持开启。完成后务必停止它（参见清理）——忘记关闭的 preview 会使空闲的 chrome-headless-shell 工作进程持续运行；在没有 GPU 的主机（WSL、容器、CI）上，这些进程会通过软件 WebGL（swiftshader）无限期地各自占用一个 CPU 核心。

渲染标志：--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. 用户指定了风格（例如 “Swiss Pulse”、“暗色科技感”、“奢侈品牌”）？ → 生成一个精简的 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() 退场动画（从该位置开始动画）。

完整的数据属性架构和合成规则，请参阅 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 "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 → 生成逐词转录文本。根据转录文本的语气选择样式（热血／企业风／教程／叙事／社交媒体风——参见 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 滤镜。
• **场景转场：**所有多场景合成 MUST 使用转场（不得硬切）。可从 CSS 原语（推入滑动、模糊交叉淡化、缩放穿越、交错方块）或着色器转场（flash-through-white、liquid-wipe、cross-warp-morph、chromatic-split 等）中选择，通过 npx hyperframes add 添加。情绪和能量表位于 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.5s 时换行超出安全区域；卡片标题采用最长版本时发生溢出；元素最终位于转场着色器后方）。包含对话气泡、卡片、字幕或紧凑排版的合成，尤其要运行 inspect。

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

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

清理

render 是一次性运行的（完成后工作进程会退出）。preview 则不是——它会运行一个后台 Next.js 服务，在你停止之前一直让 Chrome 工作进程驻留。绝不要让它持续运行：在没有 GPU 的主机上，每个空闲工作进程的 swiftshader 进程都会占满一个 CPU 核心，而且让预览连续运行数天会累积多个进程。

用户完成检查后（或开始新的预览前），停止预览：

pkill -f "hyperframes.*preview"     # the Studio server (frees port 3002)
pkill -f chrome-headless-shell      # its render workers; only safe if nothing else uses them

如果不确定其他工具是否使用 chrome-headless-shell，请先检查：pgrep -af chrome-headless-shell。若主机卡住（许多空闲工作进程持续占用 CPU），也用同样的方法恢复——参见 references/troubleshooting.md。

常见陷阱

• 让 preview 持续运行——它是一个长期运行的服务，会占用 Chrome 工作进程；在 WSL、容器或 CI 中，这些空闲进程会各自占用一个 CPU 核心（软件 WebGL）。用完后请停止它——参见清理。

• 未找到 HeadlessExperimental.beginFrame'——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()——页面加载时该元素尚不存在。请改为在时间轴内、剪辑的 data-start 时刻或之后使用 tl.set(selector, vars, timePosition)。

• 在内容文本中使用 <br>——强制换行时无法得知渲染后的字体宽度，因此自然换行加上 <br> 会导致双重换行。请使用 max-width 让文本自动换行。例外：每个词都刻意单独成行的短展示标题。

• 对 visibility 或 display 设置动画——GSAP 无法对它们进行补间。请使用 autoAlpha（同时处理 visibility 和 opacity）。

• 调用 video.play() 或 audio.play()——播放由框架管理。请勿自行调用。

• 异步构建时间轴——页面加载后，捕获引擎会同步读取 window.__timelines。请勿将时间轴构建封装在 async、setTimeout 或 Promise 中。

• 用 <template> 包裹独立的 index.html——这会使浏览器无法显示所有内容。只有通过 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 修复、环境变量、常见渲染错误