HyperFrames
HTML是视频的真理之源。合成是一个带有data-*属性的HTML文件,用于控制时间、GSAP时间线驱动动画,以及CSS控制外观。该框架处理剪辑可见性、媒体播放和时间线同步。
方法
探索(仅限探索性请求)
对于开放式请求(“给我制作一个产品发布视频”、“为我们的品牌创建一些内容”),在用户尚未确定方向的情况下,先理解意图,再选择颜色:
- 受众——谁在看这个?开发者?高管?普通消费者?
- 平台——在哪里播放?社交媒体(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。以适合视频的比例使用品牌颜色——而不是以网页UI的不透明度使用。
第2步:提示扩展
在每个合成上始终运行(除了单场景片段和简单编辑)。此步骤将用户的意图针对 design.md 和 house-style.md 进行落地,并产生一个一致的中间产物,所有下游代理都以相同方式读取。
读取 references/prompt-expansion.md 了解完整流程和输出格式。
第3步:计划
在编写HTML之前,先进行高层思考:
- 内容——观众应该体验到什么?确定叙事弧线、关键时刻和情感节拍。
- 结构——多少个合成,哪些是子合成 vs 内联,哪些轨道承载什么(视频、音频、覆盖层、字幕)。
- 节奏——在实施之前声明你的场景节奏。哪些场景是快速点击,哪些是保持,着色器落在哪里,能量峰值在哪里。命名模式:快-快-慢-快-着色器-保持。阅读 references/beat-direction.md 了解节奏模板。
- 时间——哪些剪辑驱动持续时间,过渡落在哪里,节奏如何。
- 布局——首先构建最终状态。参见下面的“先布局后动画”。
- 动画——然后使用以下规则添加运动。
按要求构建。 一个“标题卡片”的请求不是“标题卡片 + 3个辅助场景 + 背景音乐 + 字幕”的请求。每个场景、每个元素、每个补间都应该赢得它存在的理由。如果额外的场景或元素能真正改进作品,请提出建议——不要直接添加。
对于小型编辑(修复颜色、调整时间、添加一个元素),直接跳到规则。
<硬性限制>
在编写任何合成HTML之前——验证你已经从第1步获得了视觉标识。如果你正在使用 #333、#3b82f6 或 Roboto,说明你跳过了这一步。
</硬性限制>
先布局后动画
将每个元素放置在它最可见的时刻——即它完全进入、正确放置且尚未退出的帧。先将其编写为静态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/合成必需 | 秒。视频/音频默认为媒体时长。 |
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-variable-values | 否 | 子合成宿主元素上的每个实例变量覆盖的JSON对象 |
在根 <html> 元素上:
| 属性 | 必需 | 值 |
|---|---|---|
data-composition-variables | 否 | 已声明变量的JSON数组(id/type/label/default)——驱动Studio编辑UI并为 getVariables() 提供默认值 |
合成结构
通过 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>
变量(参数化合成)
使用不同内容(标题、主题颜色、价格、字幕)渲染相同的合成,而无需编辑源HTML。
三步模式:
- 声明 变量在合成的
<html>根元素上,使用data-composition-variables。每个条目需要id、type(string、number、color、boolean、enum之一)、label和default。枚举条目还需要options: [{value, label}, ...]。 - 读取 合成内部脚本中解析后的值,使用
window.__hyperframes.getVariables()。返回声明的默认值 + 每个实例覆盖 + CLI覆盖的合并结果。 - 覆盖 在渲染时使用
npx hyperframes render --variables '{...}'(顶层)或使用宿主元素上的data-variable-values='{...}'(子合成的每个实例)。
<!doctype html>
<html
data-composition-variables='[
{"id":"title","type":"string","label":"标题","default":"你好"},
{"id":"theme","type":"enum","label":"主题","default":"light","options":[
{"value":"light","label":"浅色"},
{"value":"dark","label":"深色"}
]}
]'
>
<body>
<div data-composition-id="root" data-width="1920" data-height="1080">
<h1 id="hero" class="clip" data-start="0" data-duration="3"></h1>
<script>
const { title, theme } = window.__hyperframes.getVariables();
document.getElementById("hero").textContent = title;
document.body.dataset.theme = theme;
</script>
</div>
</body>
</html>
# 开发预览使用声明的默认值
npx hyperframes preview
# 使用覆盖渲染
npx hyperframes render --variables '{"title":"第四季度报告","theme":"dark"}' --output q4.mp4
# 或者从JSON文件
npx hyperframes render --variables-file ./vars.json
子合成每个实例的值: 相同的 getVariables() 在通过 data-composition-src 加载的子合成内部工作。每个宿主元素传递其自己的值:
<div
data-composition-id="card-pro"
data-composition-src="compositions/card.html"
data-variable-values='{"title":"专业版","price":"$29"}'
></div>
<div
data-composition-id="card-enterprise"
data-composition-src="compositions/card.html"
…
[为翻译截断]