OpenMontage 角色动画流水线 Compose Director：从动作时间线到可交付 final.mp4 的渲染与质量门控实战指南

OpenMontage 角色动画流水线 Compose Director：从动作时间线到可交付 final.mp4 的渲染与质量门控实战指南

【免费下载链接】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

导读

本文聚焦 OpenMontage 开源智能视频生产系统中角色动画（character-animation）流水线的Compose（合成）阶段，系统讲解 compose-director.md 所定义的职责：将上一阶段edit-director产出的edit_decisions与action_timeline兑现为经过评审的最终渲染视频，并交付到projects/<project-name>/renders/final.mp4。读完本文，你将掌握：如何按提案锁定的render_runtime在 Remotion、HyperFrames、FFmpeg 三条渲染路径间正确路由；如何通过character_rig_renderer产出可复现的渲染包、用character_animation_reviewer完成角色级 QA；以及如何用video_compose的final_review做技术探针、抽帧、音画抽查与交付承诺校验，确保没有"静默降级"、没有把未通过的输出当作成品交付。

一、Compose 阶段在流水线中的位置与输入输出契约

在pipeline_defs/character-animation.yaml定义的 11 个阶段中，compose 处于 edit 与 publish 之间，是最后一个产出视频实体的技术阶段：

该阶段在pipeline_defs/character-animation.yaml中声明的评审焦点（review_focus）就是本文的核心脉络：

• 提案阶段选定的 runtime 必须与实际使用的 runtime 一致；
• 浏览器预览在可用时必须通过 Playwright/截图检查；
• 最终 MP4 必须通过 ffprobe、抽帧、角色 QA 与视觉自评；
• 严禁静默降级为"静态图像伪运动"。

三个产出工件分别对应 Schema：render_report.schema.json、final_review.schema.json、character_qa_report.schema.json，Pipeline 后续的 publish 阶段会把这些工件作为必选输入继续传递，因此 compose 产出的工件必须 Schema 合法，否则整个流水线无法继续。

二、Runtime 路由：先从edit_decisions.render_runtime开始

Compose Director 的第一条铁律是：先读edit_decisions.render_runtime。该字段在提案阶段由用户批准锁定，除非decision_log中有一条明确的render_runtime_selection决策改变了它，否则 compose 不得擅自更换引擎。

2.1 三条渲染路径的取舍

从源码看，这一路由契约在 video_compose.py 的模块文档字符串中写得很清楚："Routing is driven byedit_decisions.render_runtime(locked at proposal)"，且"Silent runtime swaps are forbidden by governance"——若所选 runtime 不可用或渲染失败，工具会抛出结构化阻塞（blocker）等待 Agent 重新征询用户，而不是偷偷换引擎。同时，hyperframes_compose.py 明确指出自己是video_compose在render_runtime == "hyperframes"时的委托实现，二者构成一条完整的调用链。

2.2 为什么不能随意降级到 FFmpeg

角色动画的交付承诺通常依赖真实运动（delivery_promise.motion_required: true）。Compose 阶段的评审焦点中有专门一条"No silent downgrade to still-image motion"（禁止静默降级为静态图像伪运动），即用 FFmpeg 的 Ken Burns 缩放平移冒充角色表演是不被允许的。这与 hyperframes.md 中"运动必需类交付的 runtime 是承诺而非提示"的硬性规则一脉相承。如果 Remotion 未安装、npx hyperframes doctor报告阻塞，正确的做法是按 AGENT_GUIDE.md 的"显式升级阻塞"协议处理，等待用户批准后再切换 runtime。

三、评审工作流：五步把"通过评审的渲染"落到实处

3.1 第 1 步：用character_rig_renderer产出或刷新渲染包

运行 character_rig_renderer（tools/character/character_animation.py中的CharacterRigRenderer类）生成 HyperFrames 渲染包。这一步会同时写出：

• 浏览器预览 HTML：把action_timeline序列化为window.__ACTION_TIMELINE__注入页面，用 GSAP 驱动角色眨眼、转头、摆臂等循环动画。注意：文档明确它是"QA/debug 产物，不是正式渲染路径"；
• HyperFrames 工作区：默认落在output_path.parent / "hyperframes"下，包含hyperframes.json（CLI 配置）、DESIGN.md（视觉说明）、compositions/character-scene.html（带data-composition-id的注册表块模板）；
• asset_manifest与edit_decisions：返回preview_path、hyperframes_workspace、composition_path、asset_manifest、edit_decisions等字段，其中edit_decisions.render_runtime固定为"hyperframes"，作为交付给video_compose的交接证据。

从源码看，CharacterRigRenderer的输入 Schema 要求action_timeline必填，其余rig_plan、pose_library、output_path、workspace_path、video_output_path、render_video、duration_seconds（默认 3）、fps（默认 12）可选；输出通过asset_manifest记录资产来源与成本（本地渲染成本为 0 美元），并通过edit_decisions.metadata.proposal_render_runtime保留提案期的 runtime，方便final_review做运行时切换检测。

3.2 第 2 步：核验渲染器交接产物

Compose Director 必须在继续前确认渲染器确实产出了四样东西：

1. 一个 HyperFramesworkspace_path；
2. 一份 composition HTML（compositions/character-scene.html）；
3. 一份asset_manifest；
4. 一份edit_decisions.render_runtime: "hyperframes"的交接记录。

这四者缺一不可——它们是"渲染路径可复现、可审计"的凭证，也是后续video_compose自动解析资产 ID 的依据（render操作会通过asset_manifest把cuts[].source解析为文件路径）。

3.3 第 3 步：运行character_animation_reviewer做角色级 QA

对 rig、poses、timeline 与 preview 执行 character_animation_reviewer（CharacterAnimationReviewer类）。该工具产出character_qa_report，其 Schema（character_qa_report.schema.json）规定了核心检查项：

status取值pass / revise / fail；存在任一 issue 即为revise。工具的review_level参数支持static / browser / final三档：browser与final强制要求browser_preview_checked，final还强制要求frame_samples_checked，缺少即追加 issue。其元数据中明确提示"static artifact review; run Playwright/FFmpeg checks in compose for final output"，说明角色 QA 与最终视频的 Playwright/FFmpeg 检查是互补的两道闸门。

3.4 第 4 步：通过video_compose渲染最终视频

使用渲染器的交接产物（或经批准的 Remotion/HyperFrames 包）调用video_compose的render操作。工具会依据edit_decisions.render_runtime自动路由：

• remotion→ React 逐帧精确渲染（npx remotion render）；
• hyperframes→ 委托hyperframes_compose物化工作区并执行lint → validate → render；
• ffmpeg→ 仅简单拼接/裁剪。

交付路径约定：最终成品必须落在projects/<project-name>/renders/final.mp4，这是 OpenMontage 的标准项目约定，publish 阶段会按此路径取用。

HyperFrames 路径的验证协议值得单独强调（详见 hyperframes.md 的 Validation protocol 与 hyperframes_compose.py）：

1. npx hyperframes lint——静态契约检查（重复 id、轨道重叠、缺失data-composition-id、未注册时间线），渲染前必须通过；
2. npx hyperframes validate——基于浏览器的运行时检查：seek 暂停合成、截图、像素采样、计算 WCAG 对比度、验证window.__timelines注册与class="clip"，渲染前必须通过（迭代期可--no-contrast跳过对比度，最终渲染不可跳过）；
3. npx hyperframes render --quality standard——产出 MP4；
4. 渲染后最终评审——与 Remotion 路径同一套final_review契约。

前置条件方面，hyperframes_compose依赖npx与ffmpeg，要求 Node.js ≥ 22、npx hyperframes doctor通过；注意 npm 包名为hyperframes，npx @hyperframes/cli会 404。

3.5 第 5 步：运行标准final_review

对成品执行标准最终评审，video_compose的render流程会生成final_review工件（final_review.schema.json），涵盖五个维度的检查：

final_review.status若为revise或fail，绝不能把视频当作完成品交付。这一点同时被 reviewer.md 强制：compose 阶段若缺少final_review或final_review.status != "pass"，publish 评审会直接判为 CRITICAL 级问题，final_review.checks.promise_preservation.runtime_swap_detected必须为false。

四、浏览器 QA：Playwright 可用与不可用两条路径

4.1 Playwright 可用时

按文档执行五步浏览器检查：

1. 打开预览（preview.html）；
2. 捕获开头 / 中间 / 结尾三组帧；
3. 检查控制台报错；
4. 验证角色可见；
5. 比较帧间差异确认运动确实存在。

从源码看，CharacterRigRenderer._render_preview_mp4正是这一思路的实现：用 Playwright 启动 Chromium，以 1280×720 视口打开preview_path，按fps间隔逐帧截图，再用 ffmpeg 把帧序列以yuv420p编码成预览 MP4——这解释了为何character_animation_reviewer的final评审级别要求browser_preview_checked与frame_samples_checked同时为 true。

4.2 Playwright 不可用时

退化为静态工件检查（检查预览 HTML 存在、window.__ACTION_TIMELINE__注入、角色元素渲染）加 FFmpeg 抽帧比对，并在最终交付说明中如实报告"置信度降低"。这是诚实工程的一部分：不能因为没有浏览器就谎称完成了视觉验证。

五、质量门：什么情况下绝不交付

文档最后一节定义了清晰的收尾准则，结合 Schema 可以归纳为两条硬性闸门：

1. 角色 QA 闸门：character_qa_report.status为revise或fail时，不得将输出呈现为完成品（character_qa_report.schema.json 中status枚举即pass/revise/fail，recommended_action在非 pass 时指向fix_rig/fix_assets/fix_timeline/block）；
2. 最终评审闸门：final_review.status != "pass"时不得交付（final_review.schema.json 的recommended_action指向re_render/revise_edit/revise_assets/re_author/block）。

同时，compose 阶段还必须守住"运行时一致性"红线：edit_decisions.render_runtime必须与提案锁定值一致；任何 runtime 变更都必须先有一条经过用户批准的render_runtime_selection决策记录在decision_log中。两条闸门全部放行后，projects/<project-name>/renders/final.mp4才允许进入 publish 阶段。

六、进阶：HyperFrames 实战避坑要点

由于角色动画流水线以 HyperFrames 作为主要本地渲染路径（character_rig_renderer默认产出 HyperFrames 工作区），Compose Director 在实践中还会遇到 hyperframes.md 记录的硬经验，直接决定渲染成败：

• 素材分辨率陷阱：许多免费素材库的"大尺寸"视频实际只有 640×360。若预处理用 scale-to-fit + pad，会得到"黑边里的小画面"。正确做法是 scale-to-cover + crop，例如-vf "scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,unsharp=3:3:0.6"；
• 渲染前必须预览拖拽检查：60 分钟的渲染成本极高，正式渲染前用npx hyperframes preview对每章至少一个 b-roll 主导场景做视觉检查，2 秒的预览检查能省下 60 分钟的回归成本；
• 素材关键帧密度：关键帧间隔 > 5s 的素材会导致video_heavy_parallel_timeout或帧冻结，入库前统一重编码（-c:v libx264 -r 30 -g 30 -keyint_min 30 -sc_threshold 0 -movflags +faststart）；
• 视频密集型合成用--workers 1：超过 5 个背景视频元素时，默认并行捕获会压垮 headless Chrome；
• 字体选择：确定性字体编译器只内联有映射的字体，Space Grotesk会被回退成 Arial，优先使用Outfit、Inter、JetBrains Mono等；
• GSAP 纪律：时间线内禁止repeat: -1（无限补间破坏确定性 seek-and-capture 渲染），禁止在async上下文 /setTimeout/ Promise 中构建动画——window.__timelines必须在页面加载后同步完全填充。

从 hyperframes.md 的 Pipelines adopting HyperFrames 表可见，character-animation属于 Wave 1 之外但共享同一运行时桥接能力的路径，Compose Director 需要理解这些底层约束才能真正把"渲染包 → final.mp4"跑通。

结语

Compose Director 的本质是一道"可审计的渲染闸门"：从edit_decisions.render_runtime的路由裁决，到character_rig_renderer的确定性渲染包，再到character_animation_reviewer的角色 QA 与video_compose的final_review五维自检，每一步都产出 Schema 合法、可追溯的工件。任何一步出现revise/fail，成品都不得视为完成。这套"工具产出 + 多级评审 + 承诺校验"的模式，正是 OpenMontage 用本地确定性渲染替代远程视频生成、把角色动画做成可复现工程的关键所在。

【免费下载链接】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