Video Assemble

What the source does

• FilesystemDeclared2 observations
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

digest = hashlib.md5(usedforsecurity=False)

Audit 0.4.1 · source sha 1d6e8d561898 · 20 Oct 2026Report an issue or request a re-scan

• Publisherworldwonderer GitHub organizationOwner of the repository this skill is read from
• Source folderworldwonderer/video-recap-skills/skills/video-assembleThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict1d6e8d561898A new audit runs when the source changes
• Repository statusNot archivedLast push 4 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

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

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

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

```bash
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>]]
```

## 5. 输出契约

- `recap_<stem>.mp4`:稳定的最终输出别名;每次运行覆盖更新。
- `work_dir/output.mp4`:工作目录内成片。
- `subtitles.srt`:旁白字幕;烧录时另有 `subtitles.ass`。
- `timeline.json`:后端无关的多轨模型,包含视频、原声、旁白、BGM、字幕和 ducking 自动化。
- `_placed_*.wav`:实际写入主混音的完整逐段旁白 PCM;时间线与剪映只引用这些文件。
- `narration_input_binding.json`:旁白输入、转换、实际放置、旁白总轨和最终音轨的消费记录(路径、PCM 参数、packet 计数)。区分未采用与已绑定采用决定两种状态;不等于声线鉴定或听审。
- `audio_mix_binding.json`:显式完整声音分支消费的画面时钟、底轨、48 kHz 配音放置、premaster、固定 master gain、最终 PCM/AAC 事实与 narration binding 路径的记录。
- `assembly_manifest.json`:输入来源、cut 来源标识(路径、大小、mtime)、渲染设置与最终输出路径。
- `assembly_qc.json`:旁白完整性、原声句末交接、时间线素材时长与交付质量的发布门禁。
- 剪映草稿目录:仅 `--export-jianying` 时生成,包含 `draft_content.json`、`draft_info.json` 与 `draft_meta_info.json`。

## 6. 合成规则

- 音频模式的处理与冻结语义见 `references/audio-modes.md`。默认仍为 `narration`;另外两种模式必须显式选择。
- `--audio-mix-adoption` 只与显式 `--tts-meta`、`--narration-adoption` 同时使用;它保留 `narration` 模式名,但跳过旧速度/适配、原声 handoff、环境 BGM、duck、loudnorm 和 limiter。
- 音频按轨道混合:原声、可选 BGM 与旁白各自独立。
- 段落首块(与上一块作者留白超过 1.6 秒)从写的 `start` 放置,但不早于上一块实际结尾加它的 `pause_after_ms`,上一块超时会把它往后推;段落内后续块紧接上一块的实际结尾(间隔 0.35 秒),最多比写的 `start` 提前 1.2 秒。这一提前发生在旁白校验之后,所以提前的那一段不能进入原声对白:有对白时最多提前到最后一段对白结束处。真的提前了的块在 `source_entry_status` 记 `paragraph_tightened`,并在 `written_start` 记写的 `start`。
- 旁白不做任何容差裁尾;温和加速后仍放不下即 `no_safe_fit`。每段 `_placed_*.wav`
  必须与序列化后的时间线区间等长或更短,否则 `timeline_audio_mismatch` 阻断。
- 已采用配音按其 `tempo_policy` 执行:保守默认是原速且禁止段内适速,也可显式采用符合范围要求的其他速度策略;环境默认 1.15 倍速不能覆盖采用决定。显式完整声音混音分支固定原速,不做自动适配。放不下就修订安排,不裁尾。严格运行使用新工作目录与新输出路径;输入/实际混音来源变动或 QC 失败时,不发布候选成片。没有采用文件时仍可按默认旁白路径合成,但消费记录为 `UNADOPTED`。
- 原声在旁白结束后最多再压低 3 秒,等这段时间内的下一个句末锚点:压到它的 `pause_start`,只在实测停顿内渐强,
  于 `source_restore_at` 回满(锚点为 `unverified` 时状态记 `sentence_boundary_unverified`)。3 秒内没有锚点时,
  离时间线末端不足 3 秒就压到末端(`held_to_timeline_end`),否则在旁白结束处直接回满(`bounded_release`),
  不为远处的锚点长时间压住原声对白。`assembly_qc.json` 的 `summary.max_source_duck_hold_seconds` 记录最长的压低延续。
- `--export-jianying` / `EXPORT_JIANYING=1` 可把 `timeline.json` 导出为可编辑草稿。cut 模式应传 `--source-video <orig>`,让草稿引用真实原片区间。
- 剪映导出默认把视频、音频与图片复制到 `Resources/local/{video,audio,image}`,保持草稿可搬迁;`--jianying-no-bundle-media` 只适合原路径始终可访问的情况。
- 重叠覆盖物会拆到编号轨道;非空目标目录不会覆盖,而会创建编号兄弟目录。
- 导出只接受 `schema_version: 2` 的 `timeline.json`,只映射视频、音频、字幕和图片叠层(`scale` / `position`);变速、转场、蒙版、富文本、特效轨等手写扩展字段会被明确拒绝。
- 剪映草稿引用未烧录的源视频,因此原片硬字幕仍会保留,必要时在剪映内另行遮罩。
- 字幕外观可用 `SUBTITLE_FONT_SIZE`、`SUBTITLE_MARGIN_V`、`SUBTITLE_MAX_CHARS` 等控制。
- `SUBTITLE_Y_TOP/BOT` 把 ASS 基线放到测得的原片字幕区域,坐标为显示画布上的半开 `[top, bot)`,只接受方形或近方形像素(SAR 与 1:1 相差不超过 2%,未标注的 `0:1` 按方形);比例遮罩默认 `SUBTITLE_MASK_OPACITY=0.6`;显式指定实测字幕带时默认不透明,除非另设该变量。`SOURCE_SUBTITLE_MASK_TIMING` 默认是 `narration`。
- 原声在旁白间隙回到 `IDLE_ORIG_VOLUME`,旁白下压到 `SPEECH_DUCKING_VOLUME`;`DUCK_FADE_SECONDS` 控制过渡。还可配置 `DUCK_BRIDGE_SECONDS`、`ZONE_DUCKING_VOLUME`、`FINAL_LOUDNORM`、`TARGET_LUFS` 与 `LOUDNESS_LIMITER_MAX_DB`。
- 可通过 `BGM_PATH` 指定 BGM;它会循环到成片长度,并按 `BGM_VOLUME` / `BGM_DUCKING_VOLUME` 混音。不要在没有创作依据时设置通用 BGM。
- 烧录字幕需要带 `subtitles` / libass 的 ffmpeg,合成阶段在渲染前预检。显式要求烧录(`--burn-subtitles` 或环境变量 `BURN_SUBTITLES`)时缺 libass 直接失败;只是默认开启时降级:不烧录,交付外挂 `.srt`(留白里的 `「」` 原声对白仅在有 `user_subtitles.*` 时照常写进去;原本由遮罩触发的对白随遮罩一起关闭,原片硬字幕可见),`visual_qc.json` 的 `warnings` 与 `assembly_manifest.json` 的 `warnings` 记一条 `subtitle_burn_degraded`,`subtitles.burn_degraded_reason` 写原因。降级后遮罩照旧关闭(`mask.trigger` 为 `burn_subtitles_degraded`)。
- `visual_overlays.json` 的文字叠加用 ffmpeg `drawtext`(libfreetype)。缺 drawtext 时合成在渲染前失败;叠加是写稿时明确加的内容,不会被静默丢掉。
- 成片画面一律是 H.264 8-bit 4:2:0 并带 `+faststart`:不需要滤镜、且源画面已是 H.264 8-bit 4:2:0(`yuv420p`,或全范围的 `yuvj420p`)、宽高为偶数时才流复制,原样交付;否则重编码为 `yuv420p`。色彩标记:源未标记或已是 BT.709 时标为 BT.709(`-colorspace/-color_primaries/-color_trc bt709`),其它已声明的色彩空间原样保留;全范围(`pc`)源保留 `pc`,其余标 `tv`。YUV 源只

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/worldwonderer/video-recap-skills
git -C video-recap-skills checkout 1d6e8d561898

Works in

1. 2026-10-20
   ✓SAFE B 89 / 100

   first audit · source 1d6e8d561898

Questions about Video Assemble

• github.com/worldwonderer/video-recap-skills/tree/main/skills/vid — the audited source at commit 1d6e8d561898 and every finding aboveObserved · 20 Oct 2026

Spotted something wrong? Report a correction · Methodology