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 ~/.hermes/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 前进行规划
在编写代码之前,从高层次阐述:
- 什么 — 叙事弧、关键时刻、情感基调
- 结构 — 合成、轨道(视频/音频/覆盖层)、时长
- 视觉标识 — 颜色、字体、运动特征(爆炸性 / 电影感 / 流畅 / 技术风)
- 关键帧 — 对于每个场景,大多数元素同时可见的时刻。这是你将首先构建的静态布局。
视觉标识检查点 (HARD-GATE)。 在编写任何合成 HTML 之前,必须定义视觉标识。不要使用默认或通用颜色(#333、#3b82f6、Roboto 表明此步骤被跳过)编写合成。按顺序检查:
-
项目根目录有
DESIGN.md? → 使用其精确的颜色、字体、运动规则和“禁止事项”约束。 -
用户指定了风格(例如“Swiss Pulse”、“暗黑科技风”、“奢侈品牌”)? → 生成一个最小化的
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 <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. 场景间过渡
多场景合成需要过渡。规则:
- 始终在场景之间使用过渡 — 没有跳切。
- 始终在每个场景元素上使用入场动画 (
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. Lint、验证、检查、预览、渲染
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— 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>。
验证
在渲染之前和之后:
- Lint + validate + inspect 通过:
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 — 数据属性、时间线约定、不可协商规则、排版/资产规则
- 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 修复、环境变量、常见渲染错误