HyperFrames 核心
AI 代理陷阱(请先阅读):
- 使用 flex/
inset居中,而不是在随后用 GSAPx/y动画的节点上使用 CSStransform: translate(-50%,-50%)。Lint 检查:gsap_css_transform_conflict。请改用fromTo或xPercent/yPercent。 - 不要添加场景退出时的
tl.set(..., {visibility:"hidden"})。运行时已经隐藏了计时剪辑。内层节点上的透明淡出(或.clip上的opacity)已足够。字幕硬终止是另一条规则。 window.__timelines["id"]必须与根元素的data-composition-id匹配。- 渲染后,读取摘要的第二行:
beginframe与screenshot、GPU 模式、阶段时序。Linux 上的screenshot+software gpu是慢路径。
HyperFrames 从 HTML 渲染视频。组合是一个 HTML 文件,其 DOM 通过 data-* 属性声明时序,动画运行时是可寻的,媒体播放由框架管理。
本技能是技术合约——如何构建一个 hyperframes 项目。以下正文是构建指南;每个主题的细节位于 references/(索引见下文),按需阅读。流程文档(简报、故事板、评审、制作、调度、帧工作者)位于 /hyperframes → references/。其他关注点位于兄弟领域技能——hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry。/hyperframes 中的能力地图说明了每个技能涵盖的内容。
参考文档
| 文件 | 阅读目的 |
|---|---|
references/minimal-composition.md | 从最小的可渲染组合骨架开始 |
references/composition-patterns.md | 选择整体式 vs 模块化;构建模块化 index.html;选择子组合原型 |
references/data-attributes.md | 查找任何 data-*(根 / 剪辑 / 子组合宿主 / 遗留别名);使用 class="clip" |
references/tracks-and-clips.md | 理解 data-track-index 的作用(及不能控制的内容)、z-index、剪辑相对于另一个的时序;使用 npx hyperframes timeline 列出每个轨道和剪辑 |
references/creator-editing-recipes.md | 复制真实的剪切/修剪/重排/重定时/冻结/相机/遮罩/交叉淡入淡出/音频编辑配方及其限制 |
references/sub-compositions.md | 连接子组合(宿主属性、<template>、每个实例的变量)并在其内部进行动画 |
references/variables-and-media.md | 声明变量;放置 <video>/<audio>、设置音量、修剪 |
references/determinism-rules.md | 构建可寻的时间线;确定性禁止项;布局 / 文本适配 |
references/full-screen-motion.md | 使用共享背景创作全帧动画 |
references/tailwind.md | 在 Tailwind v4 项目中工作(init --tailwind;运行时合约与 Studio 的 v3 不同) |
有关动画运行时细节(GSAP API、Lottie、Three.js 等),请参阅 hyperframes-animation → adapters/<runtime>.md。
构建组合
两种根形式(不可互换)
- 独立组合(顶层
index.html):根元素<div data-composition-id="…">直接位于<body>内,没有<template>包装。包装独立组合的根元素会隐藏所有内容,并且lint会拒绝(standalone_composition_wrapped_in_template,错误)。 - 子组合(通过
data-composition-src加载):用<template>包装根元素。这是推荐编写的形状:加载器也接受普通的完整文档并回退到其<body>,但模板化形式是示例和工具所假设的。
⚠ 传输规则:对于模板化的子组合,组装器会丢弃文件自身的
<head><style>/<script>(packages/core/src/compiler/compositionAssembly.ts,hasTemplate门),因此请将<style>/<script>放在模板内部。<link>无论哪种方式都会被提升。 ⚠ 宿主 ID 约定:给宿主插槽、内部模板和window.__timelines["<id>"]键使用相同的 ID。支持不同的本地 ID(组装器回退到文件中的第一个根元素),但不匹配是静默的,因此除非有理由,否则请匹配它们。
文件形状、宿主连接和预渲染清单 → references/sub-compositions.md。
根元素必须设置尺寸(静默布局错误)
独立组合的根元素设置 width/height: 100%。画布尺寸由 data-width/data-height 指定。运行时将这些像素值应用到组合根元素。不要硬编码为 1920px/1080px。骨架 → references/minimal-composition.md。
一个暂停的时间线
每个组合注册恰好一个 gsap.timeline({ paused: true }) 位于 window.__timelines["<id>"](键 = 根元素的 data-composition-id)。在异步回调(document.fonts.ready)内部构建它是支持的;重要的是你仅在构建完成后注册。渲染长度是根元素的 data-duration,不是时间线的长度:超出其长度的时间线会被截断,而提前结束的时间线会保持其最后一帧。省略根元素的 data-duration 则会推断长度(时间线、媒体窗口或适配器)。你不需要 window.__timelines = window.__timelines || {}:运行时会在你的内联脚本运行前创建注册表,并且 lint 不再要求它。不要手动将子时间线嵌套到宿主中;运行时会自动嵌套注册的子时间线。完整合约(包括非 GSAP 运行时)→ references/determinism-rules.md + hyperframes-animation/adapters/。
首次 lint 陷阱(保证第一次构建失败)
lint 确实会捕获的规则,但仅在事后。首次即正确编写:
- 永远不要将 CSS 初始
transform与 GSAP 在相同属性上的补间配对——CSS 值和补间的起始值会产生冲突,并且lint会以gsap_css_transform_conflict拒绝。请使用gsap.fromTo(el, { x: -40 }, { x: 0 })在补间内部设置初始状态,而不是使用 CSStransform: translateX(-40px)。 - 永远不要在
<video>/<audio>上设置crossorigin。lint无条件地以media_crossorigin_breaks_preview(错误)拒绝,包括 canvas/WebGL/WebAudio 回读。没有抑制方法。 - 永远不要给带有
data-start的<video>一个也带有data-start的祖先。lint以video_nested_in_timed_element(错误)拒绝。请为包装器或视频设置时序,不要同时设置。 - 每个
<audio>都需要一个id。lint以media_missing_id拒绝,并且没有 ID 的<audio>永远不会被混音器拾取,因此渲染是静音的。 - 永远不要用
autoAlpha或visibility补间.clip——lint以gsap_animates_clip_element拒绝。请改为对子元素进行动画。 - 命名的 CSS
font-family需要一个文件内@font-face指向已提供的本地文件,否则lint会触发font_family_without_font_face。 - 子组合的
#root使用width/height: 100%(或inset: 0),而不是硬编码的1920px/1080px。画布尺寸由data-width/data-height指定。
一个 lint 错误也会关闭布局和对比度审计:check 随后报告 0 sample(s) 和 0/0 text checks,这看起来像是干净的文件,但意味着什么也没运行。在信任这些数字之前,请清除 lint 错误。
不可协商的规则(自动化门可能遗漏的静默错误)
在此列出;完整原理请参考链接的参考文档。请勿违反:
- 无渲染时时钟 / 未播种的
Math.random/ 网络 / 输入状态;无repeat: -1(使用有限次数)。→determinism-rules.md - 永远不要在
.clip元素上补间display、visibility或autoAlpha。框架拥有剪辑可见性,并且lint会拒绝(gsap_animates_clip_element)。改为对子元素进行动画。→determinism-rules.md - 正文中无
<br>;变换后的元素必须是块级且已设置尺寸;脉动的绝对定位装饰元素需要峰值间隙。→determinism-rules.md <video>/<audio>通过平面文档查询找到,因此框架可以在任何嵌套深度(包括在子组合<template>或包装器内部)查找和解码它们。一个硬性限制:如果带有data-start的<video>位于另一个也带有data-start的普通元素内部,lint会报错,并且故障是真实的(错误的源帧,然后剪辑在插槽中间消失),因此请将时序放在包装器或视频上,永远不要同时放。子组合宿主除外:子组合内部的媒体可以正确渲染。另一个注意事项是时间线,而不是放置:子组合时间线不能动画宿主根元素。→variables-and-media.md- 保持每个
id在组装后的页面中唯一(为子组合 ID 添加前缀,#<id>-hero),这样你自己的#idCSS 和getElementById调用才能正确解析。帧注入不再依赖于此:编译器会在每个video[src]/audio[src]/img[src]上打上一个文档唯一的data-hf-render-id。使用<source>子元素而不是src属性的媒体不会被打上标记,因此唯一的 ID 在那里仍然重要。→composition-patterns.md - 在组合根上的全屏填充在正常渲染下没问题。它仅会在分层合成路径(HDR 内容,或使用着色器过渡的组合)上被丢弃,因为引擎会强制每个组合根透明,以便下面的层显示出来。如果你的组合使用着色器过渡或 HDR 媒体,请将填充放在一个全出血的子元素上(
position:absolute; inset:0)。→composition-patterns.md
编辑现有组合
- 先阅读文件。保留不相关的时序、轨道、ID、变量、媒体路径。
- 要知道项目时间线上有什么(轨道、剪辑、开始、结束、播放内容),请运行
npx hyperframes timeline [--json],而不是读取index.html和每个子组合文件。 - 匹配现有的组合 ID 和时间线键。
- 添加剪辑:有意地针对周围剪辑设置其
data-start/data-duration。data-track-index是 Studio 的显示通道,不是时序约束,因此不需要空闲。 - 任何组合元素上的
data-hidden会在预览和渲染中都隐藏它,覆盖其时间窗口;它是非破坏性/可逆的,并由 Studio 时间线的眼睛图标切换。 - 添加子组合:在连接宿主之前,验证其内部的
data-composition-id。
验证
使用 hyperframes-cli 获取命令详情
-
npx hyperframes check通过(lint、运行时、布局、运动和对比度方面 0 个发现) - 包含子组合的项目:
npx hyperframes snapshot --at <midpoints>并目视检查每一帧 -
npx hyperframes preview --background用于审查(用户可以在 Studio 时间线中编辑任何内容,并且服务器在调用命令后仍然存活) - 仅在用户批准后运行
npx hyperframes render