xsl
866f363591
文档整理: - 重写 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
316 lines
12 KiB
Markdown
316 lines
12 KiB
Markdown
# 盲游 · 音频制作执行手册
|
||
|
||
> 本手册是**从零制作一款游戏音频**的操作指南，覆盖配音、音乐、音效三类。
|
||
> 所有音频均由本机 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` 后再跑 |
|