# 每视频自适应 VAD 调参方案

## 背景：为什么必须每视频单独调 VAD

实测 CJOD-255 音频（2 小时成人视频）暴露了固定 VAD 配置的根本缺陷：

- 全片 1s 能量 **56% 在 RMS<900（音乐/低语）**、仅 13% 是静音级(<300)；
  全程有 BGM，**几乎没有纯静音**。
- 简单能量阈值（RMS>700）会把**整片识别成 1 个 4120s 的巨型语音段**——
  BGM 让能量始终高于阈值，VAD 无法分离出真实说话。
- 结果是 whisper 全段解码：80% 字幕碎片化（啊/嗯/はい）、32% 参考句漏识别、
  敏感段（口交等）丢失。

不同视频的 BGM/静音/人声比例天差地别（测试片、音乐 MV、含 BGM 剧集、
纯语音播客），**固定 VAD 参数必然在多数视频上偏差**。因此需要对**每个视频**
先独立做信号分析，再动态决定 VAD 参数。

## 可行性

1. **VAD 是解码前的前置步骤**：先用 ffmpeg 提 WAV（已有），可独立做信号分析，
   不占用模型推理资源。
2. **faster-whisper 支持 `vad_parameters` 细参**：可传
   `threshold`（说话判定阈值）、`min_silence_duration_ms`（断句静音时长）、
   `speech_pad_ms`（语音段首尾缓冲）。当前节点只传 `vad_filter`，细参入口未用。
3. **求解代价可控**：找最优参数在 1-2 分钟代表性片段上做网格搜索，
   全片只跑一次确定后的参数。

## 方案架构（三层）

```
每个视频进入 whisper 节点时：
┌─────────────────────────────────────────────────────────┐
│ ① 信号分析 profile_audio（秒级，无模型）                │
│    - 1s 网格能量/RMS 分布 → 静音比例、BGM 底噪、语音疏密    │
│    - 推断：threshold 候选、min_silence 候选、speech_pad    │
│ ② 片段网格验证 pick_best_vad（90s 代表片段，3~5 组参数）    │
│    - 若提供参考字幕 → 用"参考覆盖率+时间对齐误差"评分      │
│    - 无参考 → 用"碎片率/连贯性/置信度"启发式评分            │
│ ③ 全片用 ② 选出的 vad_parameters 跑一次                  │
└─────────────────────────────────────────────────────────┘
```

## 信号分析 → VAD 参数推荐规则

| 音频特征（从能量分布算出） | VAD 建议 |
| --- | --- |
| 静音比例高（>30%）、BGM 低 | threshold 高(0.6~0.7)、min_silence 2000，正常 VAD |
| **BGM 覆盖广（如 CJOD 56%<900）** | **threshold 低(0.3~0.4)、min_silence 300~500、speech_pad 0**——避免把音乐当语音整段拼接 |
| 纯语音（播客/采访）| threshold 0.5、min_silence 1000，普通 |
| 长静音（停顿>2s 常见）| speech_pad 减小（0~200）防时间轴压缩漂移 |

### 关键：BGM 掩盖音频的处理

对整片被 BGM 覆盖的视频，纯能量 VAD 天然失效。三种手段按优先级：

1. **降低 VAD threshold**（0.5→0.3）：让 silero 的语音概率模型在 BGM 中
   更敏感地捕捉人声，避免把音乐段误判为静音而吞掉轻语。
2. **降低 min_silence_duration_ms**（2000→300~500）：避免把停顿超过 2s 的
   短句硬并成一条，缓解"碎片化/漏句"。
3. **speech_pad_ms 减小**（400→0~200）：缓冲越大，Whisper 对片段起始时间
   估计越偏早，减小可提升时间对齐精度。

## 评分器（决定最优参数）

### 有参考字幕（OCR 硬字幕 = ground truth）
参考的第 k 条 vs 转录的对齐：
- **覆盖率** = 能在 1.5s 内找到语义对应日文的参考条数 / 总参考条数（越高越好）
- **时间误差** = 配对条目 |转录start - 参考start| 的平均（越低越好）
- 综合分 = 覆盖率 - 0.3×时间误差（权重可调）

### 无参考字幕（启发式）
用转录自身质量：
- **碎声率** = 纯单字/语气词条目占比（越低越好，如 <20%）
- **连贯性** = 每条平均字数（适中为好，不碎不并）
- **置信度** = whisper segment 的 avg_logprob

## 实现落点

- 新模块 `nodes/vad_profiler.py`：`profile_audio()`（信号分析）、
  `pick_best_vad()`（片段网格 + 评分）、`vad_parameters_for_audio()`（总入口）
- `nodes/whisper.py`：在 `invoke` 里检测到 `vad_filter=true` 且未显式传
  `vad_parameters` 时，调用 profiler 生成 per-video 参数传给 `transcribe()`
- 参考字幕可选：若工作流/请求提供 `reference_srt_uri`，走"有参考评分"
- 门控：`WOV_AUTO_VAD=1`（默认开），可关；显式传 `vad_parameters` 时跳过

## 取舍

- **收益**：每个视频用最贴合其声学的 VAD，显著降低碎片化、漏句、时间错位，
  尤其对 BGM 音频（如成人视频、综艺）。
- **成本**：每视频额外 10~30s 信号分析 + 片段上 3~5 次短转写（分钟级），
  相比全片转写可接受。
- **风险**：片段网格选取的代表性片段若无说话/纯音乐，可能评为最差参数。
  缓解：选 2 段（开头+中段）拼接，且阈值下限保护。
## 实现状态（2026-09 已落地）

- `nodes/vad_profiler.py`：`profile_audio()`（1s 能量分析）、
  `suggest_vad_parameters()`（信号→VAD 建议）、`score_transcript()`（幻觉词
  扣分启发式）、`vad_parameters_for_audio()`（总入口）、`_pick_representative_start()`
  与 `_grid_search_vad()`（片段网格）。
- `nodes/whisper.py`：`invoke` 检测到 `vad_filter=true` 且未显式传
  `vad_parameters` 且 `WOV_AUTO_VAD=1` 时，自动调用 profiler 生成 per-video 参数
  传给 `transcribe()`；分析失败回退默认不中断转写。
- 测试 `tests/test_vad_profiler.py`（19 个）覆盖：信号分析、四个建议分支、
  幻觉词/碎片评分、网格选优、异常回退、空音频/低采样率、候选网格展开。
- 门控：`WOV_AUTO_VAD=0` 关闭自动调参；显式传 `vad_parameters` 时跳过。
- 说明：当前接入默认 `whisper_invoke=None`（仅信号分析，秒级、不额外跑模型）；
  若未来要启用片段网格验证，传入 whisper 回调并暴露配置即可，框架已就绪。