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 # 创建项目脚手架
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 ~/.zedclaw/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
该脚本：
- 检查是否已安装 Node.js >= 22 和 FFmpeg（如果未安装，则打印修复说明）。
- 全局安装
hyperframesCLI（npm install -g hyperframes@>=0.4.2）。 - 通过 Puppeteer 预缓存
chrome-headless-shell——通过 Chrome 的HeadlessExperimental.beginFrame捕获路径获得最佳渲染质量所必需。 - 运行
npx hyperframes doctor并报告结果。
如果设置失败，请参阅 references/troubleshooting.md。
程序
1. 在编写 HTML 之前进行规划
在接触代码之前，请在高级别上阐明：
- 是什么 —— 叙事弧、关键时刻、情感节拍
- 结构 —— 合成、轨道（视频/音频/叠加层）、持续时间
- 视觉身份 —— 颜色、字体、运动特征（爆炸性/电影感/流畅/技术感）
- 英雄帧 —— 对于每个场景，同时可见元素最多的时刻。这将是您首先构建的静态布局。
**视觉身份门禁（硬性门禁）。**在编写任何合成 HTML 之前，必须定义视觉身份。不要使用默认或通用颜色（#333、#3b82f6、Roboto 表示跳过此步骤）编写合成。按顺序检查：
-
项目根目录下有
DESIGN.md？ → 使用其精确的颜色、字体、运动规则和“不要做什么”约束。 -
用户指定了样式（例如“瑞士脉动”、“黑暗科技感”、“奢侈品牌”）？ → 生成一个最小的
DESIGN.md，包含## Style Prompt、## Colors（3-5 个十六进制代码及其角色）、## Typography（1-2 个字体族）、## What NOT to Do（3-5 个反模式）。 -
以上都不是？ → 在编写任何 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 <名称> 选择一个，传递 --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. 场景间的转场
多场景合成需要转场。规则：
- 始终在场景之间使用转场 —— 不能有跳切。
- 始终在每个场景元素上使用入场动画（
gsap.from(...)）。 - 永远不要使用出场动画，除了最后一个场景 —— 转场本身就是出场。
- 最后一个场景可以淡出。
使用 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中的表格）。语言规则： 除非音频确认为英语，否则永远不要使用.enwhisper 模型 ——.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()—— 元素在页面加载时不存在。而是在时间线内部，在剪辑的data-start处或之后，使用tl.set(selector, vars, timePosition)。 - 内容文本中的
<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>。
验证
在渲染之前和之后：
- 检查 + 验证 + 审查通过：
npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect（lint 捕获结构问题，validate 捕获对比度问题，inspect 捕获视觉布局/溢出问题 —— 如果出现警告，请参阅 troubleshooting.md）。 - 动画编排 —— 对于新的合成或重要的动画更改，运行动画映射。
npx hyperframes init会将技能脚本复制到项目中，因此路径是项目本地的：
输出一个node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \ --out <composition-dir>/.hyperframes/anim-mapanimation-map.json，其中包含每个补间的摘要、ASCII 甘特时间线、交错检测、死区（>1 秒无动画）、元素生命周期和标志（offscreen、collision、invisible、paced-fast<0.2 秒、paced-slow>2 秒）。扫描摘要和标志 —— 修复或验证每个。对小型编辑可跳过。 - 文件存在且非零：
ls -lh final.mp4。 - 持续时间匹配
data-duration：ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4。 - 视觉检查： 提取合成中间帧：
ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png。 - 如果预期有音频：
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 —— data 属性、时间线契约、不可协商规则、排版/资产规则
- 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 修复、环境变量、常见渲染错误