# KMC 音乐引擎使用情形指南（2026-09-15）

> 口径：`bgm_spotting.py` 实读（1354 行，`/data/workspace/kais-hermes-skills/skills/movie-experts/audio_pipeline/scripts/`）+ kap-music-engine-strategy skill。commits 锚：`894f97ba`+`6822fe71`（KMC 消费端）、`1c4e7bcc`（KAP yue2 路由族）、`dbccb96`（三引擎分工落地）。

## 一、总路由表：什么情形用什么引擎

| # | 情形 | 引擎 | 触发方式 | 自动化程度 |
|---|---|---|---|---|
| 1 | **P12b spotting 全部 cue**（每集 BGM 主路径，cue 4.5–33s） | SA3（base 档） | `_kap_generate()` 级联 P1 | 全自动（管线内） |
| 2 | KAP API 不可用（生成失败/超时） | kais-bgm 曲库 | `_match_library()` 级联 P2 | 全自动 fallback |
| 3 | 曲库也没命中 | numpy drone | `_numpy_drone()` 级联 P3 | 全自动兜底（DEGRADED） |
| 4 | cue ≥60s 且显式开 `BGM_ENGINE_ACE=1` | ACE-Step 1.5 | `_kap_ace_step()` | **死分支**——实测两集 EDL 全部 cue <60s，等于从不触发 |
| 5 | **渲外特殊位长曲**（主题曲/OP-ED/宣传曲，60–360s） | m3 | 手动脚本 `import _kap_m3` | 人工触发 |
| 6 | **渲外特殊位人声歌**（主题曲/角色歌/翻唱 demo） | YuE2 | 手动脚本 `import _kap_yue2_with_gate` | 人工触发（门内自动换 seed 重试） |

## 二、P12b 级联真相（实读 `spotting_session_compose` L1255–1300）

```
P1 KAP SA3 生成（主路径）──失败──▶ P2 kais-bgm 曲库 ──未命中──▶ P3 numpy drone
```

- `_kap_generate()` 内部：`BGM_ENGINE_ACE=1 且 dur≥60` 才走 ACE，否则全部 SA3。
- 级联只认 SA3/曲库/drone 三层；**m3/YuE2 永远不在级联里**（见硬规则 R11）。
- 实际生产调用形态 = P12b 子代理 standalone import（`gen_bgm2.py` 模式），`bgm_spotting` 是子代理工具箱而非管线确定性步骤。

## 三、特殊位旁路（渲外人工触发）

### m3 — `_kap_m3(prompt, duration, out_path)`

```python
from bgm_spotting import _kap_m3
raw = _kap_m3("epic orchestral theme", 120, "/path/out.flac")  # 默认 [Instrumental]
```

- 适用：英文轴最优、开放许可证（**商用项目唯一选择**）、synthwave 类死区风格回退位。
- 耗时：2.6–7.5× realtime（CN 77s / EN 339s @45s 曲）；VRAM 22.5GB 物理互斥级。
- 运维：:5112 无 systemd 易宕，用前 `curl /health`；**渲期禁调**；用完即杀进程还卡（kill music3-server 释放 22GB）。

### YuE2 — `_kap_yue2_with_gate(style, lyrics, duration, out_path)`

```python
from bgm_spotting import _kap_yue2_with_gate
r = _kap_yue2_with_gate("Chinese ballad, warm piano", "歌词…", 45, "/path/out.flac")
# → {path, prompt_id, seed, license, vocal_gate, attempts}
```

- 适用：中文人声快速出曲（0.22×rt，10–19s/45s 曲）、中文 ballad 轴（盲审连续两日 ≥m3）、旋律符号轴实验（:8195 探针位）。
- **ASR 人声门**：faster-whisper small CPU，sim≥0.30；fail 自动换 seed 重试 ×2；`skipped≠pass`（ASR 环境缺失显式可见，禁静默放行）。
- 生产前置：`YUE2_ASR_PYTHON` 必须显式设（fallback `/tmp/asr0914/venv` → 降级 skipped）。
- **不做跨风格自动改写**：synthwave 类死区风格（人声率 0/6，引擎级死症）换 seed 无效 → 直接回退 `_kap_m3`。
- 许可证：CC-BY-NC（**商用红线**）。

## 四、三条硬规则

| 规则 | 内容 | 违反后果 |
|---|---|---|
| **R11 禁唱** | spotting 位 BGM 禁含人声（p12b_audio_composition.py:974）→ m3/YuE2 永不进级联 | 人声污染 BGM 轨 |
| **渲期避让** | m3 22.5GB 与 H3 渲染权重物理互斥；YuE2 7.6G 也守「渲前 ComfyUI queue 空」 | 渲染 OOM / 级联排队分钟级 |
| **死区风格分流** | synthwave 类（人声率 0/6）或商用项目 → 直接 m3，不试 YuE2 | 白烧 3 次重试仍无人声 |

## 五、定谳时间线（证据锚）

| 日期 | 定谳 | 台账 |
|---|---|---|
| 08-17 | 三引擎分工：SA3 单引擎主线 + m3 旁路特殊位（m3 三重否决：R11/GPU 互斥/9×rt） | commit dbccb96 |
| 09-13 | YuE2 双题盲选 2:0 m3 → 09-14 四臂盲审翻身（起效变量=步数 32→50） | `shared/2026-09-13/yue2_*_verdict.json` |
| 09-14 晚 | 六题泛化批：无普适赢家，i8-32 最稳（14/18）；核心发现 25% 轨迹无有效人声 → 生产前置=ASR 门+换 seed | `shared/2026-09-14/yue2_gen_verdict.json` |
| 09-15 | seed 轴探针：人声缺失主因=**风格轴**（synthwave 0/6 死症）；KAP yue2 路由族割接（int8-32 默认档）；KMC `with_gate` 消费端落地（19 单测+真机门 sim=0.732） | `shared/2026-09-15/vp_probe/` |

## 六、SA3 档位注意（08-18 定案）

- KAP 默认已切 base（非蒸馏）档：euler/50steps/cfg7，调用方无需传 steps/cfg。
- base 偏暗，prompt 建议带 brightness 词（"bright, luminous"）。
- 耗时 ~70s/30s 曲（vs distilled ~9s）——渲外可接受，渲期按避让规则。