HyperFrames
HTML 是视频的真理之源。合成是一个带有 data-* 属性(用于时间控制)、GSAP 时间线(用于动画)和 CSS(用于外观)的 HTML 文件。该框架负责处理剪辑可见性、媒体播放和时间线同步。
方法
发现阶段(仅限探索性请求)
对于开放式请求(如“制作一个产品发布视频”、“为我们的品牌创作一些东西”),在用户尚未确定方向时,在选取颜色前先理解意图:
- 受众——谁观看此视频?开发者?高管?普通消费者?
- 平台——在何处播放?社交媒体(15 秒)、网站英雄区、产品演示、内部使用?
- 优先级——什么最重要?动作质量?内容准确性?品牌一致性?速度?
- 变体——用户想要多个选项,还是一个最佳方案?
对于具体请求(如“添加一个标题卡”、“修复场景 3 的时间”),跳过发现阶段。
对于探索性请求,考虑提供 2-3 个有实质差异的变体——不仅仅是颜色交换,而是不同的节奏、能量水平或结构方法。一个安全/常规的,一个雄心勃勃的。不要强制要求——这只是一种在适当时候可用的工具。
步骤 1:设计系统
如果项目中存在 design.md 或 DESIGN.md,请先读取它(检查两种大小写——在 Linux 上是不同的文件)。它是品牌颜色、字体和约束的真理之源。使用其精确值——不要发明颜色或替换字体。任何格式都适用(YAML 前置元数据、散文、表格——只需提取值)。
如果它命名了本地无法找到的字体(没有包含 .woff2 文件的 fonts/ 目录,也不是内置字体),请在编写 HTML 之前警告用户:“design.md 指定了 [字体名称] 但未找到字体文件。请将 .woff2 文件添加到 fonts/,否则我将回退到 [最接近的内置替代方案]。”
如果不存在 design.md,请为用户提供选择:
- 用户指定了风格或情绪? → 阅读 visual-styles.md 了解 8 种命名预设。选择最接近的匹配。
- 想直观地浏览选项? → 运行设计选择器:阅读 references/design-picker.md 了解完整工作流。这将提供一个视觉选择器页面。用户在浏览器中配置情绪、调色板、排版和动作,然后复制生成的 design.md 并粘贴回对话中。
- 想跳过并快速进行? → 询问:情绪、浅色或深色、任何品牌颜色/字体?然后从 house-style.md 中选择调色板。
design.md 定义品牌。它不定义视频合成规则。 这些规则来自 references/video-composition.md 和 house-style.md。以适合视频的规模使用品牌颜色——而不是 web UI 的不透明度。
步骤 2:提示扩展
始终在每个合成上运行(单场景片段和微不足道的编辑除外)。此步骤将用户的意图与 design.md 和 house-style.md 对齐,并生成一个一致的中间产物,所有下游代理都按相同方式读取。
阅读 references/prompt-expansion.md 了解完整过程和输出格式。
步骤 3:规划
在编写 HTML 之前,从高层次思考:
- 什么——观众应该体验什么?确定叙事弧、关键时刻和情感节拍。
- 结构——有多少个合成,哪些是子合成 vs 内联,哪些轨道承载什么(视频、音频、叠加层、字幕)。
- 节奏——在实现之前声明你的场景节奏。哪些场景是快速点击,哪些是停顿,着色器落在哪里,能量峰值在哪里。命名模式:fast-fast-SLOW-fast-SHADER-hold。阅读 references/beat-direction.md 了解节奏模板。
- 时间——哪些剪辑驱动持续时间,过渡落在哪里,节奏如何。
- 布局——首先构建结束状态。参见下面的“布局优先于动画”。
- 动画——然后使用以下规则添加运动。
只构建被要求的内容。 一个“标题卡”的请求不是“标题卡 + 3 个辅助场景 + 背景音乐 + 字幕”的请求。每个场景、每个元素、每个补间都应该赢得其存在。如果额外的场景或元素能真正改善作品,提出它们——不要添加它们。
对于小型编辑(修复颜色、调整时间、添加一个元素),直接跳到规则。
布局优先于动画
将每个元素放置在其最可见时刻应该处于的位置——即它完全进入、正确放置且尚未退出的帧。首先将其编写为静态 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来完全填充场景。使用内边距将内容向内推——永远不要对内容容器使用position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。将position: absolute仅保留给装饰性元素。 - 使用
gsap.from()添加入场——从屏幕外/不可见动画到 CSS 位置。CSS 位置是基础事实;补间描述了到达那里的过程。(在通过data-composition-src加载的子合成中,优先使用gsap.fromTo()——参见 references/motion-principles.md 中的承载性 GSAP 规则。) - 使用
gsap.to()添加退场——从 CSS 位置动画到屏幕外/不可见。
示例
/* scene-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;
}
/* 容器填充任何场景尺寸(1920x1080、1080x1920 等)。
内边距定位内容。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="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、变换)。不要动画化 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
- 在媒体上调用 play/pause/seek——框架拥有播放控制
- 创建没有
data-composition-id的顶级容器 - 在任何时间线或补间上使用
repeat: -1——始终使用有限重复 - 异步构建时间线(在
async、setTimeout、Promise内部) - 在后期场景中对剪辑元素使用
gsap.set()——它们在页面加载时不存在于 DOM 中。请改用tl.set(selector, vars, timePosition)在剪辑的data-start时间或之后在时间线内。 - 在内容文本中使用
<br>——强制换行不考虑实际渲染的字体宽度。自然换行的文本加上<br>会产生额外的不需要的换行,导致重叠。请改用max-width让文本换行。例外:每个单词故意在单独行上的短显示标题(例如,130px 的 "THE\nIMMORTAL\nGAME")。
场景过渡(不可协商)
每个多场景合成必须遵循所有这些规则。违反其中任何一条都会导致合成损坏。
- **
…
[为翻译截断]