video-producer, 工具说明

本文是 expert-video 专家包内的工具说明书，不独立出现在技能列表中。制作流程（阶段链、两闸门、workflow 选择）由包内 SKILL.md 与 workflows/ 编排，本文只写每个子命令的输入、输出与调用方式。

调用方式：video-producer <子命令> [参数...]（wrapper 转发到 scripts/<子命令>.py，子命令名即脚本名，零路径拼接）。video-producer help 列可用子命令。

通用约定：

• 多数子命令第一个位置参数是 <project_dir>（工作区目录），产物落该目录下约定子路径。
• 产物文件存在性即 checkpoint：子命令先查产物文件是否存在，存在则 load 不重生成（允许手改 JSON 后续跑）。
• 退出码：0 成功 / 1 参数错 / 2 env 未配（如 AWK_API_KEY、VOLC_ASR_*）。

按阶段与任务使用

Stage 1, 9：脚本、分镜与素材计划

script-write / script-self-eval 先按 Brief 的类型 workflow 生成脚本与自检；Stage 3, 9 继续调用同名阶段命令，产物文件落盘后仍须由 agent 填实。GATE A 在 Stage 5 后，GATE B 在 Stage 9 后；脚手架本身不代表闸门已获批准。

deck-talk 的 Stage 1 输出 script/deck-script.md；Stage 3, 9 记录逐页/段分镜、画面状态、人物和声音来源、素材、风险及承诺。collage-broll 的 Stage 1 是隐喻清单；Stage 3, 9 登记纸片分镜、独立素材层、预览风险及逐层动作承诺。通用形态和 reversal-ad 使用清单中的标准产物；类型字段与验收口径读对应 workflows/*.md。

Stage 10：画面渲染

render-shot 建立逐镜渲染计划；常规 HTML/GSAP 动效用 visual-render scaffold/check/preview/render 调共用 HyperFrames 运行时。新项目的 motion-graphics 会转交 visual-render，旧 JSON/Pillow spec 仅供兼容；特殊生成式镜头才用 batch-i2v。Deck Talk 的计划落 render/deck-render-plan.json，纸拼贴落 render/collage-render-plan.json；计划文件不是已渲染的媒体。

Stage 11：声音与时间戳

mix-audio 根据 Brief 和脚本核定音轨；整段旁白用 narration-align，逐句旁白用 narration-layout。Deck Talk 的计划落 audio/deck-audio-plan.json，纸拼贴落 audio/collage-audio-plan.json。用户或 main 提供的原声保持锁定；无声纸拼贴必须明确记录 sound_policy=silent。

Stage 12：切段、混音与合成

clip-trim、audio-mix、timeline-compose、scene-compose、assemble 负责按时间轴切段与组装。deck-compose 是 Deck Talk 三模式的入口，内部用 pip-compose 合成小窗与唯一音轨。纸拼贴单条交付时，用 assemble --manifest 交接一个已渲染片段，保留其原音轨状态；批量逐条执行。

多段无声硬拼使用 assemble <project> --manifest render/segments.json --video-only --expect-frames <总帧数> --verify-fps <实际fps> --output video-silent.mp4。输入须同尺寸、恒定帧率且编码参数兼容；自动剥离段音轨，按视频流实测时长/帧数拼接，校验成片逐帧 PTS 与递增 DTS。混合编码或 B 帧延迟不兼容时报错，只有明确允许统一编码时才加 --video-only-reencode，串行低载处理。输入顺序、内容、参数和输出哈希落 .mp4.assemble.json；与已有输出不符时另存新版，不因帧数相同复用旧片。