HyperFrames 核心
HyperFrames 将 HTML 渲染为视频。合成是一个 HTML 文件,其 DOM 通过 data-* 属性声明时间,动画运行时可以寻址,媒体播放由框架拥有。
本技能是技术合约——如何构建一个 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,使剪辑相对于另一个剪辑计时 |
references/sub-compositions.md | 连接子合成(宿主属性、<template>、实例变量)并在其中制作动画 |
references/variables-and-media.md | 声明变量;放置 <video>/<audio>,设置音量,修剪 |
references/determinism-rules.md | 构建可寻址时间线;确定性禁止列表;可动画属性允许列表;布局/文本适配 |
references/full-screen-motion.md | 使用共享背景制作全帧动画 |
references/storyboard-format.md | 编写 STORYBOARD.md 计划(+ 解析后的清单) |
references/review-loop.md | 在活动看板上运行计划→草图→构建审查流程——所有故事板规划工作流程共享 |
references/production-loop.md | 将批准的计划转化为最终视频——阶段依赖关系(音频、帧、组装、转场、字幕、验证、交付)一个自由形式的构建紧随其后 |
references/brief-contract.md | 简报的基本规则——模式推导(协作式/自主式)、共享字段注册表、问题不变量(提问本身位于 /hyperframes→意图层) |
references/brief-format.md | 编写 BRIEF.md——已确认的意图文档,工作流的 Setup 阶段编写,后续每个阶段读取 |
references/script-format.md | 编写可选的 SCRIPT.md 锁定叙述 |
references/subagent-dispatch.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>包装器(包装它会隐藏所有内容并破坏渲染)。 - 子合成(通过
data-composition-src加载)——根必须包裹在<template>中。
⚠ 传输规则:运行时仅克隆
<template>内容;外部所有内容(包括<head>中的样式/脚本)都会被丢弃——将<style>/<script>放在 template 内部。 ⚠ 宿主 ID 规则:宿主插槽的data-composition-id必须完全等于内部模板的data-composition-id以及window.__timelines["<id>"]键——不要添加-mount/-slot/-host后缀。
文件形状、宿主连接以及预渲染检查清单 → references/sub-compositions.md。
根必须有尺寸(静默布局错误)
独立根需要一个明确的尺寸盒(width/height 以像素为单位),并且每个祖先元素直到 height:100% 的元素都必须有确定的高度——否则 flex/100% 的子元素会塌缩到约 0,内容堆积到左上角。不要仅依赖自动化门控来捕获此问题;检查快照。骨架 → references/minimal-composition.md。
一个暂停的时间线
每个合成都注册恰好一个 gsap.timeline({ paused: true }) 到 window.__timelines["<id>"](键 = 根 data-composition-id),在页面加载时同步构建。渲染时长 = 根 data-duration,而不是时间线长度。不要手动将子时间线嵌套到宿主中。完整合约(包括非 GSAP 运行时)→ references/determinism-rules.md + hyperframes-animation/adapters/。
不可协商的规则(自动化门控可能遗漏的静默错误)
在此列出;完整理由见链接的参考文档。不得违反:
- 无渲染时时钟/无种子
Math.random/网络/输入状态;无repeat: -1(使用有限次数)。→determinism-rules.md - 仅动画化视觉属性允许列表中的属性;切勿使用补间来更改
display或原始visibility。GSAPautoAlpha和零时长时间线边界设置是唯一的可见性例外,且仅适用于非剪辑元素或剪辑内的包装器。框架单独控制.clip可见性。不要在页面加载时使用gsap.set设置后续场景的剪辑。→determinism-rules.md - 正文文本中无
<br>;变换后的元素必须为块级并设置尺寸;脉动的绝对定位装饰元素需要峰值间隔。→determinism-rules.md <video>/<audio>必须是宿主根的直接子元素(绝不在子合成<template>/包装器内部);框架拥有播放控制。→variables-and-media.md- 每个
id必须在组装后的页面中唯一;在子合成内部,给 id 加上合成 id 前缀(#<id>-hero)。重复的<video>/<img>id 会渲染为空白——制片人通过getElementById注入帧,跨文件重复会绕过lint检查。→composition-patterns.md - 全屏场景填充应放在出血子元素上(
position:absolute; inset:0),绝不能放在合成根自身——制片人的帧合成可能会丢弃根元素自身的background(帧渲染为黑色),即使预览/snapshot显示正确。→composition-patterns.md
编辑现有合成
- 先读取文件。保留不相关的计时、轨道、ID、变量、媒体路径。
- 匹配现有的合成 ID 和时间线键。
- 添加剪辑:选择非重叠的
data-track-index或有意调整周围计时。 - 任何合成元素上的
data-hidden都会在预览和渲染中隐藏它,覆盖其时间窗口;它是非破坏性/可逆的,并由 Studio 的时间线眼睛图标切换。 - 添加子合成:在连接宿主之前验证其内部的
data-composition-id。
验证
使用 hyperframes-cli 获取命令详细信息
-
npx hyperframes check通过(lint、运行时、布局、运动、对比度均为 0 问题) - 包含子合成的项目:
npx hyperframes snapshot --at <midpoints>并目视检查每一帧 - 用于审查的
npx hyperframes preview(用户可以在 Studio 的时间线中编辑任何内容) - 仅在用户批准后运行
npx hyperframes render