# 盲游 · 音频制作执行手册

> 本手册是**从零制作一款游戏音频**的操作指南，覆盖配音、音乐、音效三类。
> 所有音频均由本机 AI 模型本地生成，不依赖任何真人录音或网络素材。
> 林夏项目将按本手册完全重头制作。

---

## 〇、环境速查（已就绪，无需再装）

| 类别 | 工具 | 路径 / 环境 | 用途 |
|------|------|------------|------|
| 基础 | FFmpeg 7.0 | `/usr/local/bin/ffmpeg` | 格式转换、响度归一化、听筒效果 |
| 基础 | Python 3.13 + conda | `/home/xsl/miniconda3` | 脚本运行 |
| GPU | RTX 5090 32GB | — | 模型推理 |
| **配音** | **VoxCPM2** | `/home/xsl/tts-server` · 端口 **8000** | TTS 主链路（Voice Design + 克隆） |
| 配音-备 | CosyVoice 2.0 | `/home/xsl/tools/CosyVoice` · conda `cosyvoice` | TTS 备用 |
| 配音-备 | GPT-SoVITS | `/home/xsl/tools/GPT-SoVITS` · conda `gptsovits` | TTS 备用 |
| 配音-备 | fish-speech | `/home/xsl/tools/fish-speech` · conda `fishspeech` | TTS 备用 |
| **音乐** | **ACE-Step 1.5** | `/home/xsl/tools/ACE-Step-1.5` · conda `acestep` | BGM + 铃声生成 |
| **音效** | ACE-Step 1.5 | 同上 | 氛围类音效（≥5s） |
| 音效-补 | Stable Audio Open | `/home/xsl/tools/stable-audio-tools` · conda `stableaudio` | 高品质音效补充 |
| UI 音效 | Web Audio API | 浏览器端 `audio.js` 合成 | 短促反馈音（无文件） |

**模型权重**：VoxCPM2 @ `/home/xsl/models/VoxCPM2`

> 端口说明：VoxCPM2 服务固定使用 **8000**（`/home/xsl/tts-server` 不动）。项目脚本通过 `VOXCPM_HOST`/`VOXCPM_PORT` 环境变量读取，默认 8000，已全部对齐。

---

## 一、总体流程（三类音频统一节奏）

```
准备内容（音色提示词 + 台词表 + BGM/音效 caption）
        │
        ├── 配音 ─→ 启动TTS ─→ 生成音色样本 ─→ 选定音色 ─→ 克隆生成台词 ─→ 归一化
        ├── 音乐 ─→ 启动ACE-Step ─→ 生成 ─→ 归一化
        └── 音效 ─→ 启动ACE-Step ─→ 生成 ─→ 归一化
        │
        └── 统一归一化（process_audio.sh）──→ 部署到 audio/mp3/
```

**关键原则——TTS 配音两步走**：先用提示词生成音色样本 → 人工筛选 → 再用选定音色克隆生成正式配音。不要跳过选音色这一步。

---

## 二、配音制作（TTS / VoxCPM2）

### 2.1 启动 TTS 服务

```bash
# 方式一：直接启动
bash /home/xsl/tts-server/start-voxcpm.sh
# 验证
curl http://127.0.0.1:8000/health
# 预期: {"status":"ok","model":"VoxCPM2","styled_speech":true}

# 方式二：环境检查 + 自动启动（含降噪模型回退）
bash /home/xsl/blind/audio/check_tts_env.sh
bash /home/xsl/blind/audio/check_tts_env.sh --full   # 含全链路测试合成
```

> 若降噪模型下载失败，脚本会自动回退到 `VOXCPM_ENABLE_DENOISER=0` 重试（更稳，降噪关闭）。

### 2.2 第一步：生成音色样本（Voice Design）

**输入**：角色的音色提示词（风格描述）。
**参考文档**：`docs/旁白音色提示词.md`（旁白）、`other_docs/林夏_原始设计.md` §7.3（角色音色配置表）。

```bash
# 生成六个旁白的音色样本（无需参考音频，纯 Voice Design）
cd /home/xsl/blind
python3 audio/gen_narrator_samples.py
# 输出: audio/narrator_samples/{game_id}/sample_*.wav
```

若要为新游戏/新角色生成样本，修改 `gen_narrator_samples.py` 中的 `NARRATORS` 字典：填入 `style`（音色提示词）、`speed`（语速）、`samples`（代表性台词）。

### 2.3 人工筛选音色

1. 试听 `audio/narrator_samples/{game_id}/` 下的 WAV
2. 按 `docs/旁白音色提示词.md` 末尾的"样本评估标准"打分（音色符合度、情感准确度、语速节奏、清晰度、辨识度）
3. 选定一个样本，作为该角色/旁白的**音色锚点**

### 2.4 第二步：克隆生成正式配音

**将选定音色放入参考目录**：

```
voice_mp3/narrator/{game_id}/    # 或 voice/narrator/{game_id}/（WAV）
  └── 选定的音色样本文件
```

**批量生产旁白配音**：

```bash
# 生产所有游戏旁白
python3 audio/batch_narrator_tts.py --source voice_mp3

# 只生产指定游戏
python3 audio/batch_narrator_tts.py --source voice_mp3 --game linxia

# 只生产 P0（narrate/tap/dt/intro，核心体验）
python3 audio/batch_narrator_tts.py --source voice_mp3 --priority p0

# 干跑（先看任务列表，不实际合成）
python3 audio/batch_narrator_tts.py --source voice_mp3 --dry-run
```

输出：`audio/00_raw/narrator/{game_id}/{game_id}_{scene_id}_{type}.wav`

**批量生产角色配音（林夏角色台词）**：

```bash
# 林夏角色台词（需在脚本 LINES 中维护台词表）
python3 audio/batch_tts_voxcpm.py --source voice_mp3 --dry-run    # 先看任务
python3 audio/batch_tts_voxcpm.py --source voice_mp3              # 正式生产
python3 audio/batch_tts_voxcpm.py --source voice_mp3 --role mom   # 只生产某角色
```

输出：`audio/00_raw/tts/{filename}_wav_v1.wav`

> 台词表在 `batch_tts_voxcpm.py` 的 `LINES` 变量中维护；参考音色在 `voice_mp3/{角色}/` 或 `voice/{角色}/` 下。重做林夏时需重新整理台词表。

### 2.5 VoxCPM2 API（手动单条合成时用）

| 接口 | 用途 |
|------|------|
| `POST /v1/voices` | 注册参考音频（wav_base64）→ 返回 voice_id |
| `POST /v1/speech` | 纯克隆合成（text + voice_id）→ WAV |
| `POST /v1/speech/styled` | Style Control（有 voice_id=克隆+表演；无=Voice Design） |

参数：`cfg_value`（默认 2.0）、`inference_timesteps`（默认 10）；输出 48kHz 16-bit PCM WAV。

---

## 三、音乐制作（BGM + 铃声 / ACE-Step 1.5）

### 3.1 启动环境

```bash
conda activate acestep
```

### 3.2 生成

修改 `audio/gen_music_acestep.py` 中的 `BGM_TRACKS`（每段填 `filename`、`duration`、`caption`、`seed`），然后：

```bash
# 生成全部（BGM + 铃声）
python3 audio/gen_music_acestep.py

# 只生成 BGM
python3 audio/gen_music_acestep.py --category bgm

# 只生成铃声
python3 audio/gen_music_acestep.py --category ringtone

# 干跑
python3 audio/gen_music_acestep.py --dry-run
```

输出：`audio/00_raw/music/{filename}.wav`

> RTX 5090 已在脚本顶部做了 cuBLAS 修复：`torch.backends.cuda.preferred_blas_library("cublaslt")`，无需额外处理。

### 3.3 BGM caption 示例（参考林夏已有）

```python
{
    "filename": "bgm_main_loop",
    "duration": 90,
    "caption": "lo-fi midnight bedroom, soft piano, light vinyl crackle, muted piano, subtle synth pad, occasional distant rain, melancholy but warm, ambient loop, no drums, 70 bpm",
    "lyrics": "",
    "steps": 20,
    "seed": 2103,
}
```

caption 越具体，生成质量越稳定。建议包含：风格、乐器、情绪、节奏、是否带人声、bpm。

---

## 四、音效制作（ACE-Step 1.5）

### 4.1 适用范围

- **ACE-Step 可生成**：≥5s 的氛围类音效（呼吸、心跳、转场 swell、环境底噪等）
- **需另行处理**：短促 UI 音效（叮、咚、点击）—— 由 `audio.js` 的 Web Audio 合成，无需文件
- **补充**：可用 Stable Audio Open 生成 ACE-Step 不擅长的音效

### 4.2 生成

修改 `audio/gen_sfx_acestep.py` 中的 `SFX_TRACKS`（填 `filename`、`duration`、`caption`、`seed`），然后：

```bash
conda activate acestep
python3 audio/gen_sfx_acestep.py            # 正式生成
python3 audio/gen_sfx_acestep.py --dry-run  # 干跑
```

输出：
- 音效 → `audio/00_raw/sfx/{filename}.wav`
- 环境音 → `audio/00_raw/ambience/{filename}.wav`

---

## 五、后期归一化（统一处理）

所有原始音频生成后，用 `process_audio.sh` 统一做响度归一化、听筒效果、格式转换：

```bash
cd /home/xsl/blind
bash audio/process_audio.sh tts       # 配音（含电话/语音听筒效果）
bash audio/process_audio.sh music     # BGM + 铃声
bash audio/process_audio.sh sfx       # 音效
bash audio/process_audio.sh ambience  # 环境音
bash audio/process_audio.sh all       # 全部
```

### 各类响度标准

| 类别 | 响度 | 额外处理 |
|------|------|---------|
| TTS 配音 | -16 LUFS | 电话/语音类加听筒效果（highpass+lowpass+EQ）；长语音分段拼接 |
| BGM | -18 LUFS | — |
| 音效 | -14 LUFS | — |
| 环境音 | -22 LUFS | highpass 60Hz + lowpass 12kHz |

处理流程：`audio/00_raw/{type}/` → `audio/01_processed/{type}/`

> 最终部署到 `audio/mp3/` 的文件应为 44100Hz、单声道、128kbps MP3。从 `01_processed` 拷贝/转码到 `mp3/` 时确认格式。

---

## 六、文件命名规范

### 配音（角色台词）

```
audio/mp3/tts/{role}_{scene}_{type}_wav_v1.mp3
```
林夏项目约定带 `_wav_v1` 后缀（历史命名，沿用）。

### 旁白

```
audio/mp3/narrator/{game_id}/{game_id}_{scene_id}_{type}.mp3
```

`{type}` 取值：`intro`（开场）/ `narrate`（描述）/ `tap`（单击旁白）/ `dt`（双击旁白）/ `ending_{id}`（结局）等。

### 音乐 / 音效 / 环境音

```
audio/mp3/music/{name}_v1.mp3
audio/mp3/sfx/sfx_{name}_v1.mp3
audio/mp3/ambience/amb_{name}_v1.mp3
```

---

## 七、生成优先级（生产顺序建议）

按以下顺序生产，优先保证核心体验可玩：

1. **P0（必须）**：每个游戏 `intro` + 所有 `narrate` + 所有 `tap`/`dt` 旁白
2. **P1（重要）**：所有 `ending` 结局配音
3. **P2（重要）**：角色主台词（NPC Round 1）
4. **P3（次要）**：角色反应台词（Round 2/3）、BGM
5. **P4（可选）**：条件分支变体（`_a`/`_b`）、环境音、叙事音效

> 旁白和 intro 优先级最高——它们决定玩家能否理解游戏。即使角色台词还没生成，引擎会用浏览器 TTS 兜底旁白文本，游戏也能跑起来。

---

## 八、完整生产清单（林夏重做时按此打勾）

### 配音
- [ ] 整理角色台词表（写入 `batch_tts_voxcpm.py` 的 `LINES`）
- [ ] 整理旁白脚本（对照 `docs/音频脚本.md`，写入 `batch_narrator_tts.py`）
- [ ] 为每个角色/旁白写音色提示词（对照 `docs/旁白音色提示词.md`）
- [ ] 启动 VoxCPM2：`bash /home/xsl/tts-server/start-voxcpm.sh`
- [ ] 生成音色样本：`python3 audio/gen_narrator_samples.py`
- [ ] 试听 + 选定音色，放入 `voice_mp3/narrator/{game}/`、`voice_mp3/{角色}/`
- [ ] 生产旁白：`python3 audio/batch_narrator_tts.py --source voice_mp3 --priority p0`
- [ ] 生产角色：`python3 audio/batch_tts_voxcpm.py --source voice_mp3`
- [ ] 归一化：`bash audio/process_audio.sh tts`

### 音乐
- [ ] 写 BGM caption（写入 `gen_music_acestep.py` 的 `BGM_TRACKS`）
- [ ] `conda activate acestep && python3 audio/gen_music_acestep.py --category bgm`
- [ ] 归一化：`bash audio/process_audio.sh music`

### 音效
- [ ] 写音效 caption（写入 `gen_sfx_acestep.py` 的 `SFX_TRACKS`）
- [ ] `conda activate acestep && python3 audio/gen_sfx_acestep.py`
- [ ] 归一化：`bash audio/process_audio.sh sfx && bash audio/process_audio.sh ambience`

### 部署
- [ ] 确认 `audio/mp3/` 下文件齐全、格式正确（44100Hz/单声道/128kbps MP3）
- [ ] 启动游戏验证：`python3 -m http.server 8765 --bind 0.0.0.0`，手机访问 `http://<IP>:8765/game/`

---

## 九、常见问题

| 问题 | 对策 |
|------|------|
| TTS 服务起不来 | 看 `/tmp/voxcpm-server.log`；若降噪模型下载失败，用 `VOXCPM_ENABLE_DENOISER=0 bash /home/xsl/tts-server/start-voxcpm.sh` |
| 端口 8000 被占 | `ss -lnt \| grep 8000` 查占用；如需换端口，`VOXCPM_PORT=xxxx bash start-voxcpm.sh`，并把 `gen_narrator_samples.py` 等脚本的 `VOXCPM_PORT` 一并设 |
| 某角色音色不满意 | 重新调 `style` 提示词，重跑 `gen_narrator_samples.py`，换样本 |
| 响度不统一 | 确认走了 `process_audio.sh`，别直接用 `00_raw` 的文件 |
| 长文本 TTS 质量下降 | 分段生成，`process_audio.sh` 会自动拼接（见脚本中分段处理逻辑） |
| ACE-Step 报 cuBLAS 错 | 脚本已内置修复；若仍报错，确认 `conda activate acestep` 后再跑 |