HyperFrames
HTML 是视频的真相来源。一个合成文件就是一个带有 data-* 属性用于时序的 HTML 文件,使用 GSAP 时间线进行动画,CSS 控制外观。框架处理剪辑可见性、媒体播放和时间线同步。
属性 API、合成/模板结构、变量和媒体规则: references/authoring.md。在会话中编写第一个合成 HTML 之前,请先阅读它。
方法
发现(仅针对探索性请求)
对于开放式的请求(“给我做一个产品发布视频”),当用户尚未确定方向时,先了解意图再选择颜色:受众、平台、优先级(运动质量 vs. 精度 vs. 速度),以及他们是否想要变体。如果要求变体,则提供 2-3 个在节奏或结构上不同的选项——一个安全,一个有野心——而不是简单换色。
对于具体请求(“添加一个标题卡片”,“修复场景 3 的时间”),跳过发现步骤。
步骤 1:设计系统
如果存在 design.md 或 DESIGN.md,首先读取它(注意两种大小写——在 Linux 上它们是不同的文件)。它是品牌颜色、字体和约束的真相来源——使用它的确切值。如果它指定了字体,但在 fonts/ 中没有对应的 .woff2 文件,也无法内置匹配,则在编写 HTML 之前警告用户。
如果没有 design.md,提供一个选择:
- 用户提到了风格或情绪? 读取 visual-styles.md(8 个命名预设),选择最接近的一个。
- 视觉化浏览? 运行设计选取器 - references/design-picker.md。
- 快速启动? 询问情绪、亮/暗、品牌颜色/字体;从 house-style.md 中选择一个调色板。
design.md 定义品牌,而不是视频合成规则。 那些来自 references/video-composition.md 和 house-style.md。品牌颜色应以视频规模应用,而不是网页 UI 的不透明度。
步骤 2:提示扩展
对除单场景片段和微小修改外的每个合成执行——根据 design.md/house-style.md 确定意图,形成一致的中间表示。流程和格式: references/prompt-expansion.md。
步骤 3:规划
- 什么 - 叙事弧线、关键时刻、情感节奏。
- 结构 - 多少个合成、子组合 vs. 内联、哪些轨道承载什么。
- 节奏 - 在实现之前声明场景节奏 (快-快-慢-快-着色器-停顿)。模板: references/beat-direction.md。
- 时序 - 哪些剪辑驱动持续时间、过渡落在哪里。
- 布局 - 首先构建结束状态(下一节)。
- 动画 - 然后添加运动。
只构建被要求的内容。 “一个标题卡片”不是“一个标题卡片 + 3 个支持场景 + 音乐 + 字幕。”建议额外内容;不要擅自添加。
对于小修改,直接跳到规则。
先布局后动画
将每个元素放置在其最可见的时刻——完全进入、正确放置、尚未退出。先将其编写为静态 HTML+CSS。尚不使用 GSAP。
原因:如果你将元素定位在动画开始状态(屏幕外、透明度 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(当内容增长时会溢出)。将绝对定位保留给装饰性元素。 - 使用
gsap.from()进入——从屏幕外动画到 CSS 位置。CSS 是事实依据;补间是过程。(通过data-composition-src加载的子组合:优先使用gsap.fromTo()——参见 references/motion-principles.md。) - 仅最终场景:使用
gsap.to()退出。 所有其他场景以完全可见结束——过渡本身就是退出(下面的过渡规则 3)。
如果元素 A 在元素 B 进入同一区域之前退出,为两者提供其各自英雄帧的正确 CSS 位置——时间线防止它们共存,并且布局步骤会捕获因时序错误导致的意外重叠。有意分层(文字后的辉光、卡片堆叠)是可以的;此步骤旨在捕获无意的重叠——两个标题碰撞、一个统计信息覆盖标签、内容脱离帧。
时间线契约
- 所有时间线以
{ 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、变换)。永远不要动画 visibility 或 display;永远不要调用 video.play()/audio.play()。
动画冲突: 永远不要同时从多个时间线动画同一元素的同一属性。
没有 repeat: -1: 无限重复会破坏捕获引擎。计算 repeat: Math.ceil(duration / cycleDuration) - 1。
同步时间线构建: 永远不要在 async/await、setTimeout 或 Promise 内部构建时间线——捕获引擎在加载后同步读取 window.__timelines。字体由编译器嵌入;无需等待字体加载。
永远不要做:
- 忘记
window.__timelines注册 - 使用视频作为音频——始终是静音视频 + 单独的
<audio> - 将视频嵌套在定时 div 内——使用非定时包装器
- 使用
data-layer(使用data-track-index)或data-end(使用data-duration) - 动画视频元素尺寸——动画包装器 div
- 在媒体上调用播放/暂停/搜索——框架拥有播放控制权
- 创建没有
data-composition-id的顶层容器 - 在任何时间线或补间上使用
repeat: -1 - 异步构建时间线
- 在来自后续场景的剪辑元素上使用
gsap.set()——它们在页面加载时不存在于 DOM 中。在剪辑的data-start时间点或之后使用tl.set(selector, vars, timePosition)。 - 在内容文本中使用
<br>——它会与自然换行堆叠并导致重叠;改用max-width。例外:故意一行一个单词的短显示标题。
场景过渡(不可协商)
每个多场景合成必须遵守所有四条规则。违反任何一条都是无效的合成。
- 始终在场景之间使用过渡。 没有跳切。
- 始终通过
gsap.from()动画每个元素的进入。 没有元素是完全显现的。五个元素意味着五个进入补间。 - 除最终场景外,切勿使用退出动画。 在过渡之前没有
gsap.to()淡出透明度、移出屏幕或缩放到 0——过渡本身就是退出,并且当过渡触发时,离开的场景必须完全可见。过渡前的退出补间会向过渡传递一个空帧。 - 仅最终场景 可以淡出元素。
过渡选择与实现: references/transitions.md。
动画护栏
- 将第一个动画偏移 0.1-0.3s(不是 t=0)
- 变换缓动——每个场景至少 3 种不同的缓动,同一个场景内没有重复的进入模式
- 避免深色背景上的全屏线性渐变(H.264 条带)——使用径向或纯色 + 局部辉光
- 标题 60px+,正文 20px+,数据标签 16px+
- 在数字列上使用
font-variant-numeric: tabular-nums
编辑现有合成
- 读取实际文件,而不是猜测。 合成本身就是规格说明——从源代码提取确切十六进制颜色、字体和缓动模式,而不是凭借记忆。
- 只更改被请求的内容;保留无关剪辑的时序。
输出检查清单
快速(立即运行,阻塞结果):
-
npx hyperframes lint和npx hyperframes validate均通过 - 如果存在 design.md,则验证了设计一致性
慢速(在呈现预览时并行运行):
-
npx hyperframes inspect通过,或者每个报告的溢出都已有意标记 - 对比度警告已处理
- 动画编排已验证(animation-map 脚本)
如何运行和修复每个检查: references/quality-checks.md。
参考索引
对于任何新的合成,始终读取:
| 文件 | 涵盖内容 |
|---|---|
| references/authoring.md | data 属性、模板结构、变量、视频/音频、字体/资源 |
| references/video-composition.md | 视频媒介规则——这些覆盖了网页本能 |
| references/typography.md | 字体配对、OpenType、深色背景调整 |
| references/motion-principles.md | 动效设计、图像运动、关键 GSAP 规则 |
对于多场景合成,也始终读取:
| 文件 | 涵盖内容 |
|---|---|
| references/beat-direction.md | 节奏模板、编排动词、深度层次 |
| references/transitions.md | 过渡选择;目录 路由到实现;着色器过渡位于 @hyperframes/shader-transitions npm 包中(在其 node_modules 中读取源代码) |
当任务需要时读取:
| 文件 | 何时读取 |
|---|---|
| references/quality-checks.md | 运行 inspect/contrast/design/animation-map 检查时 |
| references/cli.md | 任何 CLI 命令;构建/渲染故障排除 |
| references/captions.md | 任何与音频时序同步的文本 |
| references/transcript-guide.md | 字幕端对话处理(CLI 调用位于 media.md 中) |
| references/dynamic-techniques.md | 动态字幕动画(卡拉 OK、闪现、散射) |
| references/audio-reactive.md | 响应音乐/语音的视觉 |
| references/css-patterns.md | 标记高亮(高亮、圆圈、爆发、涂鸦) |
| references/techniques.md | 每个节拍的规划技术(11 种模式及代码) |
| references/narration.md | 旁白/TTS 节奏和脚本结构 |
| references/media.md | TTS (Kokoro)、转录 (Whisper)、背景去除 |
| references/prompt-expansion.md | 方法的步骤 2 |
| references/design-picker.md | 可视化创建 design.md |
| references/from-website.md | 将网站转化为视频 |
| references/registry.md | 安装/贡献注册表块(hyperframes add) |
| visual-styles.md | 用户指定风格;生成 design.md |
| house-style.md | 没有 design.md 时的美学默认值 |
| patterns.md | 画中画、标题卡片、幻灯片 |
| data-in-motion.md | 数据、统计、信息图 |
运行时适配器(当合成使用该运行时而非 GSAP 时读取):waapi、 lottie、 three、 animejs、 css-animations、 typegpu。