hyperframes

HyperFrames

视频以 HTML 为准。一个合成是一个 HTML 文件，其中包含用于设置时间的 data-* 属性、用于动画的 GSAP 时间线，以及用于外观的 CSS。框架会处理片段可见性、媒体播放和时间线同步。

Open Design 集成（此界面的关键要求）

当此技能在 Open Design 中运行时（即设置了 $OD_PROJECT_DIR），输出流程是固定的：项目根目录中只能放置渲染后的 .mp4。合成源文件（hyperframes.json、meta.json、index.html、资源）应放在隐藏的缓存目录中，以免它们出现在用户的文件查看器或聊天的“已生成文件”标签中。

在 OD 中的渲染工作流 — 快速路径：

对于大多数 OD 请求（“测试视频”、“5s 产品亮相”、“演示片段”），不要从头编写合成 HTML。使用 HyperFrames 内置的脚手架，只修改提示词实际要求更改的内容。“从头创作”路径需要数分钟的模型输出和静默的聊天工具调用时间；脚手架路径只需数秒。

# 1. Pick a hidden cache slot. Dotfile prefix → OD's project file
#    listing skips it, so the source files never clutter the chat.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"

# 2. Get an immediately-renderable scaffold (hyperframes.json,
#    meta.json, index.html with GSAP CDN + window.__timelines.main
#    already registered). This runs in your shell — pure file copy,
#    no Chrome, no network beyond the npx cache.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive

# 3. Edit ONLY $COMP/index.html — change `data-duration` on the root
#    if you need a non-default length, swap the placeholder palette
#    in <style>, add 1–3 clip <div>s for text/imagery, and append the
#    matching GSAP tweens inside the existing
#    `window.__timelines["main"] = gsap.timeline({paused:true})` block.
#    Keep edits minimal; the scaffold is already valid HF.

# 4. Dispatch render through the OD daemon. Do NOT run `npx hyperframes
#    render` from this shell — the daemon runs it for you in an
#    unsandboxed process. (Many agent CLIs, Claude Code in particular,
#    wrap Bash in macOS sandbox-exec under which puppeteer's Chrome
#    subprocess hangs partway through frame capture. The daemon process
#    is unsandboxed, so renders complete reliably.)
#
#    The dispatcher returns within ~1s with a {taskId}; drive the
#    render to completion by looping `od media wait <taskId>` calls.
#    Each call long-polls up to 25s (well under your shell tool's
#    default 30s cap) and exits 0/2/5 to signal done/running/failed.
out=$(node "$OD_BIN" media generate \
  --project "$OD_PROJECT_ID" \
  --surface video \
  --model hyperframes-html \
  --output "<descriptive-name>.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=$(node "$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 调用最长约为 25s，因此 Agent shell 工具默认的约 30s 时限永远不会触发。HF 的进度行（Capturing frame N/M）会在整个循环过程中实时输出到 stderr。渲染完成后，stdout 的最后一行是 {"file": { "name": "<output>", "size": …, "kind": "video", … }}——在回复中引用 file.name，让用户知道生成了什么。

在 OD 中跳过视觉风格门槛。 下文“处理方法”中的“硬性门槛”部分要求你在编写任何合成之前阅读 DESIGN.md / visual-style.md，或者停下来询问 3 个关于氛围的问题。该门槛适用于独立的 HF 项目。OD 项目已有自己的设计系统层——用户在创建项目时已经选择了视觉方向。对于 OD 测试渲染，默认使用：深色画布（#0b0b0f）、一种暖色强调色（#ffb76b）、一种冷色强调色（#7da4ff）、克制的动效。只有当用户的提示词过于模糊，甚至无法确定主题时，才询问风格方面的意见（这种情况极少）。

仅在用户明确要求的内容显然无法用空白模板承载时，才跳过脚手架并从头编写（例如，多合成时间线、音频响应式叠加效果、与用户已生成的 TTS 音轨同步的字幕）。其他情况下，默认采用初始化后编辑的路径。

以下较轻量的 HF 子命令仍可在你自己的 shell 中运行（无需启动 Chrome）：

• npx hyperframes lint "$COMP" — 在调度前验证合成
• npx hyperframes transcribe <audio> — 生成字幕
• npx hyperframes tts <text> — 生成旁白

仅将守护进程调度用于 render/inspect/preview（任何需要 Chrome 的操作）。

不要调用 od 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 之前，先从整体上思考：

1. 内容 — 观众应该体验到什么？确定叙事弧线、关键时刻和情绪起伏。
2. 结构 — 需要多少个合成，哪些是子合成、哪些是内联内容，各轨道承载什么内容（视频、音频、叠加效果、字幕）。
3. 时间 — 哪些片段决定时长，转场发生在何处，节奏如何安排。
4. 布局 — 先构建最终状态。参见下文“先布局，再动画”。
5. 动画 — 然后使用下方规则添加动效。

对于小幅修改（修复颜色、调整时间、添加一个元素），直接跳到规则部分。

视觉识别规范门槛

在编写任何构图 HTML 之前，必须先定义视觉识别规范。切勿使用默认或通用配色编写构图。

按以下顺序检查：

1. 项目中是否存在 DESIGN.md？ → 阅读该文件。使用其中指定的颜色、字体、动态效果规则和“不要做什么”约束。
2. 是否存在 visual-style.md？ → 阅读该文件。应用其中的 style_prompt_full 和结构化字段。（注意：visual-style.md 是项目专属文件。visual-styles.md 是包含 8 种命名预设的样式库——两者是不同的文件。）
3. 用户是否指定了样式（例如，“Swiss Pulse”、“暗色科技风”、“奢华品牌”）？→ 阅读 visual-styles.md，了解其中的 8 种命名预设。生成一个精简的 DESIGN.md，其中包含：## Style Prompt（一段文字）、## Colors（3-5 个带用途说明的十六进制颜色值）、## Typography（1-2 种字体系列）、## What NOT to Do（3-5 条反模式）。
4. 以上都没有？ → 在编写任何 HTML 之前，先提出 3 个问题：
   • 想要什么氛围？（奔放 / 电影感 / 流畅 / 技术感 / 混乱 / 温暖）
   • 使用浅色还是深色画布？
   • 是否有特定的品牌颜色、字体或视觉参考？ 然后根据答案生成一个精简的 DESIGN.md。

每个构图所用的配色和字体都必须能追溯到 DESIGN.md、visual-style.md 或用户明确指定的要求。如果你打算使用 #333、#3b82f6 或 Roboto，说明你跳过了这一步。

对于动态效果默认设置、尺寸、入场模式和缓动，请遵循 house-style.md。house style 负责规定元素如何运动。DESIGN.md 负责规定元素的外观。

动画前先完成布局

先将每个元素放在其最清晰可见时刻应处的位置——也就是元素已完全入场、位置正确且尚未退场的画面。先将其编写为静态 HTML+CSS，暂不使用 GSAP。

为什么这很重要： 如果你将元素放在动画开始状态（画面外、缩放为 0、不透明度为 0），再通过补间动画将它们移动到你认为合适的位置，那你其实是在猜测最终布局。视频渲染前，重叠问题是看不见的。先构建最终状态，就能在添加动态效果之前发现并修复布局问题。

流程

1. 为每个场景确定主画面——也就是最多元素同时可见的时刻。你要构建的就是这个布局。
2. 为该画面编写静态 CSS。 .scene-content 容器必须使用 width: 100%; height: 100%; padding: Npx;、display: flex; flex-direction: column; gap: Npx; box-sizing: border-box 填满整个场景。使用内边距将内容向内推——内容容器上绝不能使用 position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。position: absolute 仅用于装饰元素。
3. 使用 gsap.from() 添加入场动画——从画面外 / 不可见状态动画至 CSS 定义的位置。CSS 位置是最终依据；补间动画描述的是元素到达该位置的过程。
4. 使用 gsap.to() 添加退场动画——从 CSS 定义的位置动画至画面外 / 不可见状态。

示例

/* scene-content fills the scene, padding positions content */
.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;
}
/* Container fills any scene size (1920x1080, 1080x1920, etc).
   Padding positions content. Flex + gap handles spacing. */

错误——硬编码尺寸并使用绝对定位：

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// Step 3: Animate INTO those positions
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);

// Step 4: Animate OUT from those positions
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/合成必填	秒数。视频/音频默认使用媒体时长。
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"] {
        /* scoped styles */
      }
    </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 });
      // tweens...
      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="10" data-track-index="1"></div>

视频和音频

视频必须设置为 muted playsinline。音频始终使用单独的 <audio> 元素：

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

时间线约定

• 所有时间线都以 { paused: true } 启动——播放由播放器控制
• 注册每条时间线：window.__timelines["<composition-id>"] = tl
• 框架会自动嵌套子时间线——请勿手动添加
• 时长取自 data-duration，而非 GSAP 时间线长度
• 切勿创建空补间来设置时长

规则（不可妥协）

确定性： 不要使用 Math.random()、Date.now() 或基于时间的逻辑。如果需要伪随机值，请使用带种子的 PRNG（例如 mulberry32）。

GSAP： 只动画视觉属性（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、transforms）。不要动画 visibility、display，也不要调用 video.play()/audio.play()。

动画冲突： 绝不要在多个时间轴上同时动画同一元素的同一属性。

不要使用 repeat: -1： 无限重复的时间轴会破坏捕获引擎。根据合成时长计算准确的重复次数：repeat: Math.ceil(duration / cycleDuration) - 1。

同步构建时间轴： 绝不要在 async/await、setTimeout 或 Promise 中构建时间轴。页面加载后，捕获引擎会同步读取 window.__timelines。编译器会嵌入字体，因此字体可立即使用，无需等待字体加载。

绝不要：

1. 忘记注册 window.__timelines
2. 用视频承载音频——始终使用静音视频 + 独立的 <audio>
3. 将视频嵌套在定时 div 中——使用非定时包装元素
4. 使用 data-layer（应使用 data-track-index）或 data-end（应使用 data-duration）
5. 动画视频元素的尺寸——改为动画包装 div
6. 对媒体调用 play/pause/seek——播放由框架控制
7. 创建没有 data-composition-id 的顶层容器
8. 在任何时间轴或补间中使用 repeat: -1——始终使用有限次数的重复
9. 异步构建时间轴（在 async、setTimeout、Promise 中）
10. 在后续场景的片段元素上使用 gsap.set()——页面加载时这些元素尚不存在于 DOM 中。应在时间轴内、片段的 data-start 时间点或之后使用 tl.set(selector, vars, timePosition)。
11. 在内容文本中使用 <br>——强制换行不会考虑实际渲染的字体宽度。自然换行的文本再加上 <br> 会导致多出不必要的换行，从而造成重叠。应使用 max-width 让文本自然换行。例外：每个词都刻意单独占一行的短展示标题（例如 130px 字号的 “THE\nIMMORTAL\nGAME”）。

场景转场（不可妥协）

每个多场景合成都必须遵循以下所有规则。违反任何一条都会导致合成损坏。

1. 始终在场景之间使用转场。 不要使用跳切。没有例外。
2. 始终为每个场景使用入场动画。 每个元素都必须通过 gsap.from() 动画进入。不得让元素以完整形态直接出现。如果场景有 5 个元素，就需要 5 个入场补间。
3. 绝不要使用退场动画，最终场景除外。这意味着：在转场开始前，禁止使用 gsap.to() 将 opacity 动画至 0、将 y 移出屏幕、将 scale 动画至 0，或使用任何其他“退出”动画。转场本身就是退场。转场开始时，离场场景的内容必须完全可见。
4. 仅限最终场景： 最后一个场景可以将元素淡出（例如淡至黑屏）。这是唯一允许使用 gsap.to(..., { opacity: 0 }) 的场景。

错误——转场前使用退场动画：

// BANNED — this empties the scene before the transition can use it
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// transition fires on empty frame

正确——仅使用入场动画，由转场处理退场：

// Scene 1 entrance animations
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// NO exit tweens — transition at 7.2s handles the scene change
// Scene 2 entrance animations
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

动画注意事项

• 首个动画延后 0.1-0.3s（不要设为 t=0）
• 让入场补间使用不同的缓动函数——每个场景至少使用 3 种不同的缓动函数
• 不要在同一场景中重复入场模式
• 深色背景避免使用全屏线性渐变（H.264 会产生色带——使用径向渐变，或纯色 + 局部光晕）
• 渲染视频中的标题字号至少为 60px，正文至少为 20px，数据标签至少为 16px
• 在数字列上使用 font-variant-numeric: tabular-nums

如果未提供 visual-style.md 或动画方向，请遵循 house-style.md 中的美学默认设置。

排版与素材

• 字体： 只需在 CSS 中写入所需的 font-family，编译器会自动嵌入受支持的字体。如果字体不受支持，编译器会发出警告。
• 为外部媒体添加 crossorigin="anonymous"
• 对于动态文本溢出，使用 window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })
• 所有文件都放在项目根目录，与 index.html 同级；子合成使用 ../

编辑现有合成

• 先通读整个合成，沿用现有字体、颜色和动画模式
• 只修改要求修改的内容
• 保持无关片段的时间安排不变

输出检查清单

• npx hyperframes lint 和 npx hyperframes validate 均通过
• npx hyperframes inspect 通过，或所有报告的溢出都已明确标记
• 已处理对比度警告（见下方“质量检查”）
• 已处理布局问题（见下方“质量检查”）
• 已验证动画编排（见下方“质量检查”）

质量检查

视觉检查

hyperframes inspect 会在无头 Chrome 中运行合成，沿时间线逐帧检查，并标出带时间戳、选择器、边界框和修复提示的视觉布局问题。在运行 lint 和 validate 后执行：

npx hyperframes inspect
npx hyperframes inspect --json

失败通常意味着文本溢出气泡/卡片、固定尺寸的标签裁切了动态文案，或文本移出了画布。可通过增大容器尺寸或内边距、减小字号或字间距、设置实际的 max-width 让文本在容器内换行，或对动态文案使用 window.__hyperframes.fitTextFontSize(...) 来修复。

对于内容密集的视频，使用 --samples 15；对于特定的主视觉帧，使用 --at 1.5,4,7.25。默认会合并重复的静态问题，避免 Agent 上下文被大量信息淹没。如果溢出是进场/退场动画中的有意设计，请为该元素或其祖先添加 data-layout-allow-overflow。如果装饰性元素不应接受审计，请为其添加 data-layout-ignore。

hyperframes layout 是同一检查的兼容性别名。

对比度

默认情况下，hyperframes validate 会执行 WCAG 对比度审计。它会跳转到 5 个时间戳，对页面截图，对每个文本元素背后的背景像素进行采样，并计算对比度。失败项会显示为警告：

⚠ WCAG AA contrast warnings (3):
  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

如果出现警告：

• 深色背景上：提亮未通过的颜色，直到达到 4.5:1（普通文本）或 3:1（大号文本，即 24px 及以上，或 19px 及以上的粗体文本）
• 浅色背景上：加深颜色
• 保持在同一调色板范围内，不要创造新颜色，只调整现有颜色
• 重新运行 hyperframes validate，直到没有警告

如果需要快速迭代并计划稍后检查，可使用 --no-contrast 跳过检查。

动画图

编写动画后，运行动画图以验证动画编排：

node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

输出单个 animation-map.json，其中包含：

• 逐补间摘要："#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"
• ASCII 时间线：展示整个合成时长内所有补间的甘特图
• 错开检测：报告实际间隔（"3 elements stagger at 120ms"）
• 空白区段：超过 1s 没有动画的区段——是有意停留，还是缺少进场动画？
• 元素生命周期：首次/最后动画时间、最终可见性
• 场景快照：5 个关键时间戳处的可见元素状态
• 标记：offscreen、collision、invisible、paced-fast（短于 0.2s）、paced-slow（长于 2s）

阅读 JSON。检查摘要中是否有意外情况。检查每个标记，并修复问题或说明其合理性。确认时间线显示了预期的动画编排节奏。修复后重新运行。

小幅编辑（如修复颜色、调整单个时长）时可跳过。新建合成或大幅修改动画时应运行。

参考资料（按需加载）

• references/captions.md — 字幕、隐藏字幕、歌词、与音频同步的卡拉 OK。自适应语气的样式检测、逐词样式、文本溢出防护、字幕退出保障、词语分组。添加与音频时间同步的文本时阅读。

• references/tts.md — 使用 Kokoro-82M 进行文本转语音。语音选择、速度调整、TTS+字幕工作流。生成旁白或配音时阅读。

• references/audio-reactive.md — 音频响应动画：将频段和振幅映射到 GSAP 属性。需要视觉效果响应音乐、语音或声音时阅读。

• references/css-patterns.md — CSS+GSAP 标记高亮：高亮、画圈、爆发、涂鸦、描边。确定性强，完全支持时间轴定位。为文本添加视觉强调时阅读。

• references/typography.md — 字体排版：字体搭配、OpenType 特性、深色背景调整、字体发现脚本。始终阅读——每个创作内容都包含文本。

• references/motion-principles.md — 动态设计原则：缓动表达情绪、时长体现分量、编排构建层级、场景节奏、环境动态、反模式。编排 GSAP 动画时阅读。

• visual-styles.md — 8 种命名视觉风格（Swiss Pulse、Velvet Standard、Deconstructed、Maximalist Type、Data Drift、Soft Signal、Folk Frequency、Shadow Cut），包含十六进制调色板、GSAP 缓动特征和着色器搭配。用户指定风格或生成 DESIGN.md 时阅读。

• house-style.md — 未指定风格时使用的默认动态效果、尺寸和调色板。

• patterns.md — PiP、标题卡片、幻灯片模式。

• data-in-motion.md — 数据、统计和信息图模式。

• references/transcript-guide.md — 转录命令、whisper 模型、外部 API、故障排除。

• references/dynamic-techniques.md — 动态字幕动画技巧（卡拉 OK、clip-path、slam、scatter、elastic、3D）。

• references/transitions.md — 场景转场：交叉淡化、擦除、显现、着色器转场。能量/情绪选择、CSS 与 WebGL 指南。多场景创作时始终阅读——没有转场的场景会感觉像直接跳切。

  • transitions/catalog.md — 硬性规则、场景模板，以及各类型实现代码的索引。
  • 着色器转场位于 @hyperframes/shader-transitions（packages/shader-transitions/）——阅读软件包源码，而非技能文件。

GSAP 模式和效果位于 /gsap 技能中。