# Video Assemble

合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录，...

- Repository: https://github.com/zenstory-ai/oh-story-dsh (665 stars)
- Category: Media
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add zenstory-ai/oh-story-dsh --skill video-assemble -g -a claude-code -y`
Codex: `npx skills add zenstory-ai/oh-story-dsh --skill video-assemble -g -a codex -y`
Cursor: `npx skills add zenstory-ai/oh-story-dsh --skill video-assemble -g -a cursor -y`
Gemini CLI: `npx skills add zenstory-ai/oh-story-dsh --skill video-assemble -g -a gemini-cli -y`

## Description

合成视频解说最终成片：把旁白音频铺到源视频上，按旁白窗口压低原声，生成 SRT / ASS 字幕并可烧录， 最后做响度标准化。作为最终合成阶段使用。输入源视频、tts_meta.json 与旁白位置； 输出 recap 成片和字幕。触发词：视频合成、混音、字幕、压字幕、assemble video、mux、ducking、subtitles、成片。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## 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. 运行命令

The rest: https://github.com/zenstory-ai/oh-story-dsh/blob/HEAD/packages/knowledge/video-recap/skills/video-assemble/SKILL.md