项目整理：重写主文档、归档过时文档、清理死代码、新增音频制作手册

文档整理: - 重写 game/操作说明.md 为项目主文档（6游戏/6手势/旁白/模型生成音频/TTS两步流程） - 归档过时文档至 other_docs/（林夏原始设计、旧执行文档） - 新增 docs/音频制作执行手册.md（从零制作游戏音频的完整流程） - docs/ 下保留旁白音色提示词、音频脚本代码清理: - 删除旧架构死代码: story.js / gestures.js / profile.js - 删除耦合旧架构的过时测试目录 game/tests/ 脚本配置修正: - check_tts_env.sh: 启动脚本路径 AutoVideo → tts-server（实际位置） - gen_narrator_samples.py: 硬编码地址改为环境变量，默认对齐 tts-server 端口 8000
2026-06-19 22:29:04 +08:00
parent b3384499e3
commit 866f363591
46 changed files with 5061 additions and 2374 deletions
@@ -0,0 +1,315 @@
+# 盲游 · 音频制作执行手册
+
+> 本手册是**从零制作一款游戏音频**的操作指南，覆盖配音、音乐、音效三类。
+> 所有音频均由本机 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` 后再跑 |