Appearance
HyperFrames：素材、二次编辑与透明包装轨道
HyperFrames 适合制作字幕条、角标、片头、动态图表、3D 产品动画等视频包装，再与主视频组合。 它以 HTML composition + CSS / JavaScript + 素材文件描述画面，通过浏览器逐帧渲染、FFmpeg 编码与混音输出视频。JSON 可以提供配置、变量和资源描述，但不是与任意视频草稿通用的工程格式。
本文的 Hyperframe 指 HeyGen 的开源项目 HyperFrames。 核对日期：2026-09-30；依据官方仓库 快照 efd3c51ac9b7， 该快照的 CLI / Producer 包版本字段为 0.8.94。以下“上游支持”来自文档与源码审阅， 本次未运行 HyperFrames 渲染，也不将主分支版本字段当作 npm 发布状态证明。
当前集成状态
本仓库是基于 React、Mediabunny、WebCodecs、PixiJS 等开源技术构建的编辑学习 Demo， 目前未依赖或接入 HyperFrames。本文提供能力说明与接入设计；现有编辑器尚不具备 HyperFrames 工程导入、草稿转换或透明包装轨道的完整链路。
能力速查
| 问题 | 上游能力及适用条件 | 对本项目的含义 |
|---|---|---|
| 源文件是 HTML 还是 JSON？ | 画面与时序的主要源文件是 HTML；JSON 用于配置、变量等辅助数据 | 保存完整工程目录，不能只保留导出视频或一个 JSON |
| audio / video 能作为素材吗？ | 支持 HTML 音视频元素、入点、时长、速率、音量与混音 | 可以把其他草稿先渲染为视频，再放进 composition |
| 字体、CSS、JS 能一起使用吗？ | 支持网页字体、样式和脚本；动画必须可按时间求值 | 字体与依赖需要随工程固定，避免换机器后失效 |
| Three.js / WebGL 呢？ | 有 three 时间适配器，也有 WebGL 特效实现 | 3D 场景作者负责按指定时间更新与绘制 |
| WebGPU 呢？ | 有 TypeGPU / 原生 WebGPU 适配器 | 依赖实际渲染环境的 GPU、浏览器和异步完成同步 |
| 可以二次编辑吗？ | 源码、Studio 支持的画布/时间线操作、模板变量均可修改 | 任意 JS 内部状态不会自动变成可视化编辑参数 |
| 可以导出透明视频吗？ | 已支持 WebM VP9、MOV ProRes 4444，以及透明 PNG 序列 | 本项目还需接入、验证透明解码、代理、合成与输出 |
工程文件与可编辑性的边界
一个可交接的工程可以按下面的方式组织；styles/、scripts/ 是组织建议，不是必需目录：
text
overlay-project/
index.html 主 composition：布局、时间与素材引用
hyperframes.json CLI 资源库和目录配置
compositions/ 可复用的子 composition
lower-third.html
assets/ 视频、音频、图片、字体、模型、纹理
styles/ CSS（可选，也可内联）
scripts/ JS / 模块（可选，也可内联）
variables.json 模板参数输入（可选，自定义文件名）hyperframes.json 的官方用途包括 registry 与 blocks/components/assets 路径配置， 不是完整时间线草稿。变量 JSON 可以通过 --variables-file 传入；composition 需要声明 变量并将它们绑定到 DOM、样式或脚本。Lottie JSON 是另一类动画资源，也不等于整个工程。 参见官方 composition 概念、 CLI 配置和 变量机制。
二次编辑应保留 HTML、样式、脚本、原始素材、字体、参数、依赖版本与输出规格。 Studio 对支持的布局、文字、媒体、时序和动画操作回写同一份项目文件；复杂 shader、 自定义 JS 或程序化 3D 结构仍需源码编辑。导出的 MP4/WebM/MOV 已经是像素与声音， 不会携带可恢复的文字图层、关键帧或 Three.js 场景树。 参见官方 源码与 Studio 编辑说明。
支持哪些素材与 Web 能力
这里的“支持”表示有接入方式，不代表所有扩展名、编码组合和运行环境均已通过验证。
| 类型 | 使用方式与能力 | 生产使用约束 |
|---|---|---|
| 静态图片 / SVG | <img>、内联 SVG、CSS 背景；适合 Logo、图标、贴纸 | 保留透明图片原始 alpha；动图需要另行核对逐帧时序 |
| Video | <video src="…">；官方 Studio 接受 MP4、WebM、MOV | 容器不等于编码；预览解码与 FFmpeg 渲染都要验证。MOV 不代表浏览器能原生播放任意 ProRes |
| Audio | <audio src="…">，以及视频中的源音频；用于配音、音乐、音效 | MP3/WAV 等常用音频仍需在目标环境检查；不要把任意 Web Audio 实时输出视作自动导出音轨 |
| Font | @font-face 加载字体文件，例如 WOFF2 / TTF | 字体随工程交付，检查中文字形覆盖；布局测量和捕获须等待字体加载完成 |
| CSS | 布局、渐变、遮罩、滤镜、变换及受运行时控制的 CSS 动画 | 受 Chromium CSS 实现影响；必须检查最终分辨率与导出画面 |
| JavaScript | 脚本、ES module、GSAP 等；可生成 DOM / Canvas / SVG | 固定依赖版本、初始数据和随机种子，加载完成后再捕获 |
| Lottie | Lottie 动画及其 JSON / 图片资源，通过适配器求值 | 保留关联资源，验证选定 Lottie renderer 与效果支持 |
| Three.js / WebGL | Three 场景、相机、模型、材质、shader；three 适配器提供时间 | Three.js 需自行加载；GLTF、纹理等由相应 loader 处理，框架不会自动把模型变成编辑器轨道 |
| TypeGPU / WebGPU | WGSL、计算与渲染管线；typegpu 适配器提供时间和完成屏障 | 需要可用 GPU adapter；预览能运行不代表 headless / Docker 环境可用 |
依据：官方 媒体指南、 图片与视频、 音频指南、 帧适配器，以及 字体处理说明。
媒体时间与合成时间
HTML 的 data-start、data-duration 描述片段在时间线上的位置；媒体源入点使用 data-media-start。例如把另一份草稿的成片第 4–10 秒放到本 composition 第 2–8 秒：
html
<!-- 放在已有 composition 内；片段静音，配音交给单独音频层 -->
<video
class="clip"
src="assets/other-draft.mp4"
data-start="2"
data-duration="6"
data-media-start="4"
data-track-index="0"
muted
playsinline
></video>
<audio
src="assets/voice.wav"
data-start="2"
data-duration="6"
data-media-start="0"
data-volume="1"
></audio>这是结构示例，不是已渲染样片。实际工程还需设置 composition 尺寸、总时长与布局。 上游当前不同读路径对 data-playback-start / data-media-start 的处理有差异： 视频、音频使用 data-media-start，嵌套 composition 使用 data-playback-start， 以免发生画面裁剪而音频仍从源文件开头播放的问题。不要用脚本同时控制媒体播放头， 应让运行时根据声明的时序驱动。参见官方 HTML 媒体契约。
Three.js / WebGPU 的关键是可 Seek
逐帧导出要能回答“时间 t 的画面是什么”，不能依赖页面运行了多久。 Three.js 可在 hf-seek 中使用 event.detail.time 设置旋转、相机或 mixer.setTime(t)， 然后主动绘制。WebGPU 提交命令后，还需同步注册 event.detail.waitUntil(device.queue.onSubmittedWorkDone())，让捕获等待 GPU 工作完成。 Three / TypeGPU composition 应显式声明 data-duration；不能假设框架能推断任意脚本的时长。
避免用 Date.now()、未固定种子的随机数、每帧累加速度或自由运行的动画循环决定导出状态。 粒子模拟、物理、时间累积后处理若依赖历史帧，需要确定性重放或缓存策略，不能直接从任意 t 读取相同结果。模型、纹理、字体和 shader 初始化完成后才能开始捕获。
WebGPU 必须检测 navigator.gpu 和实际 adapter；必需 WebGPU 的 composition 可声明 data-requires-webgpu，使不满足条件的渲染明确失败。WebGPU 与实验性 HTML-in-Canvas 组合有额外浏览器要求，应独立验证。CLI 的 --browser-gpu 控制浏览器 GPU， --gpu 控制 FFmpeg 硬件编码，两者不是同一个开关。
依据：上游 Three.js 适配说明、 WebGPU 适配说明和 确定性渲染。
与其他视频草稿如何互通
| 路径 | 可以继续编辑什么 | 需要付出的代价 |
|---|---|---|
| 保留或嵌套 HyperFrames 源工程 | 原 HTML、文字、布局、动画代码、变量与素材 | 管理子 composition、依赖、资源路径和局部时间 |
| 将其他草稿转换为 HyperFrames | 转换器覆盖的轨道、入出点、位置、文字与效果 | 必须编写草稿 schema → HTML / 动画的转换器，逐项处理不支持的语义 |
其他草稿先导出视频，再作为 <video> 导入 | 整段裁剪、变速、位置、透明度、叠加包装 | 原草稿内部图层已经合并，不能恢复为可编辑对象 |
| HyperFrames 导出为一层素材轨道 | 本编辑器中的片段时间、变换、合成与音量 | 改包装内文字或动画时，返回源工程修改并重新渲染 |
剪映 / Premiere / After Effects / 本项目 Project JSON 等工程并不会因为“也是 JSON 或有时间线” 而自动互通。本次核对未发现通用的任意 NLE 草稿导入契约，应按目标格式开发转换器。 转换时至少明确时间单位（本项目使用微秒）、帧率、源入点、速率、轨道顺序、裁剪、锚点、 字体和混音；无法映射的转场或特效应给出损失报告，必要时将该段预渲染。
建议本项目先采用“保留源工程 + 预渲染包装轨道”的方式：
轨道素材建议记录源工程位置、入口 HTML、参数快照、内容 hash、渲染器版本、尺寸、帧率、 时长及 alpha 约定。这些是本项目拟新增的元数据，不是现有 schema 或 HyperFrames 通用草稿标准。重新渲染后替换素材引用，保留轨道位置与外层变换；时长变化需重新核对裁剪边界。
渲染可运行在独立的本地服务或服务端 Worker 进程中；Producer 依赖 Node、Chrome / Chromium 和 FFmpeg，并非可以直接塞进当前浏览器 Media Worker 的纯前端库。
透明背景输出：上游已具备能力
透明导出保存的是逐像素 alpha，适合字幕条、Logo 动效、粒子或装饰包装。 将轨道整体 opacity 调低、输出黑背景或把文件后缀改成 .webm 都不等价于保留 alpha。
| 交付格式 | 上游编码 / 像素格式 | 透明与声音 | 适合的用途 |
|---|---|---|---|
| MP4 | 常规 H.264 yuv420p；另有 HDR 路径 | 该导出路径不保留 alpha；AAC | 包装与主视频合成后的最终成片 |
| WebM | VP9 yuva420p | 连续 alpha；Opus | Web 包装视频；仍需验证接收端透明解码 |
| MOV | ProRes 4444 yuva444p10le | 连续 alpha；AAC | 专业剪辑软件的中间素材；通常体积较大 |
| PNG 序列 | RGBA PNG | 无损 alpha；音频另存旁路文件 | alpha 验证基准、后期处理、逐帧合成 |
上游另有 GIF / HLS 输出；GIF 只有二值透明，无法保留柔和半透明边缘；当前 HLS 路径不保留 alpha。 ProRes 的编码像素格式不表示网页捕获凭空获得了高位深画面信息。 PNG 序列不是单个视频文件，交接时必须携带帧率、帧序号与音频；README 与源码中的音频旁路 文件名描述存在差异，接入应以实际运行结果为准，不硬编码文件名。
依据：Producer 透明输出说明、 编码实现及 RenderConfig 契约。
导出操作示例
以下命令在已经准备好的 HyperFrames 工程目录执行，需要对应 CLI、Chromium 和 FFmpeg。 本仓库没有安装这些依赖；示例根据上述快照核对，尚未在本机执行。实际接入时应锁定并验证所用版本。
bash
npx hyperframes lint
npx hyperframes check
npx hyperframes render --format webm --output renders/overlay.webm
npx hyperframes render --format mov --output renders/overlay.mov
npx hyperframes render --format png-sequence --output renders/overlay-frames也可通过 Producer 的 createRenderJob({ inputPath, outputPath, format: "webm", ... }) 和 executeRenderJob(job) 集成渲染任务。应显式传递 format，不要仅依赖扩展名。 官方 CLI 渲染参数与 Studio 导出面板给出了两种操作入口。
画面透明需要满足的条件
- 场景没有被填满。 上游透明捕获会覆盖
html、body、[data-composition-id]的背景， 但内部铺满画面的 div、图片或视频仍会遮住背景。需要保留的卡片底色应放在内部元素上。 - Canvas 自身保留透明。 Three.js 使用允许 alpha 的 renderer，并清屏为透明； WebGPU 需要透明的 canvas 配置、清屏 alpha 和正确的预乘约定。仅改 CSS 无法消除 canvas 内的黑底。
- 中间处理保留 RGBA。 截图、滤镜、shader、合成、缓存和编码都不能提前填底或丢弃 alpha。 HDR + alpha 在该上游路径不受支持，会回退 SDR；Linux 的 BeginFrame 路径不保留 alpha， 上游为透明输出选择其他捕获路径，不能套用普通 MP4 的性能结论。
- 接收端也读得出 alpha。 Safari 的 WebM alpha 支持不完整；ProRes MOV 主要面向后期软件。
<video>能播放不意味着 Mediabunny / WebCodecs 的同一路径也能取出透明帧，必须实测。
背景覆盖的实际选择器见 透明截图实现。
本编辑器接入时需要补齐什么
现有 多轨道编辑和原素材导出 已经提供轨道顺序与外层变换，但有以下明确限制：
| 环节 | 当前源码事实 | 透明包装轨道需要的改造 |
|---|---|---|
| 工程描述 | Track 只有 video / audio / text；无 HyperFrames 源工程关联字段 | 扩展 Asset 元数据；是否新增轨道类型由编辑语义决定，预渲染素材可沿用视频轨 |
| 导入 / 解码 | 主测试集为 H.264/AAC MP4，没有完整的透明导入验证 | 探测格式、编码与 alpha；验证真实解码像素，失败时提供转码或 PNG 路径 |
| 预览代理 | 代理使用 AVC，且配置 alpha: "discard" | 为透明素材提供保留 alpha 的代理，或在可承受时跳过代理 |
| 合成 | 导出每帧先填充工程背景色，再按顺序绘制 | 导出单独包装时清成透明，保留半透明边缘；最终成片仍可填底 |
| 输出 | H.264 编码配置 alpha: "discard"，封装 MP4 | 包装素材输出接入独立 alpha 渲染服务或 RGBA 帧管线 |
导入透明包装并合成为普通 MP4，与从本编辑器导出独立透明包装是两个不同验收目标。 前者只需在最终合成前保留透明；后者要求直到最终编码和封装都保留 alpha。 把现有 H.264 配置改为 alpha: "keep" 并不足以实现后者。
推荐分阶段接入，以下均为待实现方案：
- 保存 HyperFrames 工程与参数，通过独立 Producer 渲染出透明包装资产，并先以 PNG 序列验证像素。
- 打通一个目标格式的导入、透明解码、预览与原素材合成；当前 AVC 代理不得作为透明素材的替代源。
- 支持“修改源工程 → 重新渲染 → 替换轨道素材”；缓存按工程、资源、参数与输出规格共同失效。
- 再增加本编辑器的独立透明轨道导出预设，以及更深的草稿转换 / 在线参数编辑。
对应本地证据： Project schema、 代理编码、 导出填底与编码。
透明包装的验收方法
不能仅用“能播放”或文件 metadata 判断成功。建议使用一个包含不透明色块、半透明阴影、 透明空白区和文字边缘的短片，并分别在黑、白、彩色背景上合成：
| 验收对象 | 通过条件 |
|---|---|
| 像素 alpha | 空白处为 0，实心处为最大值，阴影 / 边缘存在中间值；解码后仍成立 |
| 边缘颜色 | 无明显黑边、白边、错误预乘造成的光晕 |
| Seek 与同步 | 首尾、随机时间点、倒序 Seek 与连续渲染画面一致，音频入点一致 |
| 预览与导出 | 代理和原素材切换后透明效果不变，最终合成仍能看到底层主视频 |
| 环境 | 在实际本地 / 容器 / GPU 环境和目标接收软件中分别验证 |
WebM 检查可参考上游测试，显式选择能读 VP9 alpha 的 FFmpeg 解码器：
bash
# 在生成 overlay.webm 后执行；FFmpeg 需包含 libvpx-vp9 解码器
ffmpeg -c:v libvpx-vp9 -i renders/overlay.webm -frames:v 1 -pix_fmt rgba -update 1 renders/alpha-check.png随后检查 PNG 的实际 alpha 像素。只看到 alpha_mode=1 元数据不够；默认解码器也可能在 读取时丢弃 alpha，导致错误地认为原视频不透明。完整接入应覆盖多个时间点与半透明像素， 上游 透明回归测试 提供了透明区和不透明区像素断言的参考。以上为验收设计，尚不是本项目已通过的测试结果。