video-assemble

1. 定位

本技能负责最终合成：

1. 把各段旁白音频放到视频时间线上。
2. 在旁白窗口内用固定包络压低原声（盖住原声对白时与落在安静段时各用一档音量），间隙恢复原声。
3. 根据旁白位置生成 subtitles.srt；默认同时生成并烧录 subtitles.ass，--no-burn-subtitles 可关闭。不烧录时（关闭或降级），subtitles.srt 复制到成片旁，名为 recap_<stem>.srt；烧录时删掉旧的同名外挂字幕。
4. 可选把最终响度标准化到目标 LUFS：两遍 loudnorm，只用一个恒定增益，不做动态压缩；混音的真峰值放不下这么大的增益时，先过 4 倍过采样的真峰值限幅器（最多削 LOUDNESS_LIMITER_MAX_DB，默认 6 dB），超出部分才下调目标响度。真峰值目标针对交付的 AAC 文件：AAC 编码会让真峰值比 PCM 混音高 0.3–1.4 dB，所以首次渲染瞄准 TP 下 0.5 dB，渲染后解码成片实测；仍超过 -1 dBTP 时按超出量再降 0.1 dB 只重编码音频（画面流复制），最多两次，仍超出则以 delivered_true_peak_over_target 阻断。ffmpeg 实际用的模式、限幅量与成片实测值记在 assembly_qc.json 的 loudness_mode 与 loudnorm_final_pass（delivered）。
5. 成片不带原片的容器元数据（title、comment 等标签与章节）。

2. 声音收尾契约

合成阶段只实现创作决定，不凭空制造决定。Agent 在写旁白位置前，已在 visual_audio_board.json 为每个 beat 指定 audio_owner：

• original_dialogue
• action_sound
• ambience / music
• silence
• narration

旁白间隙按已选声音分工保留。只在确有任务时加入 BGM，并保住必须听见的台词与有意义的沉默。

当前渲染器不解析 visual_audio_board.json；Agent 通过旁白时间、overlaps_speech、原声留白与现有混音参数落实这些决定。

3. 输入契约

• <video>：源视频；cut 模式下为 edited_source.mp4。
• work_dir/tts_meta.json：默认 narration 模式必需；配音阶段写出的 {segments: [...]}。每段包含 audio_path、时间、pause_after_ms、overlaps_speech 和用于混音/字幕的位置。显式 source-mix / adopted-packet-copy 模式不读取它。
• 已采用的配音使用显式 --tts-meta 和 --narration-adoption：后者由调用方独立确认文字、请求的引擎/声线和速度策略，不能从待消费元数据自动“批准”出来。完整格式与记录边界见 references/narration-adoption.md。
• 已采用的完整声音底轨与逐段配音可再传 --audio-mix-adoption；严格格式、48 kHz 声道矩阵和双 binding 事务见 references/explicit-audio-mix.md。

下面的 scripts/... 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。

4. 运行命令

python3 scripts/assemble.py <video> --work-dir <work_dir> \
  [--audio-mode narration|source-mix|adopted-packet-copy] [--audio-stream-index <N>] \
  [--tts-meta <tts_meta.json> --narration-adoption <narration_adoption.json>] \
  [--audio-mix-adoption <audio_mix_adoption.json>] \
  [--recap-stem <name>] [--output-dir <dir>] [--no-burn-subtitles] \
  [--subtitle-y-top <inclusive-y> --subtitle-y-bot <exclusive-y>] \
  [--source-video <orig.mp4>] [--export-jianying [--jianying-out <dir>]]