HyperFrames Core
HyperFrames 从 HTML 渲染视频。合成是一个 HTML 文件,其 DOM 通过 data-* 属性声明时序,其动画运行时是可查找的,并且媒体播放由框架拥有。
此技能是技术契约。其他关注点位于同级技能中:
hyperframes-animation— 原子运动规则 + 场景蓝图 + 每个运行时的适配器(GSAP、Lottie、Three、Anime.js、CSS、WAAPI、TypeGPU)hyperframes-creative— 调色板、排版、旁白、节拍规划、音频响应hyperframes-media— TTS、Whisper 转录、背景去除、字幕hyperframes-registry— 安装块和组件(hyperframes add)hyperframes-cli— 开发循环命令(lint / validate / preview / render)
对于 Tailwind v4 项目(hyperframes init --tailwind),请参阅 references/tailwind.md — 浏览器运行时契约与 Studio 的 Tailwind v3 设置不同。
路由
| 需求… | 阅读 |
|---|---|
| 查看最小可渲染合成 | references/minimal-composition.md |
| 决定单片单文件架构与模块化子合成架构 | references/composition-patterns.md |
构建模块化 index.html(协调器 + 插槽 + 根音频) | references/composition-patterns.md |
| 选择子合成原型(内容 / 仅驱动 / 多场景合并 / 音频响应) | references/composition-patterns.md |
查找 data-* 属性(根、剪辑片段、子合成宿主、遗留别名) | references/data-attributes.md |
正确使用 class="clip" | references/data-attributes.md |
选择 data-track-index;同轨重叠;轨道索引与 CSS z-index 对比 | references/tracks-and-clips.md |
使一个剪辑片段相对于另一个计时(data-start="intro + 2",交叉淡入淡出重叠,链式) | references/tracks-and-clips.md |
连接子合成(宿主属性,<template> 包装器,每个实例的变量) | references/sub-compositions.md |
在子合成内部动画(gsap.fromTo 优先于 gsap.from,回退行为) | references/sub-compositions.md |
声明变量(类型、额外选项、默认值,CI 中的 --strict-variables) | references/variables-and-media.md |
放置 <video> / <audio>,设置音量,使用 data-media-start 修剪 | references/variables-and-media.md |
构建可查找的时间线(暂停、同步构造、gsap.set 后期场景陷阱) | references/determinism-rules.md |
避免非确定性状态(时钟、Math.random、repeat: -1、有限重复公式) | references/determinism-rules.md |
了解哪些可以/不可以动画化(可视属性允许列表;不是 display/visibility) | references/determinism-rules.md |
适合文本并防止溢出(fitTextFontSize 签名,<br> 规则,布局约定) | references/determinism-rules.md |
| 创作全帧运动并共享背景 | references/full-screen-motion.md |
在 Tailwind v4 项目中工作(init --tailwind) | references/tailwind.md |
对于动画运行时细节(GSAP API、Lottie、Three.js 等),请访问 hyperframes-animation → adapters/<runtime>.md。
合成结构
两种根形式;它们不可互换。
- 独立合成(顶级
index.html)— 根<div data-composition-id="…">直接位于<body>中。没有<template>包装器。 将独立根包装在<template>中会向浏览器隐藏所有内容并破坏渲染。 - 子合成(通过
data-composition-src加载的文件)— 根<div data-composition-id="…">必须 包装在<template>中。没有包装器,运行时无法提取和挂载它。
⚠ 子合成传输规则:运行时仅克隆
<template>内容到实时 DOM 中。模板之外的所有内容 — 包括<head>和<head>中的任何<style>/<script>/<link>— 都将被丢弃。将<style>和<script>块放入<template>内部,而不是<head>中。⚠ 宿主 ID 规则:在宿主文件中,插槽上的
data-composition-id必须完全等于内部模板的data-composition-id以及window.__timelines["<id>"]键。不要添加-mount/-slot/-host后缀。
有关文件形状、宿主连接、陷阱示例以及渲染前验证清单,请参阅 references/sub-compositions.md。
根必须设置大小(静默布局错误)
独立根必须建立一个显式大小的盒子,并且 height: 100% 元素与根之间的每个祖先都必须有一个已解析的高度。如果根或中间包装器没有高度,flex/height:100% 内容容器会折叠到大约 0,并且内容会堆积在左上角(通常会截断 x=0 处的第一个字形)。lint、validate 和 inspect 不会捕获这一点 — inspect 会用创作的 data-width/data-height 替换折叠的根,并报告“0 个布局问题”。
<body style="margin: 0">
<div
id="root"
data-composition-id="main"
data-width="1920"
data-height="1080"
data-duration="5"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
>
<!-- 强制定位:position:absolute + inset:0 填充已设置大小的根,无论中间包装器如何;
或者仅当父级链已设置大小时,才使用 flex 容器。 -->
<section
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
>
<h1>标题</h1>
</section>
</div>
</body>
使 padding(≥80px)位于居中容器上 — 它是标题安全边距,可防止大号文字触及框架边缘。请参阅 references/minimal-composition.md。
时间线约定(GSAP 默认)
每个合成注册恰好一个 GSAP 时间线。
- 使用
gsap.timeline({ paused: true })创建 — 播放器拥有播放权限。 - 注册到
window.__timelines["<composition-id>"];键必须与根的data-composition-id完全匹配。如果 id 是有效的标识符,则点语法(window.__timelines.<id> = tl)是等效的;如果 id 包含-,则使用括号。 - 在页面加载期间同步构建时间线 — 而不是在
async、setTimeout、Promise或事件处理程序内部。渲染器在页面加载完成后进行采样;任何延迟的时间线构建都会错过采样。 - 渲染持续时间来自根上的
data-duration,而不是来自 GSAP 时间线长度。不要用空补间填充时间线来设置持续时间。 - 对于子合成,不要手动将子时间线嵌套到宿主中(
master.add(sub));框架独立驱动它们。
对于非 GSAP 运行时(Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU),等效约定位于 hyperframes-animation/adapters/<runtime>.md 中。有关跨运行时动画运行时约定,请参阅 references/determinism-rules.md。
不可协商规则
这些会破坏渲染器 — 或产生 lint/validate/inspect 无法捕获的静默视觉错误(规则 3、7-8)。(同步时间线构建在上面的时间线约定中已涵盖。)
- 没有
Math.random()/Date.now()/performance.now()驱动视觉效果 — 使用种子化 PRNG。 - 没有
repeat: -1。使用repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)—floor,不是ceil(ceil会超出data-duration并触发gsap_repeat_ceil_overshootlint;max(0, …)可避免负重复 = 无限)。 <video>/<audio>必须是宿主根(index.html)的直接子元素 — 永远不要在子合成<template>内部,永远不要在包装器<div>内部;否则它将永远不会被解码并渲染为空白/黑色(静默错误)。框架拥有播放权限:没有video.play()/audio.play()/currentTime = …。子合成不能驱动宿主元素(选择器或querySelector),因此请在主时间线以全局时间动画化宿主媒体。请参阅references/variables-and-media.md。- 没有对来自后期场景的剪辑元素使用
gsap.set()(它们尚未存在于 DOM 中)。在剪辑元素的data-start时或之后使用tl.set(selector, vars, time)。 - 没有动画化
display/visibility。动画化opacity/ 变换;剪辑生命周期处理显示/隐藏。 - 正文文本中没有
<br>。通过max-width让文本自动换行。 - 变换后的元素必须是块级元素并且已设置大小。
transform/scaleX/scaleY对内联<span>是无操作的,缩放自动宽度(0px)的元素不会显示任何内容 → 不可见的条形/填充。为它们提供display: block/inline-block/flex-item 以及实际的width/height(例如,在已设置大小的父元素内使用width: 100%)。 - 绝对定位的装饰性元素(徽章、药丸、标签)如果脉冲或过冲(
yoyo缩放,back.out)需要在其峰值大小处具有间隙,并且不得跨越overflow: hidden边缘 — 否则它们会与相邻元素重叠或被裁剪。为最大帧定位,而不是静止帧。
编辑现有合成
- 在编辑之前读取实际文件。
- 保留不相关的时序、轨道、ID、变量和媒体路径。
- 匹配现有的合成 ID 和时间线注册键。
- 添加剪辑片段时,选择一个不重叠的
data-track-index或有意调整周围的时序。 - 添加子合成时,在连接宿主之前验证其内部的
data-composition-id。
验证
有关命令详细信息,请使用 hyperframes-cli。
-
npx hyperframes lint通过(0 个错误) -
npx hyperframes validate通过(0 个控制台错误) -
npx hyperframes inspect通过,或者溢出被有意标记 - 包含子合成的项目:
npx hyperframes snapshot --at <midpoints>并目测每一帧