HyperFrames
HTML 是视频的唯一真实来源。一个合成是一个包含用于时序的 data-* 属性、用于动画的 GSAP 时间线和用于外观的 CSS 的 HTML 文件。该框架负责处理剪辑可见性、媒体播放和时间线同步。
方法
在编写 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 个字体系列)、## 禁止事项(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填满整个场景。使用内边距将内容向内推 — 切勿在内容容器上使用position: absolute; top: Npx。绝对定位的内容容器在内容高于剩余空间时会溢出。position: absolute保留仅用于装饰性元素。 - 使用
gsap.from()添加入场 — 从屏幕外/不可见动画到 CSS 位置。CSS 位置是事实来源;补间描述了到达该位置的路径。 - 使用
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/合成必需 | 秒数。视频/音频默认为媒体持续时间。 |
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 中。请改用时间线内剪辑的data-start时间或之后的时间位置上的tl.set(selector, vars, timePosition)。 - 在内容文本中使用
<br>— 强制换行不考虑实际渲染的字体宽度。自然换行的文本加上<br>会产生额外的、不需要的换行,导致重叠。请改用max-width让文本自动换行。例外:短小的显示标题,其中每个单词有意位于独立行(例如,130px 的“THE\nIMMORTAL\nGAME”)。
场景过渡(不可协商)
每个多场景合成必须遵循所有这些规则。违反其中任何一条都会导致合成错误。
- 始终在场景之间使用过渡。 没有跳切。没有例外。
- 始终在每个场景上使用入场动画。 每个元素通过
gsap.from()动画进入。没有元素可以完整形式出现。如果一个场景有 5 个元素,则它需要 5 个入场补间。 - 除非是最后一个场景,否则永远不要使用退出动画。 这意味着:在过渡触发之前,没有
gsap.to()将透明度动画到 0、将元素移出屏幕、缩放到 0 或任何其他“退出”动画。过渡本身即为退出。传出场景的内容必须在过渡开始时完全可见。 - 仅限最后一个场景: 最后一个场景可以淡出元素(例如,淡出到黑色)。这是唯一允许使用
gsap.to(..., { opacity: 0 })的场景。
错误 — 在过渡前使用退出动画:
// 禁止 — 这会在过渡能够使用场景之前清空它
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// 过渡在空帧上触发
正确 — 仅限入场,过渡处理退出:
// 场景 1 入场动画
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);
// 无退出补间 — 7.2 秒处的过渡处理场景切换
// 场景 2 入场动画
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);
动画护栏
- 将第一个动画偏移 0.1-0.3 秒(不在 t=0)
- 在入场补间中变化缓动效果 — 每个场景至少使用 3 种不同的缓动
- 不要在一个场景中重复使用入场模式
- 避免在深色背景上使用全屏线性渐变(H.264 条带 — 使用径向或纯色 + 局部发光)
- 渲染视频中标题 60px+、正文 20px+、数据标签 16px+
- 数字列上使用
font-variant-numeric: tabular-nums
当没有提供 visual-style.md 或动画方向时,请遵循 house-style.md 获取美学默认值。
版式和资源
- 字体: 只需在 CSS 中写入你想要的
font-family— 编译器会自动嵌入支持的字体。如果不支持某个字体,编译器会发出警告。 - 将
crossorigin="anonymous"添加到外部媒体 - 对于 ...
[翻译截断]