深入editonny核心：HyperFrames渲染管线与project.json项目契约解析

editonny 是一款本地对话式视频编辑工具，由 Matheus Gomes 创建。你用自然语言描述剪辑需求，它就在你自己的电脑上完成转录、剪辑、字幕、动画与渲染。本文带你深入 editonny 的核心：以project.json为"项目契约"，由HyperFrames 渲染管线驱动的本地视频编辑工作流。

为什么 project.json 是项目的"契约"

在 editonny 中，每个视频项目都由一个project.json文件完整描述。它不是普通的配置文件，而是引擎、构建脚本与渲染器之间的唯一事实来源：改设置、改剪辑、改字幕后，管线都会基于它重新生成合成层。

模板项目契约位于 project.json，顶层字段包括：

几个对新手友好的细节：

• 时间可以锚定到"说出的词"：blocks的start既可以是秒数，也可以是语音词锚点，用after区分重复出现的词——这让剪辑点天然跟着语流走；
• 字幕可局部关闭：captions.enabled控制全局，单个 block 里写captions: false即可局部禁用；
• 风格与画幅都是枚举：paper/night/amber三种风格，四种画幅，避免自由参数带来的渲染不确定。

完整的字段与枚举说明见模板自带的 README.md（Project contract 一节）。

HyperFrames 渲染管线：从契约到成片

editonny 的渲染交给 HyperFrames），编辑期间不应升级，保证渲染结果可复现。

管线输入：edit/ 目录

渲染前，编辑目录会准备好cut.mp4、cut_timeline.json和transcripts/cut.json三个核心文件，可选的face_layout.json、waveform_words.json等还能提升构图与口播词时机精度。

七步构建命令

模板内置的build.py把整条管线封装为几条命令：

1. prepare—— 下载锁定的 GSAP 运行时，用于本地渲染；
2. cut—— 构建带字幕的剪辑版本供审阅；
3. sample START END—— 构建代表性片段，快速验证效果；
4. compose—— 构建完整合成；
5. studio—— 启动本地 Studio 预览服务；
6. hf lint/hf check—— 校验生成的合成结构；
7. hf render --quality draft—— 渲染审阅副本。

💡 新手建议：先用sample渲染 3–5 秒验证场景与字幕，再跑compose+render全量输出，能省下大量等待时间。

hyperframes.json：路径与注册表

hyperframes.json 声明了blocks、components、assets三条资源路径都指向项目内的compositions/与assets/目录，并开启media.autoProxy。这意味着渲染时所有媒体都取自项目本地副本，而不是包内的捆绑视频——每个项目都是自包含的。

校验与保真：不只是"能渲染"

• project_contract.py 负责校验workflowschema 1、确认哈希与产物依赖，防止基于过期设置的旧渲染被当作新结果；
• workspace.py 负责独占的项目创建、独立修订与"不覆盖"的交付发布；
• quality_gate.py 与 fidelity.py 会在渲染后实测帧、色域与音频峰值，遇到不支持的 HDR 叠加等情况会明确拦截而不是悄悄改图。

这套"契约校验 → 构建 → 渲染 → 保真验证"的闭环，是 editonny 与"跑个脚本出视频"最大的区别。

自定义场景：契约驱动的动画层

compositions/scenes/提供了 2D/3D 场景模板。复制一个内置场景、重命名 ID 后，在project.json中注册即可：

{"scenes": [{"file": "compositions/scenes/example.html", "start": 2, "end": 7}]}

构建时，引擎会通过window.__scenes向每个场景注入start、end、words、colors、safeArea等运行时数据——场景本身只需声明结构，时序与配色完全由契约驱动。3D 场景还要求"确定性绘制"：seek 到同一时间点必须产出同一帧，这正是 HyperFrames 可复现渲染的底层要求。

详细的场景开发约定见 compositions/scenes/README.md。

核心模块路径速查

一句话总结：editonny 把"你要什么视频"写进project.json契约，由锁版本的 HyperFrames 管线本地执行，再用契约校验与保真验证兜底——对话式输入、工程化交付，这就是它的核心。