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

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

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

林夏.md

@@ -552,70 +552,99 @@ E（隐藏，优先级 1）→ A（优先级 2）→ B（优先级 3）→ C（
 | **林夏语音** | 主角对话回应（通用 + 专属） | ~55 条, ~100s | VoxCPM2 声音克隆 |
 | **NPC Round 1 语音** | 各角色主要台词 | ~30 条, ~300s | VoxCPM2 声音克隆 |
 | **NPC Round 2/3 反应** | 对话分支反应 | ~54 条, ~205s | VoxCPM2 声音克隆 |
-| **self-3y 三版** | 时光胶囊备忘录 ×3 | 3 条, ~150s | VoxCPM2（linxia 音色） |
+| **self-3y 三版** | 时光胶囊备忘录 ×3 | 3 条, ~150s | VoxCPM2（`self_3y_v03` 独立参考） |
 | **UI 短音效** | 提示音、选择反馈、打字/发送 | ~12 种 | Web Audio 合成（无需文件） |
-| **BGM** | 4 段主题音乐 | 4 段 | Suno / Udio 生成 |
-| **环境音** | 卧室夜噪、酒吧、街声 | 4-5 段 | Freesound (CC0/CC-BY) |
-| **角色铃声** | 来电铃声 | 3-4 段 | 简单合成或 Suno 短旋律 |
+| **BGM** | 4 段主题音乐 | 4 轨 | ACE-Step 1.5 本地生成 |
+| **环境音** | 卧室夜噪、厨房、黎明等 | 3 段 | ACE-Step 1.5 本地生成 |
+| **角色铃声** | 来电铃声 | 5 条（游戏引用 4 种场景） | ACE-Step 1.5 本地生成 |
+| **叙事音效** | 敲门、心跳、呼吸、水壶等 | 4 条 | ACE-Step 1.5 本地生成 |
 
-### 7.2 TTS 方案：VoxCPM2 本地声音克隆（唯一主链路）
+### 7.2 TTS 方案：VoxCPM2 本地克隆（现行 v5 链路）
 
-> **注意**：本项目 TTS 统一使用 **VoxCPM2**。`执行文档_音频素材制作.md` 中早期记录的 CosyVoice2 方案作为备用，不作为主生产链路。批量脚本、音色目录、QA 标准均以 VoxCPM2 为准。
+> **注意**：本项目 TTS 统一使用 **VoxCPM2**。CosyVoice2 仅作备用，不作为主生产链路。  
+> **详细操作与目录**：见 `audio_2/项目状态说明.md`、`执行文档_音频素材制作.md`。
 
-所有角色语音使用 **VoxCPM2**（本地部署，无需外部 API），通过声音克隆实现一致的角色音色。
+**现行流程**（2026-05 落地）：
+
+```
+Voice Design 试听（v4，每角色 5 条提示词变体）
+  → 人工选定参考 wav
+  → Style Control 克隆 + 表演修饰（v5）
+  → 部署到 audio/mp3/tts/*_wav_v1.mp3（游戏直接加载）
+```
+
+**服务启动**（端口 **8002**，8000 被其他服务占用）：
 
-**服务启动**：
 ```bash
-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
+curl http://127.0.0.1:8002/health
+# 预期: {"status":"ok","model":"VoxCPM2","styled_speech":true}
 ```
 
 **API 接口**：
-- `POST /v1/voices` — 注册参考音频（wav_base64）→ 返回 voice_id
-- `POST /v1/speech` — 合成语音（text + voice_id）→ 返回 WAV
+
+| 接口 | 用途 |
+|------|------|
+| `POST /v1/voices` | 注册参考音频（wav_base64）→ voice_id |
+| `POST /v1/speech` | 纯克隆合成（text + voice_id） |
+| `POST /v1/speech/styled` | Style Control：有 voice_id = 克隆+表演；无 voice_id = Voice Design |
+
 - 输出格式：48kHz 16-bit PCM WAV
 - 参数：cfg_value（默认 2.0）、inference_timesteps（默认 10）
 
-**声音克隆流程**：
-```
-参考音频 (voice/{角色}/*.wav)
-  → 转换为 16kHz mono WAV
-  → POST /v1/voices 注册 → voice_id
-  → POST /v1/speech 合成台词 → WAV
-  → ffmpeg atempo 调速 → 最终音频
+**批量生产（现行）**：
+
+```bash
+# 全量克隆并部署游戏目录
+VOXCPM_PORT=8002 python audio_2/scripts/04_gen_tts_clone.py --force
+
+# 只重跑某角色
+VOXCPM_PORT=8002 python audio_2/scripts/04_gen_tts_clone.py --role mom --force
+
+# 重新生成试听样本（换提示词挑音色）
+VOXCPM_PORT=8002 python audio_2/scripts/03_gen_voice_samples.py --role delivery --force
 ```
 
+**游戏音频命名**：仅 `*_wav_v1.mp3` 被 `story.js` / `engine.js` 引用；`*_mp3_v1.mp3` 为旧流水线产物，已清理。
+
 ### 7.3 角色音色配置
 
-| 角色 | 参考音频目录 | 语速 | 音色描述 |
-|------|-------------|------|---------|
-| **林夏** | `voice/linxia/` | 1.00 | 24 岁女生，疲惫但清醒，克制但有温度 |
-| 妈妈 | `voice/mom/` | 0.92 | 50 上下，温柔不黏腻，西部口音轻微 |
-| 阿哲 | `voice/azhe/` | 1.05 | 27 岁，城市男生，理性偏冷 |
-| 小美 | `voice/xiaomei/` | 1.10 | 24 岁，活泼，语速快 |
-| 小美（醉） | `voice/xiaomei/` | 0.95 | 同音色，降速模拟醉态 |
-| 周南 | `voice/zhounan/` | 0.95 | 26 岁，温和略拘谨 |
-| HR 王姐 | `voice/hr/` | 1.00 | 38 岁，职场化，疲惫的善意 |
-| 安安 | `voice/anan/` | 1.15 | 23 岁，活泼，比小美更嗲 |
-| 室友 A | `voice/dorm_a/` | 1.10 | 年轻女声，兴奋 |
-| 室友 B | `voice/dorm_b/` | 1.00 | 年轻女声，随和 |
-| 室友 C | `voice/dorm_c/` | 0.95 | 年轻女声，温柔 |
-| 外卖小哥 | `voice/delivery/` | 1.20 | 30 岁，麻利 |
-| self-3y | `voice/linxia/` | 1.15 | 3 年前的林夏，更明朗（同一音色，不同语速） |
+参考音频来自 Voice Design 试听选定，存放在 `voice/{角色}/{角色}_ref.wav` 与 `audio_2/tts/v4_voice_samples/{角色}/`。
 
-### 7.4 批量合成脚本
+| 角色 | 参考文件 | 目录 | 语速 | 音色描述 |
+|------|----------|------|------|---------|
+| **林夏** | `linxia_v05.wav` | `voice/linxia/` | 1.00 | 24 岁女生，疲惫但清醒，克制但有温度 |
+| 妈妈 | `mom_v01.wav` | `voice/mom/` | 0.92 | 50 上下，温柔不黏腻，西部口音轻微 |
+| 阿哲 | `azhe_v03.wav` | `voice/azhe/` | 1.05 | 27 岁男声，城市男生，理性偏冷 |
+| 小美 | `xiaomei_v05.wav` | `voice/xiaomei/` | 1.10 | 24 岁，活泼，语速快 |
+| 小美（醉） | `xiaomei_drunk_v05.wav` | `voice/xiaomei/` | 0.95 | 同闺蜜基底，降速模拟醉态 |
+| 周南 | `zhounan_v05.wav` | `voice/zhounan/` | 0.95 | 26 岁男声，温和略拘谨 |
+| HR 王姐 | `hr_v05.wav` | `voice/hr/` | 1.00 | 38 岁，职场化，疲惫的善意 |
+| 安安 | `anan_v04.wav` | `voice/anan/` | 1.15 | 23 岁，活泼，比小美更嗲 |
+| 室友 A | `dorm_a_v03.wav` | `voice/dorm_a/` | 1.10 | 年轻女声，兴奋 |
+| 室友 B | `dorm_b_v02.wav` | `voice/dorm_b/` | 1.00 | 年轻女声，随和 |
+| 室友 C | `dorm_c_v03.wav` | `voice/dorm_c/` | 0.95 | 年轻女声，温柔 |
+| 外卖小哥 | `delivery_v04.wav` | `voice/delivery/` | **1.00** | 30 岁**男声**，北方腔，语速适中 |
+| self-3y | `self_3y_v03.wav` | `voice/linxia/` | 1.15 | 3 年前的林夏，更年轻明亮（独立参考，非复用小美） |
+
+表演修饰（warm/cold/分段等）由 `audio_2/voice_style_prompts.py` 的 `get_clone_style()` 控制；音色本身由参考 wav 锚定。
+
+### 7.4 脚本与产物目录
+
+| 脚本 | 用途 | 输出 |
+|------|------|------|
+| `audio_2/scripts/03_gen_voice_samples.py` | v4 试听（每角色 5 条） | `audio_2/tts/v4_voice_samples/` |
+| `audio_2/scripts/04_gen_tts_clone.py` | **v5 全量克隆 + 部署** ★ | `audio_2/tts/v5_cloned/*_wav_v5.mp3` → `audio/mp3/tts/*_wav_v1.mp3` |
+| `audio/batch_tts_voxcpm.py` | 台词表 `LINES`（173 条）+ 语速配置 | 旧版直连克隆，已被 v5 替代 |
+| `audio_2/voice_style_prompts.py` | 表演修饰 / Voice Design 提示词 | — |
+| `audio_2/voice_sample_prompts.py` | v4 试听变体与统一试听文本 | — |
+
+**台词表**：`audio/batch_tts_voxcpm.py` 中 `LINES` + `04_gen_tts_clone.py` 中 `EXTRA_LINES`（self-3y ×3、系统 memo）。
+
+**配置与文档**：
 
 ```bash
-# 启动 VoxCPM2 服务
-bash /home/xsl/AutoVideo/start-voxcpm.sh
-
-# 使用 WAV 参考音色，批量合成所有台词
-python audio/batch_tts_voxcpm.py --source voice
-
-# 只合成特定角色
-python audio/batch_tts_voxcpm.py --source voice --role linxia
-
-# 干跑查看任务列表
+# 旧版批量（仅参考，不再用于正式产出）
 python audio/batch_tts_voxcpm.py --source voice --dry-run
 ```
 
@@ -815,14 +844,13 @@ async _handleChoice(dir) {
 | self-3y | 3 版 | 0 | ~3 条 | ~150s |
 | **合计** | | | **~90 条** | **~835s** |
 
-### 总计
+### 总计（现行部署）
 
-- 林夏 ~55 条，~100 秒
-- NPC ~90 条，~835 秒
-- **总语音约 145 条，约 15.5 分钟**
+- 游戏引用 **184** 个 MP3（`audio/mp3/`，已与 `story.js` / `engine.js` 对齐）
+  - TTS 对白 **169** 条（`tts/*_wav_v1.mp3`）
+  - BGM + 铃声 **8** 条 · 音效 **4** 条 · 环境音 **3** 条
+- v5 克隆产物归档 **177** 条（`audio_2/tts/v5_cloned/`，含台词表全量 + self-3y + 系统 memo）
 - UI 音效：13 种，全部 Web Audio 合成
-- BGM：4 段
-- 环境音：4-5 段
 
 ---
 
@@ -831,39 +859,35 @@ async _handleChoice(dir) {
 ```
 blind/
 ├── game/
-│   ├── index.html          # 入口
+│   ├── index.html
 │   └── js/
-│       ├── main.js         # 启动 + 事件绑定
-│       ├── gestures.js     # 7 种手势识别（含长按）
-│       ├── haptics.js      # 触觉反馈
+│       ├── story.js        # 16 条消息 + 音频引用（*_wav_v1.mp3）
+│       ├── engine.js       # 系统语音、结局、BGM/环境音
 │       ├── audio.js        # 音频管理 + UI 合成音效
-│       ├── story.js        # 16 条消息剧情数据
-│       ├── engine.js       # 游戏引擎（状态机 + 对话流程）
-│       ├── profile.js      # 行为画像 + 状态变量
-│       └── utils.js        # 工具函数（sleep, dbg 等）
+│       └── …
 ├── audio/
-│   ├── mp3/
-│   │   ├── linxia/         # 林夏语音（当前 edge-tts 版本）
-│   │   └── react/          # NPC 反应语音（当前 edge-tts 版本）
-│   ├── 00_raw/tts/         # VoxCPM2 生成原始 WAV
-│   └── batch_tts_voxcpm.py # VoxCPM2 批量合成脚本
-├── voice/                   # VoxCPM2 参考音色（WAV）
-│   ├── linxia/             # 林夏
-│   ├── mom/                # 妈妈
-│   ├── azhe/               # 阿哲
-│   ├── xiaomei/            # 小美
-│   ├── zhounan/            # 周南
-│   ├── hr/                 # HR 王姐
-│   ├── anan/               # 安安
-│   ├── dorm_a/             # 室友 A
-│   ├── dorm_b/             # 室友 B
-│   ├── dorm_c/             # 室友 C
-│   └── delivery/           # 外卖小哥
-├── gdd/
-│   └── redesign_v2.md      # v2 重构设计文档
-└── 林夏.md                  # 本文档（总设计纲要）
+│   ├── batch_tts_voxcpm.py # 台词表 LINES + ROLES 语速
+│   └── mp3/                # 游戏运行时音频（184 文件）
+│       ├── tts/            # 169 条对白
+│       ├── music/          # BGM + 铃声
+│       ├── sfx/            # 叙事音效
+│       └── ambience/       # 环境音
+├── voice/                  # 各角色参考音频（v5 选定 *_ref.wav）
+├── audio_2/                # TTS v4/v5 流水线
+│   ├── 项目状态说明.md
+│   ├── voice_style_prompts.py
+│   ├── voice_sample_prompts.py
+│   ├── scripts/            # 03 试听 · 04 克隆部署 ★
+│   └── tts/
+│       ├── v4_voice_samples/  # 选定参考音色
+│       └── v5_cloned/         # 正式产物 + clone_manifest.tsv
+├── 林夏.md
+├── 执行文档_音频素材制作.md
+└── 技术报告_音频资源制作.md
 ```
 
+TTS 服务（独立部署）：`/home/xsl/tts-server/`（端口 **8002**）
+
 ---
 
 ## 11. 风险与对策
@@ -871,7 +895,7 @@ blind/
 | 风险 | 对策 |
 |------|------|
 | VoxCPM2 长情绪戏（妈妈 4 分钟）质感不够 | 分段录制 + 后期拼接，预留调参时间 |
-| 声音克隆音色不够区分 | 每角色选择差异大的参考音频 + 调速区分 |
+| 声音克隆音色不够区分 | Voice Design 试听多变体 → 人工选定 → 克隆锚定；男声角色单独标注 |
 | 60+ 分支语音管理复杂 | batch_tts_voxcpm.py 统一管理，命名规范 |
 | 手势误判导致选错 | 滑动阈值 30px + 40°范围；双击间隔 250ms 内 |
 | 玩家不理解手势含义 | MSG-02（小美教学关）强引导，每步正向反馈 |
@@ -902,14 +926,14 @@ blind/
 
 ## 12. 制作流程
 
-| 阶段 | 关键交付 |
-|------|---------|
-| **剧本定稿** | 16 条全脚本 + 5 结局完整对白 + 所有分支台词 |
-| **参考音色准备** | voice/ 下 12 个角色参考音频确认 |
-| **VoxCPM2 批量合成** | ~145 条语音 + 语速调整 + 质检 |
-| **BGM + 环境音** | 4 段 BGM + 环境采样 |
-| **程序集成** | story.js 对接最终音频路径 + 全流程调试 |
-| **测试** | 全 5 结局通关测试 + 分支覆盖 |
+| 阶段 | 关键交付 | 状态 |
+|------|---------|------|
+| **剧本定稿** | 16 条全脚本 + 5 结局完整对白 + 所有分支台词 | ✅ |
+| **参考音色准备** | v4 试听选定 13 角色参考 wav | ✅ |
+| **VoxCPM2 v5 批量合成** | 177 条克隆 + 部署 `audio/mp3/tts/` | ✅ |
+| **BGM + 环境音 + 音效** | ACE-Step 本地生成，游戏引用 15 条 | ✅ |
+| **程序集成** | story.js 对接 `*_wav_v1.mp3` | ✅ |
+| **测试** | 全 5 结局通关 + 各角色听感迭代 | 待 playtest |
 
 ---