OpenMontage HyperFrames 变量与媒体编排完全指南：把外部输入注入 HTML 合成，并让视频/音频素材按框架契约播放-迪斯科星球

OpenMontage HyperFrames 变量与媒体编排完全指南：把外部输入注入 HTML 合成，并让视频/音频素材按框架契约播放

【免费下载链接】OpenMontageWorld's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.项目地址: https://gitcode.com/GitHub_Trending/op/OpenMontage

HyperFrames 以"HTML 即视频"为哲学：一个index.html通过data-*属性声明时间轴，动画运行时支持确定性 seek，媒体播放权归框架所有。而在真正的生产中，一个合成必须回答两个问题：哪些内容会从 HTML 外部流入（运行时参数）？外部媒体文件（视频/音频）如何被精确驱动？本文基于 OpenMontage 仓库中的.agents/skills/hyperframes-core/references/variables-and-media.md这份核心契约文档展开，系统讲解 HyperFrames 的变量声明、取值、覆盖、严格校验机制，以及<video>/<audio>的"直接宿主根子节点"铁律、时间属性、音量自动化与常见静默错误。读完你将能写出可被lint/validate/render链路可靠消费、可在 Studio 中编辑参数、且不会出现"白板/黑屏"事故的 HyperFrames 合成。

为什么把"变量"和"媒体"放在同一份契约里

原文档开宗明义：这两者本属两件事，却因共同回答了同一个问题而被归为一组——"什么从 HTML 外部流入合成"：

变量（runtime parameters）：控制"数据流"，即合成启动时应读取的运行时参数（标题、强调色、枚举档位等）。
媒体（external media files）：控制"内容流"，即<video>/<audio>这类外部音视频文件如何进入时间轴并被框架驱动。

在 OpenMontage 的完整体系里，这份文档是 hyperframes-core 技能的 12 份参考文档之一（技能总索引见 SKILL.md），与data-attributes.md、tracks-and-clips.md、sub-compositions.md等共同构成"HyperFrames 合成契约"。它被反复强调的原因是：这两块都是lint/validate/inspect抓不到的静默错误高发区——放错位置的媒体会渲染成空白或黑色，读错时机/形状的变量会在 CI 里悄悄产出错误画面。

Variables：在`<html>`上声明合成入参

声明语法（schema 形状）

变量声明在<html>元素的data-composition-variables属性上，每条声明需要且仅需要四个字段：id、type、label、default。

<html >const { title, accent } = window.__hyperframes.getVariables(); document.getElementById("title").textContent = title; document.documentElement.style.setProperty("--accent", accent);

这里有一个关键原则（原文档明确为规则）：在 init 时读取一次，绝不要在动画每一帧（animation tick）里反复读。因为 HyperFrames 是确定性渲染——变量在渲染过程中不会改变，每一帧重新读取既无必要，也可能引入时序不一致。

五种类型与其 UI 选项

变量类型由 Studio 的编辑 UI 消费，各类型可携带的附加选项如下：

类型	可选附加选项	说明
`string`	`placeholder`、`maxLength`	文本输入框的占位提示与最大长度
`number`	`min`、`max`、`step`、`unit`	数值滑杆的范围、步进与单位后缀
`color`	无	颜色选择器
`boolean`	无	开关
`enum`	`options`（必填）	下拉枚举，必须形如`options: [{ "value": "...", "label": "..." }, ...]`

变量使用规则速查

从原文档中可以直接沉淀出以下实战规则：

始终提供有意义的default：这样在没有任何 CLI 覆盖参数时，预览也能直接工作。
子合成按实例覆盖：在子合成宿主（sub-composition host）上使用data-variable-values='{"title":"Pro"}'实现"每个实例一份值"。
渲染时覆盖：npx hyperframes render --variables '{"title":"Q4 Report"}'，或使用--variables-file指向 JSON 文件。
CI 中加--strict-variables：把"未声明的键、类型不匹配、options之外的枚举值"从警告升级为错误——这是防"参数悄悄失效"的防线。
init 一次性读取：变量渲染中途不变，勿在 tick 中读取。
媒体调色可直接引用变量：在data-color-grading的 JSON 内，用$gradingPreset或${gradingIntensity}作为整个字段的值；运行时会在应用 shader 调色前，先从当前合成的变量中解析它。

两种 JSON 形状（极易混淆）

原文档专门强调了这个"文档第一坑"，务必区分：

data-composition-variables是声明数组（schema）：[{id, type, label, default}, ...]
CLI 的--variables与宿主的data-variable-values是以 id 为键的值对象（values）：{ title: "Q4", accent: "#fff" }

一个是"定义有哪些参数"，一个是"给参数填什么值"。混用形状是lint不一定能及时拦住、却会让 Studio 编辑 UI 与 CI 严格校验双双失效的经典错误。这条契约在 HyperFrames 子合成体系里同样成立——.agents/skills/hyperframes-core/references/sub-compositions.md中按实例传值的机制与本文"变量由宿主决定、子合成读取"的边界互相印证。

Media：不可协商的宿主根直接子节点铁律

铁律本身

<video>/<audio>必须是宿主合成根（index.html）的直接子节点。

运行时只会注册并驱动"直接作为根子节点出现"的媒体。以下两种情况媒体永远不会被 seek / 解码，最终渲染为空白（纸白）或黑色：

放在子合成的<template>内部；
被任何中间<div>包裹。

更棘手的是：lint/validate/inspect三个校验命令都抓不到这个问题，只有逐帧snapshot才会看到空白的画面块。因此这是必须在创作期靠纪律守住的约束，而不是靠工具兜底的规则。在 OpenMontage 的 HyperFrames 技能体系里，这条铁律也被写进了 hyperframes-core/SKILL.md 的不可协商规则清单，与"根必须有显式尺寸"等一起被列为"lint 抓不到的静默 bug"。

由此推导的三个直接后果

原文档给出三个必须内化的推论：

场景专属的 clip 依然住在宿主根，而不是场景的子合成里。子合成只保留"画面/外壳（frame/shell）"，真正的媒体是盖在其上的一个宿主级兄弟元素。
子合成无法触达或驱动宿主元素：无论document.querySelector("#host-id")还是 gsap 选择器串（tl.to("#host-id", …)）都跨不过合成边界，子合成时间轴只能驱动自己的子树。因此宿主媒体上所有逐场景的动效（缩放/透明度/形变/倾斜/呼吸感）必须写进index.html的主时间轴，且使用 GLOBAL 时间——即"场景本地时间 + 该场景槽位的data-start"。
没有透视父容器时做 3D 倾斜：使用 gsap 的transformPerspective属性直接作用在元素上。这种"场景媒体放宿主根、运动统一在主时间轴、按全局时间编排"的布局范式即 composition-patterns.md 中记载的 archetype B 形态。

最小可用示例

视频元素必须muted且playsinline；音频即使与视频共用同一个源文件，也必须单独成一个<audio>元素：

<video id="a-roll" class="clip" src="assets/demo.mp4" >tl.to("#bgm", { volume: 0, duration: 1 }, "outro");

原因在于：运行时探测时间轴上的 volume 关键帧，并在预览与渲染中一致地应用；而data-volume只是"没有任何 tween 触碰的元素"的静态基线值。若你既给 tween 又设data-volume，二者语义不同，容易产生"预览正常、渲染不一致"的幻觉。

时长语义

<video>与<audio>的data-duration是可以省略的：当媒体固有长度已知、且你想要整段素材时，可以只靠源文件的真实时长驱动。反之，当需要裁剪（只取片段）或源文件时长不稳定时，必须显式提供data-duration。这一语义与 OpenMontage 管线把edit_decisions.cuts[i].in_seconds / out_seconds翻译为元素上data-start/data-duration的映射规则（见 skills/core/hyperframes.md）完全对齐：叙事层的时间即合成层的时间。

这些规则为什么值得被当作"契约"而不是"建议"

把变量与媒体规则上升为"不可协商契约"，背后是 HyperFrames 的确定性渲染模型：

变量一次性解析，保证同一份合成在任何时刻、任何机器上 seek 到同一帧结果一致；
媒体由框架统一 seek/解码，杜绝合成代码里并发的play()/seek()与抓帧竞争，这是--workers并行抓帧能成立的前提；
跨边界禁令（子合成不驱动宿主、媒体不放子合成内）保证"组装后页面"的 id 唯一性与轨道归属清晰，避免把单个项目的 bug 扩散成跨子合成的耦合。

而校验盲区（lint/validate/inspect抓不到上述两类问题）决定了：这条契约主要由创作端的纪律保障，而不是由校验工具兜底。在 OpenMontage 的落地流程里，最终防线是.agents/skills/hyperframes-core/SKILL.md#L73-L77的验证清单——lint→validate→inspect→ 带子合成的项目做snapshot --at <midpoints>逐帧目检 →preview人工审阅 → 用户批准后才render。其中"逐帧 snapshot 目检"正是捕获"空白媒体块/黑色画面"这类静默 bug 的唯一有效手段。

写作时自检清单

合成本文结论，交付一份可复用的创作前检查表：

变量声明是数组（schema），传入的值是对象（values），勿混用；
变量在 init 时读一次，default必须可用，CI 里开--strict-variables；
每个<video>/<audio>都是宿主根的直接子节点，无中间包装；
音频独立成<audio>，<video>恒muted playsinline；
宿主媒体的动效一律走主时间轴 + 全局时间（场景本地时间 +data-start）；
音量自动化走 timelinevolumekeyframes，data-volume只当静态基线；
显式给足data-duration（除非确定要用整段源素材）；
对外部素材加crossorigin="anonymous"，CI/最终交付前跑一遍逐帧snapshot目检。

变量与媒体是 HyperFrames 合成与"外部世界"之间的唯二通道：把data-*之外的一切输入管好，你的合成才能稳定穿越从 Studio 预览、CI 校验到确定性渲染的整条链路。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析