HyperFrames
HTML 是视频的“单一事实来源”。合成是一个带有 data-* 属性用于时间控制、GSAP 时间线用于动画、CSS 用于外观的 HTML 文件。该框架处理剪辑可见性、媒体播放和时间线同步。
Open Design 集成(本技能的关键)
当此技能在 Open Design 内运行(即设置了 $OD_PROJECT_DIR)时,输出流程是固定的:只有渲染后的 .mp4 文件应放置在项目根目录中。合成源文件(hyperframes.json、meta.json、index.html、资产)应放在隐藏的缓存目录中,以免使用户的文件查看器或聊天的“生成的文件”标签混乱。
OD 内的渲染工作流——快速路径:
对于大多数 OD 请求(“测试视频”、“5 秒产品展示”、“演示片段”),不要从头编写合成 HTML。请使用 HyperFrames 的内置脚手架,仅编辑提示中实际更改的内容。从头编写路径会消耗数分钟的模型输出和静默聊天工具时间;脚手架路径只需几秒钟。
# 1. 选择一个隐藏的缓存槽。点前缀使 OD 的项目文件列表跳过它,因此源文件不会使聊天混乱。
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"
# 2. 获取一个立即可渲染的脚手架(hyperframes.json、meta.json、index.html 包含已注册的 GSAP CDN 和 window.__timelines.main)。此操作在你的 shell 中运行——纯文件复制,无需 Chrome,除了 npx 缓存外无需网络。
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive
# 3. 仅编辑 $COMP/index.html——如果需要非默认长度,请更改根元素的 `data-duration`;在 <style> 中替换占位调色板;添加 1-3 个用于文本/图像的剪辑 <div>;并在现有的 `window.__timelines["main"] = gsap.timeline({paused:true})` 块内添加匹配的 GSAP 补间动画。保持最小编辑;脚手架已经是有效的 HF。
# 4. 通过 OD 守护进程分派渲染。**不要**从此 shell 运行 `npx hyperframes render`——守护进程会在一个无沙箱的进程中为你运行它。(许多代理 CLI,特别是 Claude Code,将 Bash 包装在 macOS sandbox-exec 中,在该环境下,Puppeteer 的 Chrome 子进程在帧捕获过程中会挂起。守护进程是无沙箱的,因此渲染能够可靠完成。)
#
# 调度器在大约 1 秒内返回一个 {taskId};通过循环调用 `"$OD_NODE_BIN" "$OD_BIN" media wait <taskId>` 驱动渲染完成。
# 每次调用最长长轮询 25 秒(远低于你的 shell 工具的默认 30 秒上限),并以退出码 0/2/5 表示完成/运行中/失败。
out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
--project "$OD_PROJECT_ID" \
--surface video \
--model hyperframes-html \
--output "<描述性名称>.mp4" \
--composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
out=$("$OD_NODE_BIN" "$OD_BIN" media wait "$task_id" --since "$since")
ec=$?
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }
每次 generate 和每次 wait 调用最多持续约 25 秒,因此代理 shell 工具的默认约 30 秒上限永远不会触发。HF 的进度行(Capturing frame N/M)在整个循环过程中实时流式传输到 stderr。渲染完成时,最后一行 stdout 是 {"file": { "name": "<输出>", "size": …, "kind": "video", … }}——在你的回复中引用 file.name,以便用户知道生成了什么。
跳过 OD 内的视觉标识门控。 下面“方法”部分中的 HARD-GATE 部分告诉你在编写任何合成之前阅读 DESIGN.md / visual-style.md 或停下来询问 3 个情绪问题。该门控适用于独立的 HF 项目。OD 项目已经有了自己的设计系统层——用户在项目创建时选择了他们的视觉方向。对于 OD 测试渲染,默认为:深色画布 (#0b0b0f),一个暖色调强调色 (#ffb76b),一个冷色调强调色 (#7da4ff),克制运动。仅当用户的提示过于模糊以至于无法选择主题时(很少见),才需要询问风格输入。
何时跳过脚手架并从头编写:仅当用户明确要求一些空白模板显然无法承载的内容时(例如多合成时间线、音频反应式叠加层、与已生成的 TTS 轨道同步的字幕)。对于其他所有情况,init + 编辑是默认路径。
你仍然可以直接从自己的 shell 运行的较轻量级 HF 子命令(它们不需要启动 Chrome):
npx hyperframes lint "$COMP"— 在分派前验证合成npx hyperframes transcribe <audio>— 生成字幕npx hyperframes tts <text>— 生成旁白
将守护进程分派保留用于 render/inspect/preview(任何需要 Chrome 的操作)。
不要调用 "$OD_NODE_BIN" "$OD_BIN" media generate --model hyperframes-html——该调度器路径会故意返回 400 (AGENT_RENDERED)。HyperFrames 由你通过 npx 直接渲染。
不要将 hyperframes.json / meta.json / index.html 放到项目根目录中;OD 的文件列表会递归扫描,用户会在聊天中看到三个不相关的文件出现。
对于 render 以外的 CLI 选项(lint、preview、transcribe、tts、inspect、benchmark),当任务需要时,直接从你的 shell 工具调用它们(例如,在合成中引用之前,将 TTS 音频生成到缓存中)。
方法
在编写 HTML 之前,从高层次思考:
- 什么——观众应该体验到什么?确定叙述弧线、关键时刻和情感节拍。
- 结构——有多少个合成,哪些是子合成,哪些是内联的,哪些轨道承载什么内容(视频、音频、叠加层、字幕)。
- 时间——哪些剪辑驱动持续时间,过渡在哪里落地,节奏是怎样的。
- 布局——首先构建最终状态。请参阅下面的“布局优先于动画”。
- 动画——然后使用下面的规则添加运动。
对于小的编辑(修复颜色、调整时间、添加一个元素),直接跳到规则。
视觉标识门控
按此顺序检查:
- 项目目录中存在 DESIGN.md? → 读取它。使用其确切的颜色、字体、运动规则和“不做什么”约束。
- 存在 visual-style.md? → 读取它。应用其
style_prompt_full和结构化字段。(注意:visual-style.md是项目特定的文件。visual-styles.md是包含 8 个命名预设的样式库——不同的文件。) - 用户命名了一个样式(例如“Swiss Pulse”、“黑暗科技风”、“奢侈品牌”)? → 读取 visual-styles.md 以获取 8 个命名预设。生成一个最小的 DESIGN.md,包含:
## Style Prompt(一个段落)、## Colors(3-5 个带角色的十六进制值)、## Typography(1-2 个字体族)、## What NOT to Do(3-5 个反模式)。 - 以上都不是? → 在编写任何 HTML 之前,先问 3 个问题:
- 情绪是什么?(爆炸性 / 电影感 / 流畅 / 技术感 / 混乱 / 温暖)
- 浅色还是深色画布?
- 有任何特定的品牌颜色、字体或视觉参考吗? 然后根据答案生成一个最小的 DESIGN.md。
每个合成必须将其调色板和排版追溯到 DESIGN.md、visual-style.md 或用户明确指示。如果你正在使用 #333、#3b82f6 或 Roboto——那么你跳过了这一步。
对于运动默认值、大小、入场模式和缓动函数——请遵循 house-style.md。house style 处理事物如何移动。DESIGN.md 处理事物看起来像什么。
布局优先于动画
将每个元素放置在其最显眼时刻应处的位置——即它完全进入、正确放置且尚未退出的帧。首先将其编写为静态 HTML+CSS。暂不使用 GSAP。
为什么这很重要: 如果你将元素定位在动画起始状态(屏幕外、缩放为 0、透明度 0),然后通过补间动画将它们移动到你认为应该落地的位置,你实际上是在猜测最终布局。重叠在视频渲染之前是不可见的。通过首先构建最终状态,你可以在添加任何运动之前看到并修复布局问题。
流程
- 为每个场景确定英雄帧——即大多数元素同时可见的时刻。这是你要构建的布局。
- 为该帧编写静态 CSS。
.scene-content容器必须使用width: 100%; height: 100%; padding: Npx;配合display: flex; flex-direction: column; gap: Npx; box-sizing: border-box来填充整个场景。使用 padding 将内容向内推入——不要在内容容器上使用position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。保留position: absolute仅用于装饰性元素。 - 使用
gsap.from()添加入场动画——从屏幕外/不可见状态动画到 CSS 位置。CSS 位置是真实状态;补间动画描述了到达那里的过程。 - 使用
gsap.to()添加退场动画——从 CSS 位置动画到屏幕外/不可见状态。
示例
/* scene-content 填充场景,padding 定位内容 */
.scene-content {
display: flex;
flex-direction: column;
justify-content: center;
width: 100%;
height: 100%;
padding: 120px 160px;
gap: 24px;
box-sizing: border-box;
}
.title {
font-size: 120px;
}
.subtitle {
font-size: 42px;
}
/* 容器填充任何场景大小(1920x1080、1080x1920 等)。
padding 定位内容。Flex + gap 处理间距。 */
错误——硬编码尺寸和绝对定位:
.scene-content {
position: absolute;
top: 200px;
left: 160px;
width: 1920px;
height: 1080px;
display: flex; /* ... */
}
// 第 3 步:动画进入这些位置
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);
// 第 4 步:从这些位置动画退出
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);
当元素跨时间共享空间时
如果元素 A 在元素 B 进入同一区域之前退出,则两者都应具有其各自英雄帧的正确 CSS 位置。时间线排序保证它们永远不会在视觉上共存——但如果你跳过布局步骤,你将无法捕捉到它们由于时间错误而意外重叠的情况。
什么算是有意重叠
分层效果(文字后面的发光、阴影元素、背景图案)和 z 轴堆叠设计(卡片堆叠、深度层次)是有意的。布局步骤旨在捕捉无意重叠——两个标题相互重叠、一个统计数据覆盖标签、内容溢出画面。
数据属性
所有剪辑
| 属性 | 必需 | 值 |
|---|---|---|
id | 是 | 唯一标识符 |
data-start | 是 | 秒数或剪辑 ID 引用("el-1"、"intro + 2") |
data-duration | 对 img/div/compositions 为必需 | 秒数。视频/音频默认为媒体持续时间。 |
data-track-index | 是 | 整数。同一轨道的剪辑不能重叠。 |
data-media-start | 否 | 剪裁偏移量进入源文件(秒数) |
data-volume | 否 | 0-1(默认为 1) |
data-track-index 不影响视觉层次——请使用 CSS z-index。
合成剪辑
| 属性 | 必需 | 值 |
|---|---|---|
data-composition-id | 是 | 唯一的合成 ID |
data-start | 是 | 开始时间(根合成:使用 "0") |
data-duration | 是 | 优先于 GSAP 时间线持续时间 |
data-width / data-height | 是 | 像素尺寸(1920x1080 或 1080x1920) |
data-composition-src | 否 | 外部 HTML 文件的路径 |
合成结构
通过 data-composition-src 加载的子合成使用 <template> 包装器。独立合成(主要的 index.html)不使用 <template>——它们将 data-composition-id div 直接放在 <body> 中。在独立文件上使用 <template> 会向浏览器隐藏所有内容并破坏渲染。
子合成结构:
<template id="my-comp-template">
<div data-composition-id="my-comp" data-width="1920" data-height="1080">
<!-- 内容 -->
<style>
[data-composition-id="my-comp"] {
/* 作用域样式 */
}
</style>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
// 补间动画...
window.__timelines["my-comp"] = tl;
</script>
</div>
</template>
在根元素中加载:<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="5"></div>