插件安装: 在执行设置或新鲜度命令之前,请遵循插件执行规则(当此技能位于 HyperFrames 插件内时)。独立安装则保留下方更新说明。
HyperFrames Core
代理陷阱(请先阅读):
- 使用 flex/
inset进行居中,不要使用 CSStransform: translate(-50%,-50%)然后在此基础上应用 GSAP 的x/y。Lint 检查:gsap_css_transform_conflict。请使用fromTo或xPercent/yPercent。 - 不要添加场景退出的
tl.set(..., {visibility:"hidden"})。运行时已经隐藏了计时片段。对内层节点进行透明度淡出(或对.clip使用opacity)就已足够。字幕硬性移除是另一条规则。 window.__timelines["id"]必须与根节点的data-composition-id匹配。- 执行
render后,阅读摘要的第二行:beginframevsscreenshot、GPU 模式、阶段计时。screenshot+software gpuon Linux 为慢速路径。
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 | 选择整体式或模块化;构建模块化 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 设置。运行时会将这些像素值应用到合成根节点上。不要在 #root 上硬编码 1920px/1080px。骨架 → references/minimal-composition.md。
一个暂停的时间线
每个合成在 window.__timelines["<id>"](键值 = 根节点的 data-composition-id)处注册恰好一个 gsap.timeline({ paused: true })。在异步回调(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(错误)拒绝它,包括画布/WebGL/WebAudio 回读。没有抑制方法。 - 永远不要给带有
data-start的<video>祖先元素也同时添加data-start。lint会用video_nested_in_timed_element(错误)拒绝。给包装器或视频添加时间,不要同时添加。 - 每个
<audio>都需要一个id。lint会用media_missing_id拒绝,没有 ID 的<audio>永远不会被混音器拾取,因此渲染会是静默的。 - 永远不要对
.clip使用autoAlpha或visibility进行补间——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仅在有限的根节点data-duration下使用(将导出发送到它——否则使用有限次数)。→determinism-rules.md - 永远不要对
.clip元素使用display、visibility或autoAlpha进行补间。框架拥有片段的可见性,lint会拒绝它(gsap_animates_clip_element)。改为对子元素进行动画。→determinism-rules.md - 正文文本中不要使用
<br>;变换后的元素必须是块级+有尺寸;脉冲式的绝对定位装饰元素需要顶部间隙。→determinism-rules.md <video>/<audio>通过扁平文档查询找到,因此框架会在任何嵌套深度上进行搜索和解码(包括在子合成<template>或包装器内部)。一个硬性限制:如果<video data-start>位于另一个也带有data-start的普通元素内部,lint会报错,且失败是真实的(源帧错误,然后片段在中间槽消失),因此请将时间放在包装器或视频上,永远不要同时添加。子合成宿主是豁免的:子合成内的媒体可以正确渲染。其他注意事项关于时间线,而非放置位置:子合成时间线不能对宿主根节点元素进行动画。→variables-and-media.md- 确保装配后页面上的每个
id都是唯一的(为子合成 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-duration的片段会被截断:在同一编辑中将根节点data-duration扩展到片段的结束(lint会警告clip_ends_past_root_duration)。 - 任何合成元素上的
data-hidden会在预览和渲染中都隐藏它,覆盖其时间窗口;这是非破坏性/可逆的,由 Studio 时间线的眼睛图标切换。 - 添加子合成:在连接宿主之前验证其内部的
data-composition-id。
验证
使用 hyperframes-cli 获取命令详情
-
npx hyperframes check通过(在 lint、运行时、布局、动态和对比度方面没有发现任何问题) - 包含子合成的项目:
npx hyperframes snapshot --at <midpoints>并目视检查每一帧 -
npx hyperframes preview --background用于审阅(用户可以在 Studio 的时间线中编辑任何内容,并且服务器在调用命令后继续运行) - 仅在用户批准后执行
npx hyperframes render