同步音频文档至 v5 克隆现行状态

更新林夏设计纲要、执行文档与技术报告，对齐 VoxCPM2 8002 端口、v4/v5 流水线、游戏 184 个 MP3 引用及 13 角色参考音色。

Co-authored-by: Cursor <cursoragent@cursor.com>

执行文档_音频素材制作.md

@@ -1,9 +1,10 @@
 # 《林夏》音频素材本地制作执行文档
 
-> **前置文档**：`林夏.md`（游戏设计）、`SOP_AI音频生产.md`（生产规范）
-> **执行环境**：本机 WSL2 · RTX 5090 32GB · FFmpeg 7.0
-> **TTS 主链路**：**VoxCPM2**（见 `林夏.md` §7.2），批量脚本 `audio/batch_tts_voxcpm.py`
-> **TTS 备用**：CosyVoice2-0.5B（见附录 B）
+> **前置文档**：`林夏.md`（游戏设计）、`SOP_AI音频生产.md`（生产规范）  
+> **现行状态**：`audio_2/项目状态说明.md`（v5 音色、目录、命令，**以此为准**）  
+> **执行环境**：本机 WSL2 · RTX 5090 32GB · FFmpeg 7.0  
+> **TTS 主链路**：**VoxCPM2**（Voice Design 试听 → 克隆 → Style Control 表演），脚本 `audio_2/scripts/04_gen_tts_clone.py`  
+> **TTS 备用**：CosyVoice2-0.5B（见附录 B）  
 > **目标**：按 SOP 规范在本地生产全部音频素材
 
 ---
@@ -12,14 +13,17 @@
 
 | 资源 | 路径 / 状态 | 用途 |
 |---|---|---|
-| **VoxCPM2** | `bash /home/xsl/AutoVideo/start-voxcpm.sh` → `http://127.0.0.1:8000` | **TTS 主链路**（声音克隆 + 合成） |
+| **VoxCPM2** | `/home/xsl/tts-server/` · 端口 **8002** · `bash /home/xsl/tts-server/start-voxcpm.sh` | **TTS 主链路**（Voice Design + 声音克隆 + Style Control） |
 | CosyVoice 2.0 (0.5B) | `/home/xsl/tools/CosyVoice` · conda env: `cosyvoice` | TTS 备用（见附录 B） |
+| ACE-Step 1.5 | `/home/xsl/tools/ACE-Step-1.5` · conda env: `acestep` | BGM / 铃声 / 叙事音效 / 环境音 |
+| Stable Audio Open 1.0 | `/home/xsl/tools/stable-audio-tools` · conda env: `stableaudio` | 高品质音效补充 |
 | FFmpeg 7.0 | `/usr/local/bin/ffmpeg` | 音频格式转换、响度归一化、听筒效果 |
-| GPU | RTX 5090 32GB | 跑 VoxCPM2 / CosyVoice 推理 |
+| GPU | RTX 5090 32GB | 跑 VoxCPM2 / CosyVoice / ACE-Step 推理 |
 | MuseTalk | `/home/xsl/work/MuseTalk` | **注意：这是唇形同步工具，不是 TTS** |
 
-> **SOP 中的 MiniMax / 豆包 API 全部替换为本地 VoxCPM2**。音乐（Suno）、音效（ElevenLabs SFX）、环境采样（Freesound）仍走云端。
-> CosyVoice2 保留作为备用方案（见附录 B），仅在 VoxCPM2 表现不佳时切换。
+> **端口说明**：8000 被 head3d 占用，TTS 固定使用 **8002**（`VOXCPM_PORT=8002`）。  
+> **游戏运行时音频**：`audio/mp3/`（184 文件，仅保留 `story.js` / `engine.js` 引用的 `*_wav_v1.mp3` 等）。  
+> CosyVoice2 保留作为备用，仅在 VoxCPM2 表现不佳时切换。
 
 ---
 
@@ -36,20 +40,26 @@ mkdir -p voice/{linxia,mom,azhe,xiaomei,zhounan,hr,anan,dorm_a,dorm_b,dorm_c,del
 ### 1.2 启动 VoxCPM2 服务
 
 ```bash
-# 启动 VoxCPM2 TTS 服务
-bash /home/xsl/AutoVideo/start-voxcpm.sh
-# uvicorn 服务: http://127.0.0.1:8000
+VOXCPM_PORT=8002 VOXCPM_ENABLE_DENOISER=0 bash /home/xsl/tts-server/start-voxcpm.sh
+# 服务: http://127.0.0.1:8002
 ```
 
 验证服务可用：
 ```bash
-curl -s http://127.0.0.1:8000/docs | head -5
-# 应返回 API 文档页面
+curl -s http://127.0.0.1:8002/health
+# 预期: {"status":"ok","model":"VoxCPM2","styled_speech":true}
 ```
 
-**VoxCPM2 API 接口**（详见 `林夏.md` §7.2）：
-- `POST /v1/voices` — 注册参考音频（wav_base64）→ 返回 voice_id
-- `POST /v1/speech` — 合成语音（text + voice_id）→ 返回 WAV
+**VoxCPM2 API 接口**（详见 `林夏.md` §7.2、`/home/xsl/tts-server/server.py`）：
+
+| 接口 | 用途 |
+|------|------|
+| `POST /v1/voices` | 注册参考音频（wav_base64）→ voice_id |
+| `POST /v1/speech` | 纯克隆合成（text + voice_id）→ WAV |
+| `POST /v1/speech/styled` | Style Control / Voice Design（见下） |
+
+- 有 `voice_id` → 克隆音色 + style 表演修饰
+- 无 `voice_id` → 纯 Voice Design（仅提示词，无参考音频）
 - 输出格式：48kHz 16-bit PCM WAV
 
 ### 1.4 验证 FFmpeg
@@ -67,104 +77,118 @@ echo "FFmpeg loudnorm 可用"
 
 ## 2. 角色参考音频准备（关键步骤）
 
-VoxCPM2 的声音克隆需要**每个角色一段参考音频**（WAV 格式）。参考音频的音色决定了最终 TTS 的音色。参考音频存放在 `voice/{角色}/` 目录下（详见 `林夏.md` §7.3 角色音色配置）。
+VoxCPM2 的声音克隆需要**每个角色一段参考音频**（WAV）。**现行方案**：先用 Voice Design 生成试听变体，人工选定后作为永久参考。
 
-### 2.1 参考音频来源方案
+### 2.1 现行流程（v4 → v5）
+
+```
+1. 03_gen_voice_samples.py  → 每角色 5 条约 10s 试听（不同提示词）
+2. 人工试听，每角色保留 1 条 → audio_2/tts/v4_voice_samples/{role}/
+3. 04_gen_tts_clone.py       → 全量克隆 + 部署 audio/mp3/tts/*_wav_v1.mp3
+4. 副本同步到 voice/{角色}/{角色}_ref.wav
+```
+
+**已选定参考**（2026-05-23）：
+
+| 角色 | 文件 | 性别 |
+|------|------|------|
+| linxia | `linxia_v05.wav` | 女 |
+| mom | `mom_v01.wav` | 女 |
+| azhe | `azhe_v03.wav` | 男 |
+| xiaomei | `xiaomei_v05.wav` | 女 |
+| xiaomei_drunk | `xiaomei_drunk_v05.wav` | 女 |
+| zhounan | `zhounan_v05.wav` | 男 |
+| hr | `hr_v05.wav` | 女 |
+| anan | `anan_v04.wav` | 女 |
+| dorm_a/b/c | `v03` / `v02` / `v03` | 女 |
+| delivery | `delivery_v04.wav` | **男** |
+| self_3y | `self_3y_v03.wav` | 女 |
+
+提示词配置：`audio_2/voice_sample_prompts.py`（试听）、`audio_2/voice_style_prompts.py`（表演修饰）。
+
+### 2.2 参考音频规格（仍适用）
+
+- **时长**：5-20 秒（推荐 10 秒左右）
+- **格式**：WAV，16kHz mono（注册前由脚本自动转换）
+- **内容**：完整中文句子
+- **质量**：干声为主，避免底噪、混响、BGM
+
+### 2.3 旧方案（人工录音 / 截取）
+
+若 Voice Design 不满意，仍可按原方案准备参考音频放入 `voice/{角色}/`：
 
 | 角色 | 音色要求 | 参考音频获取方案 |
 |---|---|---|
-| `mom` 妈妈 | 50 岁，温柔克制 | 方案 A：找一位 45-55 岁女性朋友录 15 秒朗读（最佳）；方案 B：从影视作品中截取合适片段 |
-| `azhe` 阿哲 | 27 岁，理性偏冷 | 从播客/有声书截取年轻男声冷淡片段 |
-| `xiaomei` 小美 | 24 岁，活泼 | 找年轻女性朋友录制，或从 vlog 截取 |
-| `zhounan` 周南 | 26 岁，温和拘谨 | 播客/有声书截取温和男声 |
-| `hr` HR 王姐 | 38 岁，知性 | 新闻女主播或播客截取 |
-| `anan` 安安 | 23 岁，可爱 | 年轻女性活泼语调截取 |
-| `dorm-a/b/c` | 三个不同年轻女声 | 需要 3 段风格不同的女声参考 |
-| `delivery` 外卖小哥 | 30 岁，北方腔 | 短视频/影视截取 |
-| `system` 系统 | 中性 AI 女声 | VoxCPM2 注册一个中性女声参考音频 |
-| `self-3y` 3年前自己 | 同 xiaomei 基底 | 复用 xiaomei 参考音频，调速度和音调 |
-
-### 2.2 参考音频制作规格
-
-- **时长**：5-20 秒（推荐 10 秒左右）
-- **格式**：WAV，16kHz 以上采样率
-- **内容**：完整的中文句子（需同时记录对应文字）
-- **质量**：干声为主，避免底噪、混响、BGM
-
-存放路径：`voice/{角色代号}/`（与 `林夏.md` §7.3 保持一致）
-
-```bash
-# 如果参考音频不是 wav 或采样率不对，用 FFmpeg 转换
-ffmpeg -i input.mp3 -ar 16000 -ac 1 voice/mom/ref.wav
-```
-
-### 2.3 创建参考音频记录表
-
-在 `voice/` 下创建 `ref_manifest.txt`，记录每条参考音频对应的文字：
-
-```
-mom/ref.wav | 今天天气不错，妈妈给你做了红烧排骨，等你回来吃饭。
-azhe/ref.wav | 好的，我知道了，那件事明天再说吧。
-xiaomei/ref.wav | 哎你猜怎么着，今天路上遇到一个超级搞笑的事！
-zhounan/ref.wav | 嗯，其实我也不太确定，就是觉得应该跟你说一声。
-hr/ref.wav | 好的，那我们下周三前把流程走完，有什么问题随时联系我。
-anan/ref.wav | 天呐天呐你快来！这边超级好玩的！
-dorm_a/ref.wav | 嘿你们看看我，今天升职了！请大家吃饭！
-dorm_b/ref.wav | 恭喜恭喜啊，太厉害了，我就知道你行的。
-dorm_c/ref.wav | 嗯，不错，对了夏夏怎么不说话啊。
-delivery/ref.wav | 你好你的外卖到了，放门口了啊，麻辣烫注意别洒了。
-```
+| `mom` 妈妈 | 50 岁，温柔克制 | 真人录音或影视截取 |
+| `azhe` 阿哲 | 27 岁男声，理性偏冷 | 播客/有声书截取 |
+| `delivery` 外卖小哥 | 30 岁北方男声 | 语速适中，非过快 |
+| … | 见 `林夏.md` §7.3 | — |
 
 ---
 
 ## 3. TTS 生产流程
 
-### 3.1 VoxCPM2 声音克隆流程
+### 3.0 现行主力：v5 克隆流水线 ★
 
-**前置**：确认 VoxCPM2 服务已启动（§1.2）。
-
-**单条合成步骤**：
-1. 将角色参考音频注册为 voice_id：`POST /v1/voices`（wav_base64）
-2. 调用合成接口：`POST /v1/speech`（text + voice_id）
-3. 获得 48kHz 16-bit PCM WAV
-4. 用 FFmpeg atempo 调速（按 `林夏.md` §7.3 各角色语速配置）
-5. 保存到 `audio/00_raw/tts/`
-
-**角色音色目录**（与 `林夏.md` §7.3 一致）：
-```
-voice/
-├── linxia/     # 林夏（speed 1.00）
-├── mom/        # 妈妈（speed 0.92）
-├── azhe/       # 阿哲（speed 1.05）
-├── xiaomei/    # 小美（speed 1.10，醉态 0.95）
-├── zhounan/    # 周南（speed 0.95）
-├── hr/         # HR 王姐（speed 1.00）
-├── anan/       # 安安（speed 1.15）
-├── dorm_a/     # 室友 A（speed 1.10）
-├── dorm_b/     # 室友 B（speed 1.00）
-├── dorm_c/     # 室友 C（speed 0.95）
-└── delivery/   # 外卖小哥（speed 1.20）
-```
-
-### 3.2 用批量脚本生产（主力方式）
-
-使用项目自带的 VoxCPM2 批量合成脚本：
+**前置**：VoxCPM2 已启动（§1.2），参考音频已在 `v4_voice_samples/` 每角色 1 条。
 
 ```bash
-# 确保 VoxCPM2 服务已启动
-bash /home/xsl/AutoVideo/start-voxcpm.sh
+cd /home/xsl/blind
 
-# 批量合成所有台词
-python audio/batch_tts_voxcpm.py --source voice
+# 全量克隆 + 自动部署游戏目录
+VOXCPM_PORT=8002 python audio_2/scripts/04_gen_tts_clone.py --force
 
-# 只合成特定角色
-python audio/batch_tts_voxcpm.py --source voice --role linxia
+# 只重跑某角色
+VOXCPM_PORT=8002 python audio_2/scripts/04_gen_tts_clone.py --role delivery --force
 
-# 干跑查看任务列表
+# 预览任务
+python audio_2/scripts/04_gen_tts_clone.py --dry-run
+```
+
+| 步骤 | 脚本 | 输出 |
+|------|------|------|
+| 试听选音色 | `03_gen_voice_samples.py` | `audio_2/tts/v4_voice_samples/` |
+| 全量克隆 | `04_gen_tts_clone.py` | `audio_2/tts/v5_cloned/*_wav_v5.mp3` |
+| 游戏部署 | （04 脚本自动） | `audio/mp3/tts/*_wav_v1.mp3` |
+
+- 台词来源：`audio/batch_tts_voxcpm.py` → `LINES`（173 条）+ `EXTRA_LINES`（self-3y ×3、系统 memo）
+- 表演修饰：`audio_2/voice_style_prompts.py` → `get_clone_style()`
+- 清单：`audio_2/tts/v5_cloned/clone_manifest.tsv`
+
+**游戏仅加载 `*_wav_v1.mp3`**，不加载 `*_mp3_v1.mp3`。
+
+### 3.1 VoxCPM2 声音克隆流程（底层原理）
+
+**单条合成步骤**：
+1. 将角色参考音频注册为 voice_id：`POST /v1/voices`
+2. 调用：`POST /v1/speech/styled`（text + voice_id + style 表演修饰）
+3. 获得 48kHz WAV → ffmpeg atempo 调速（`ROLES` 配置）→ MP3
+4. 部署到 `audio/mp3/tts/`
+
+**角色语速**（`audio/batch_tts_voxcpm.py` → `ROLES`，与 `林夏.md` §7.3 一致）：
+
+```
+voice/
+├── linxia/     # 1.00
+├── mom/        # 0.92
+├── azhe/       # 1.05
+├── xiaomei/    # 1.10（醉态 xiaomei_drunk 0.95）
+├── zhounan/    # 0.95
+├── hr/         # 1.00
+├── anan/       # 1.15
+├── dorm_a/b/c  # 1.10 / 1.00 / 0.95
+├── delivery/   # 1.00（已从 1.20 调慢）
+└── self_3y/    # 1.15（独立参考 self_3y_v03.wav）
+```
+
+### 3.2 旧版批量脚本（参考，已被 v5 替代）
+
+```bash
+# 旧流程：直接读 voice/ 参考，无 Style Control 表演
 python audio/batch_tts_voxcpm.py --source voice --dry-run
 ```
 
-脚本读取 `voice/` 目录下的参考音频，按 `林夏.md` §7.3 角色配置自动注册 voice_id 并批量合成。输出到 `audio/00_raw/tts/`。
+输出原为 `audio/00_raw/tts/`，现正式产物见 `audio_2/tts/v5_cloned/` 与 `audio/mp3/tts/`。
 
 ### 3.3 长戏分段处理
 
@@ -191,29 +215,22 @@ SOP §5.3 规定：**超过 30 秒的台词必须分段录制**。
 
 ### 3.4 系统 TTS
 
-系统提示音（播报状态、念选项等）用 VoxCPM2 注册一个中性女声参考音频：
+系统提示音（内容警告、暂停、热线、等待回复、memo 等）**现行方案**：
 
-1. 准备一段清晰的中性女声参考音频（如新闻播报片段），存入 `voice/system/`
-2. 通过 `POST /v1/voices` 注册为 system voice_id
-3. 用 `POST /v1/speech` 合成所有系统语句
-
-系统语句示例：
-- "阿哲，发来1条语音。8秒。"
-- "是否回复？"
-- "一，好，明天寄。二，你怎么不自己来拿。三，你那边都好吗。四，什么都不说。"
-- "妈妈3条未读、小美1条已读、阿哲1条未播放"
+- 大部分系统语音用 **林夏音色**（`linxia_ref.wav`）克隆，见 `LINES` 中 `v2_sys_*` 与 `lv11_sys_memo_01`
+- 合成走 v5 流水线，与对白同一套参考
 
 ### 3.5 self-3y 三版预录
 
-使用与 `xiaomei` 同基底参考音频，但调整 speed 为 +0.05（即 1.15）：
+**现行**：独立参考 `self_3y_v03.wav`（非复用小美），角色 key 为 `self_3y`，speed 1.15。
 
-| 版本 | 文件名 | 内容要求 | 情绪 |
-|---|---|---|---|
-| 明朗版 | `lv11_0030_self-3y_voice_01` | 3 年前刚来北京，对一切新鲜 | 兴奋带紧张 |
-| 迷茫版 | `lv11_0030_self-3y_voice_02` | 3 年前已经累了 | 假装坚强 |
-| 温柔版 | `lv11_0030_self-3y_voice_03` | 写给未来的自己 | 平静有力 |
+| 版本 | 文件名 | 情绪 |
+|---|---|---|
+| 明朗版 | `lv11_0030_self3y_voice_01` | 兴奋带紧张 |
+| 迷茫版 | `lv11_0030_self3y_voice_02` | 疲惫假装坚强 |
+| 温柔版 | `lv11_0030_self3y_voice_03` | 平静有力 |
 
-> 台词需要编剧写好，每版约 50 秒。
+台词见 `audio_2/scripts/04_gen_tts_clone.py` → `EXTRA_LINES`。
 
 ---
 
@@ -346,9 +363,11 @@ ffmpeg -i input.wav \
 
 ---
 
-## 5. 音乐素材（Suno）
+## 5. 音乐素材（ACE-Step 本地 + Suno 备选）
 
-音乐生产仍走 Suno 云端，按 SOP §6 操作。
+**现行产出**：BGM 4 轨 + 铃声 5 条，均由 **ACE-Step 1.5** 本地生成，已部署至 `audio/mp3/music/`。
+
+Suno 仍可作为备选（按 SOP §6 操作）：
 
 ### 5.1 操作步骤
 
@@ -380,7 +399,11 @@ done
 
 ---
 
-## 6. 音效素材（ElevenLabs SFX）
+## 6. 音效素材（ACE-Step 本地 + ElevenLabs 备选）
+
+**现行产出**：叙事音效 4 条（敲门、心跳、呼吸、水壶）在 `audio/mp3/sfx/`，由 ACE-Step 生成。
+
+ElevenLabs SFX 仍可作为备选：
 
 ### 6.1 操作步骤
 
@@ -491,34 +514,25 @@ done
 
 ---
 
-## 9. 执行顺序总结
+## 9. 执行顺序总结（现行状态 2026-05-23）
 
 ```
-第 1 步 · 启动 VoxCPM2 + 部署环境 (§1)
-    ↓    约 30 分钟
-第 2 步 · 准备参考音频到 voice/ (§2)  ← 这一步最关键，音色质量取决于此
-    ↓    约 1-3 天（需要找人录音或搜集素材）
-第 3 步 · 系统 TTS 先行 (§3.4)       ← 最简单的先跑通 VoxCPM2 流程
-    ↓    约 1 小时
-第 4 步 · 短台词批量生产 (§3.2 batch_tts_voxcpm.py)
-    ↓    约 3-4 小时
-第 5 步 · 长戏分段录制 (§3.3)
-    ↓    约 2-3 小时
-第 6 步 · 后期处理 (§4)
-    ↓    约 2-3 小时
-第 7 步 · 铃声 + 音乐 (§5)         ← 可与 TTS 并行
-    ↓    约 3 小时
-第 8 步 · 音效 (§6)                ← 可与 TTS 并行
-    ↓    约 3 小时
-第 9 步 · 环境底噪 (§7)            ← 可与 TTS 并行
-    ↓    约 2 小时
-第 10 步 · QA 验收 (§8)
-    ↓    约 4-6 小时
-第 11 步 · 最终打包 (§4.5)
-    ↓    约 30 分钟
-完成
+✅ 第 1 步 · 部署 VoxCPM2（/home/xsl/tts-server，端口 8002）
+✅ 第 2 步 · Voice Design 试听 → 选定 13 角色参考 wav（v4）
+✅ 第 3 步 · v5 全量克隆 + 部署 audio/mp3/tts/（04_gen_tts_clone.py）
+✅ 第 4 步 · BGM / 铃声 / 音效 / 环境音（ACE-Step → audio/mp3/）
+✅ 第 5 步 · 清理未引用音频（184 文件与游戏对齐）
+⬜ 第 6 步 · Playtest 听感迭代 + QA（§8）
 ```
 
+**重跑 TTS**（改参考或表演修饰后）：
+
+```bash
+VOXCPM_PORT=8002 python audio_2/scripts/04_gen_tts_clone.py --force
+```
+
+详细目录与命令见 `audio_2/项目状态说明.md`。
+
 ---
 
 ## 附录 A · 常见问题