video-recap-skillsCAUTION

From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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` 阻断。
- 已采用配音的 v1 合同只支持原速、禁止段内适速;不能让环境默认 1.15 倍速或旧缓存覆盖它。放不下就修订安排,不裁尾。严格运行使用新工作目录与新输出路径;输入/实际混音来源变动或 QC 失败时,不发布候选成片。没有采用文件的旧入口仍是兼容模式,不自动获得同等证据。
- 原声在旁白结束后最多再压低 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 源只改标记,不转换像素;RGB 源(ffprobe 报 `gbr`,如 PNG/QuickTime RLE 封装的 MOV)没有 YUV 矩阵可保留,按 

CAUTIONgrade B · trust 84/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

declared (4 observation(s))

Network

declared (6 observation(s))

Shell

none-observed

Dependencies

pinned

Secrets in source

found

Findings (17)

url = f"http://127.0.0.1:{server.server_address[1]}/"

assert "ghp_" not in materials._redact_text("token ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345")

pulse-demo.wav

click-demo.wav

return eval(

return eval(expr, {"__builtins__": {}}, {"t": float(t), "min": min, "max": max})

digest = hashlib.md5(usedforsecurity=False)

assert hashlib.sha1(tokens).hexdigest() == SHARED_TOKENS_SHA1

pytest.param(BGM, lambda d: d["files"][0].update(path="../../../../outside.wav"), (BGM, "file_path"), id="path_escapes_library"),

os.environ.items() ... urllib.request

- `dashboard_server.py --host` 经 `_loopback_host` 只接受 IPv4 回环,所以只能在 127.0.0.0/8 的别名之间选;`main()` 却总打印 `http://127.0.0.1:<端口>/`,传 `--host 127.0.0.2` 时打印的地址是错的。SKILL.md 与 `resource-library.md` 都没写这个参数,唯一

export INDEX_TTS_ENDPOINT=http://127.0.0.1:<port>/tts

"批准全文。", output, endpoint="http://127.0.0.1:9880/tts", voice="private-voice", timeout=7

Path(out_wav).write_bytes(base64.b64decode(data))

output_path.write_bytes(base64.b64decode(audio_data))

assert base64.b64decode(encoded) == b"R" * 45

for block in re.split(r"\r?\n\s*\r?\n", text.lstrip("").strip()):

Gates applied: no_behavioural_pass.