blind/docs/音频制作执行手册.md

盲游 · 音频制作执行手册

本手册是从零制作一款游戏音频的操作指南，覆盖配音、音乐、音效三类。 所有音频均由本机 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 /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（角色音色配置表）。

# 生成六个旁白的音色样本（无需参考音频，纯 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）
  └── 选定的音色样本文件

批量生产旁白配音：

# 生产所有游戏旁白
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

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

# 林夏角色台词（需在脚本 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 启动环境

conda activate acestep

3.2 生成

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

# 生成全部（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 示例（参考林夏已有）

{
    "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），然后：

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 统一做响度归一化、听筒效果、格式转换：

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 后再跑