初步框架

docs/技术报告_音频资源制作.md

@@ -0,0 +1,269 @@
+# 音频资源制作技术落地报告
+
+> 调研日期：2026-05-20  
+> 最后更新：2026-05-20（新增 Stable Audio 部署完成状态）  
+> 硬件环境：NVIDIA RTX 5090 (32GB VRAM) / CUDA Driver 12.9 / WSL2 Linux
+
+---
+
+## 一、本机已有能力总览
+
+| 能力域 | 工具 | 状态 | 环境 |
+|--------|------|------|------|
+| TTS 语音合成 | VoxCPM2 | **运行中** (port 8000) | Python 3.13 venv |
+| TTS 语音合成 | CosyVoice2-0.5B | 已部署，需手动启动 | conda cosyvoice |
+| 音乐/铃声生成 | ACE-Step 1.5 | 已部署，需手动启动 | conda acestep |
+| 音效/氛围生成 | ACE-Step 1.5 | 同上 | conda acestep |
+| 音效/氛围生成 | **Stable Audio Open 1.0** | **已部署** ✅ | conda stableaudio / torch 2.8.0+cu128 |
+| 语音识别 (ASR) | SenseVoice Small | 模型已缓存 | HuggingFace cache |
+| 语音识别 (ASR) | Whisper Tiny | 模型已缓存 | HuggingFace cache |
+| 轻量 TTS | Kokoro-82M | 模型已缓存 | HuggingFace cache |
+| 音频处理 | ffmpeg 7.0.2 | 可用 | 系统 PATH |
+| 音频分析 | librosa / soundfile / pydub | 可用 | pip |
+| 音视频同步 | MuseTalk / LatentSync | 已部署 | conda 环境 |
+
+### 当前产出数据 (《林夏》项目)
+
+| 类型 | 数量 | 生成工具 |
+|------|------|----------|
+| TTS 对话语音 | 216 条 (mp3/tts/) | VoxCPM2 |
+| BGM 背景音乐 | 4 轨 (90s/30s/120s/120s) | ACE-Step 1.5 |
+| 角色铃声 | 9 条 | ACE-Step 1.5 |
+| 音效 | 18 条 | ACE-Step 1.5 |
+| 环境氛围 | 6 条 | ACE-Step 1.5 |
+| 总计 MP3 | 372 个文件 | — |
+
+---
+
+## 二、各能力域详细分析
+
+### 2.1 TTS 语音合成
+
+#### 本机已有
+
+| 工具 | 模型大小 | VRAM | 中文质量 | 声音克隆 | 延迟 | 特点 |
+|------|---------|------|---------|---------|------|------|
+| **VoxCPM2** | 4.7GB | ~6GB | A | 零样本 (5-30s参考音频) | ~1s/句 | FastAPI 服务，REST API，48kHz WAV 输出，带降噪器 |
+| **CosyVoice2-0.5B** | 5.3GB | ~8GB | A+ | 零样本 | ~2s/句 | WebUI，多语言，语速可控，阿里开源 |
+| **Kokoro-82M** | <200MB | <2GB (可CPU) | B (中文社区扩展) | 不支持 | <0.3s | 超轻量，英文为主，适合实时场景 |
+| **Edge-TTS** | 0 (云端) | 0 | B+ | 不支持 | 网络延迟 | 微软在线服务，免费，多音色 |
+
+**当前主链路**：VoxCPM2 为主 → CosyVoice2 为备 → Edge-TTS 为最终兜底
+
+#### 推荐部署到本地
+
+| 工具 | Stars | 模型大小 | VRAM | 为什么值得部署 | 部署难度 |
+|------|-------|---------|------|--------------|---------|
+| **F5-TTS** | 14.5k | ~3GB | 8GB | Flow-matching 架构；零样本克隆质量最高；MIT 开源 | 低 (pip install) |
+| **ChatTTS** | 39k | ~2GB | 4GB | 专为对话设计；自然笑声/停顿/语气词；适合互动叙事 | 低 (pip install) |
+
+**部署优先级建议**：
+1. **ChatTTS** — 对话自然度最高，适合即兴/随机对白生成
+
+#### 线上服务
+
+| 服务 | 中文质量 | 声音克隆 | 延迟 | 价格 | 适用场景 |
+|------|---------|---------|------|------|---------|
+| **MiniMax Speech 2.8** | S | 支持 (30s参考) | <250ms | 按字符计费 | 实时语音交互、低延迟场景 |
+| **豆包 TTS 2.0** (字节) | S | 支持 (Seed-ICL) | ~1s | 火山引擎计费 | 中文情感表达最强，指令控制情绪 |
+| **通义 TTS** (阿里) | A+ | 支持 (CosyVoice) | 标准 | 免费试用额度 | 与本机 CosyVoice 生态互通 |
+| **ElevenLabs** | A | 专业级 | ~100ms | $5-99/月 | 多语言、API 最成熟、配套 SFX |
+| **百度语音合成** | A | 有限 | 标准 | Token 计费 | 最老牌、REST 接入最简单 |
+
+---
+
+### 2.2 音乐制作
+
+#### 本机已有
+
+| 工具 | 模型大小 | VRAM | 能力 | 当前产出 |
+|------|---------|------|------|---------|
+| **ACE-Step 1.5** | 9.4GB (60个checkpoint) | ~8GB | 文本→音乐/铃声/氛围；支持歌词+人声；20s 生成 4 分钟音频；seed 可复现 | 4轨 BGM + 9 条铃声 |
+
+**当前配置**：已针对 RTX 5090 修复 cuBLAS 兼容性 (`cublaslt`)，turbo 模式。
+
+#### 推荐部署到本地
+
+| 工具 | Stars | VRAM | 为什么值得部署 | 适用场景 |
+|------|-------|------|--------------|---------|
+| **DiffRhythm 2** | 新项目 | ~8GB | 最快：10 秒生成 4:45 歌曲；精确歌词对齐；Latent Diffusion 架构 | 快速迭代 BGM 候选 |
+| **YuE (乐)** | Apache 2.0 | 8GB(量化)-80GB(全) | 双 LLaMA 架构；完整歌曲（人声+伴奏同步）；最接近 Suno 的开源方案 | 需要完整歌曲（含唱） |
+| **MusicGen (Meta)** | CC BY-NC | ~12GB fp16 | 研究级纯器乐生成；立体声输出；Loop 素材可控性强 | 纯器乐 BGM / 素材 |
+| **Stable Audio Open 1.5** | 已 clone | ~12GB | 47s 立体声 44.1kHz；SFX 和音乐兼顾；代码已在本机 | 音效与短音乐片段 |
+
+**部署优先级建议**：
+1. **Stable Audio Open 1.5** — 代码已在本机 (`/home/xsl/tools/stable-audio-tools/`)，只需下载模型权重 + `pip install`，马上可用
+2. **DiffRhythm 2** — 速度碾压 ACE-Step，适合大量迭代试听
+3. **YuE** — 32GB VRAM 可跑量化版，适合需要有歌词人声的完整歌曲
+
+#### 线上服务
+
+| 服务 | 人声 | 中文歌词 | 时长 | 价格 | 特点 |
+|------|------|---------|------|------|------|
+| **Suno v5** | 有 | 支持 | ~4min | 免费 300 首/月 | 品质最高；版权诉讼风险 |
+| **Udio** | 有 | 支持 | ~4min | 免费额度 | 与 Suno 竞品；已暂停下载功能 |
+| **网易天音** | 有 | 中文原生 | 可变 | 按需 | 国内平台，版权更清晰 |
+
+---
+
+### 2.3 音效生成
+
+#### 本机已有
+
+| 工具 | 能力 | 当前产出 |
+|------|------|---------|
+| **ACE-Step 1.5** | 氛围类音效 (>=5s)：心跳、呼吸、雨声、敲门、猫叫、水壶、环境氛围等 | 18 条 SFX + 6 条氛围 |
+| **ffmpeg** | 后期处理：混音叠加、底噪叠加、格式转换、音量调节 | 全流程 |
+| **Web Audio API** (游戏内) | 13 种 UI 短音效：合成叮/咚/滴/滑动音，无需外部文件 | 实时合成 |
+
+**限制**：ACE-Step 擅长氛围/音乐类音效，不擅长短促精确的 UI 音效（<1s 的 click/beep）。
+
+#### 推荐部署到本地
+
+| 工具 | VRAM | 为什么值得部署 | 适用场景 |
+|------|------|--------------|---------|
+| **Stable Audio Open 1.5** | ~12GB | 音效生成品质最高的开源方案；44.1kHz 立体声；47s 时长 | 高品质 Foley、环境音 |
+| **AudioLDM 2** | 8-16GB | 全能型（SFX + 音乐 + 语音）；48kHz；多种模型尺寸 | 短音效、过渡音 |
+
+**部署优先级建议**：
+1. **Stable Audio Open 1.5** — 同上，已有代码，补模型即可
+2. **AudioLDM 2** — pip 安装，轻量推理，适合补充短促音效
+
+#### 线上服务
+
+| 服务 | 时长上限 | 价格 | 特点 |
+|------|---------|------|------|
+| **ElevenLabs SFX v2** | 30s | 免费额度 | 制作级品质，支持循环，版税免费 |
+| **Stable Audio 2.5** (API) | 3min | 按量 | 音频修复/inpainting，商业安全 |
+
+---
+
+### 2.4 语音克隆 / 变声
+
+#### 本机已有
+
+VoxCPM2 和 CosyVoice2 均内置零样本声音克隆。当前《林夏》项目已为 12 个角色建立参考音频库：
+
+```
+voice/
+  linxia/    linxia_ref.wav
+  mom/       mom_extra_04.wav
+  azhe/      azhe_extra_05.wav
+  xiaomei/   ...
+  zhounan/   delivery/   hr/   anan/
+  dorm_a/    dorm_b/     dorm_c/
+```
+
+#### 推荐部署到本地
+
+| 工具 | Stars | 为什么值得 | 适用场景 |
+|------|-------|----------|---------|
+| **OpenVoice V2** | 36k | 单条音频秒级克隆；跨语言（克隆英文声 → 输出中文）| 快速原型、临时角色 |
+| **RVC v2** | 36k | 实时变声；10 分钟数据可训练；社区模型库庞大 | 歌声转换、直播变声 |
+| **Seed-VC** | 新 | 零样本相似度最高；解决音色泄漏问题；支持唱歌 | 高精度声音复刻 |
+
+**部署优先级**：Seed-VC > OpenVoice V2
+
+---
+
+### 2.5 语音识别 (ASR) — 辅助能力
+
+| 工具 | 状态 | 用途 |
+|------|------|------|
+| **SenseVoice Small** | 模型已缓存 | 中文 ASR，可用于语音标注、字幕生成 |
+| **Whisper Tiny** | 模型已缓存 | 多语言 ASR 兜底 |
+
+---
+
+## 三、推荐部署路线图
+
+### ✅ 已完成部署（2026-05-20）
+
+| 序号 | 工具 | 路径 | 模型 | torch |
+|------|------|------|------|-------|
+| 1 | **Stable Audio Open 1.0** | `/home/xsl/tools/stable-audio-tools/` | `/home/xsl/models/stable-audio-open/` | 2.8.0+cu128 (stableaudio) |
+
+**注：全部使用 CUDA 12.8 编译版 torch，支持 RTX 5090 (sm_120)**。  
+PyTorch wheel 来源：`https://mirrors.aliyun.com/pytorch-wheels/cu128/`
+
+#### 启动命令
+
+```bash
+# Stable Audio Open — Gradio WebUI
+conda activate stableaudio
+cd /home/xsl/tools/stable-audio-tools
+python run_gradio.py \
+  --model-config /home/xsl/models/stable-audio-open/model_config.json \
+  --ckpt-path /home/xsl/models/stable-audio-open/model.safetensors
+```
+
+### 下一优先级 — 待部署
+
+| 序号 | 工具 | 操作 | 预计耗时 | VRAM |
+|------|------|------|---------|------|
+| 4 | **ChatTTS** | `pip install ChatTTS` → 下载模型 | 30min | 4GB |
+
+### 按需部署
+
+| 序号 | 工具 | 场景 |
+|------|------|------|
+| 5 | **DiffRhythm 2** | 需要快速迭代大量 BGM 候选时 |
+| 6 | **AudioLDM 2** | 需要精确短音效生成时 |
+| 7 | **YuE** | 需要完整中文歌曲（人声+伴奏）时 |
+| 8 | **OpenVoice V2** | 需要快速跨语言声音克隆时 |
+
+---
+
+## 四、能力矩阵
+
+```
+                    本机已有              待部署            线上服务
+                ┌───────────────┐  ┌────────────┐  ┌────────────┐
+   TTS          │ VoxCPM2       │  │ ChatTTS    │  │ MiniMax    │
+   语音合成     │ CosyVoice2    │  │ F5-TTS     │  │ 豆包 TTS   │
+                │ Kokoro-82M    │  │            │  │ ElevenLabs │
+                │               │  │            │  │ 通义 TTS   │
+                └───────────────┘  └────────────┘  └────────────┘
+                ┌───────────────┐  ┌────────────┐  ┌────────────┐
+   音乐生成     │ ACE-Step      │  │ DiffRhythm │  │ Suno v5    │
+                │               │  │ YuE        │  │ Udio       │
+                │               │  │ MusicGen   │  │            │
+                └───────────────┘  └────────────┘  └────────────┘
+                ┌───────────────┐  ┌────────────┐  ┌────────────┐
+   音效生成     │ ACE-Step      │  │ AudioLDM 2 │  │ ElevenLabs │
+                │ StableAudio ✅│  │            │  │ StableAudio│
+                │ Web Audio     │  │            │  │ API        │
+                │ ffmpeg        │  │            │  │            │
+                └───────────────┘  └────────────┘  └────────────┘
+                ┌───────────────┐  ┌────────────┐  ┌────────────┐
+   声音克隆     │ VoxCPM2       │  │ Seed-VC    │  │ ElevenLabs │
+                │ CosyVoice2    │  │ OpenVoice  │  │ MiniMax    │
+                │               │  │ RVC v2     │  │ 豆包       │
+                └───────────────┘  └────────────┘  └────────────┘
+                ┌───────────────┐
+   ASR          │ SenseVoice    │  (辅助能力，非生产主线)
+   语音识别     │ Whisper       │
+                └───────────────┘
+```
+
+---
+
+## 五、VRAM 并行策略
+
+RTX 5090 (32GB) 可同时运行的组合：
+
+| 组合 | 占用 VRAM | 场景 |
+|------|----------|------|
+| VoxCPM2 (6G) + ACE-Step (8G) | ~14GB | TTS + 音乐同时生产 |
+| VoxCPM2 (6G) + Stable Audio (12G) | ~18GB | TTS + 高品质音效 |
+| CosyVoice2 (8G) + ChatTTS (4G) | ~12GB | 双 TTS 引擎对比试听 |
+| 单独 YuE 量化版 | ~8-24GB | 完整歌曲生成（独占） |
+
+---
+
+## 六、针对《林夏》项目的升级建议
+
+| 现状 | 升级方案 | 收益 |
+|------|---------|------|
+| ACE-Step 生成全部音效 | → Stable Audio Open 1.5 补充精细音效 | 44.1kHz 立体声，电话底噪/UI 音效品质更高 |
+| 结局仅语音 + 字幕 | → ACE-Step/DiffRhythm 生成结局专属 BGM | 5 个结局各有独立氛围音乐，沉浸感提升 |

docs/策划案任务拆分.md

@@ -0,0 +1,173 @@
+# 仙侠纯听觉MUD游戏 — 策划案任务拆分
+
+> 创建日期：2026-05-21  
+> 修订日期：2026-05-21  
+> 状态：修订完成（技术架构前置至第一层，AI游历修士明确标识为NPC）
+
+---
+
+## 项目概览
+
+| 项目 | 说明 |
+|------|------|
+| 类型 | 纯听觉交互手机游戏（屏幕全黑） |
+| 题材 | 仙侠 |
+| 参考 | 传统 MUD 游戏 |
+| 平台 | 纯 HTML5（浏览器运行） |
+| 操作 | 上滑、下滑、左滑、右滑、单击、双击（共6种手势） |
+| 输出 | 语音播报 + 音效 + 环境氛围音乐（无视觉元素） |
+| 战斗 | 回合制 |
+| 联机 | 大型MUD在线世界，支持PvP/PvE/副本，低人数时游历修士NPC填充 |
+| 商业模式 | 纯免费 |
+| 玩法 | 主线剧情 + 自由探索/修炼 |
+| 语音策略 | 预生成 + 按需生成 + 播报时拼装 |
+
+---
+
+## 任务拆分
+
+策划案共分为 **14 个模块**，按依赖关系分为 4 层。
+
+> **关键原则**：技术架构前置。手势识别、音频引擎、WebSocket 协议、资源缓存、服务端权威状态等技术约束会反过来决定玩法能否成立，因此必须与基础设计同层确定。
+
+### 第一层：基础框架 + 技术架构（无依赖，必须最先确定）
+
+#### 任务 1：游戏概述与核心设计理念
+- 游戏定位、目标用户
+- 核心体验描述（"闭眼修仙"的体验承诺）
+- 与传统MUD的异同对比
+- 纯音频游戏的设计原则与约束
+
+#### 任务 2：世界观与背景设定
+- 仙侠世界观框架（天地灵气、修炼体系的宏观设定）
+- 大陆/区域划分
+- 主要势力/门派
+- 时间线与历史大事件
+- 世界运行规则（昼夜、天气、灵气潮汐等）
+
+#### 任务 3：交互设计 — 手势映射与UI流转
+- 6 种手势在不同场景下的功能映射表（严格6种，不引入长按等额外手势）
+- 场景上下文切换逻辑（探索态、战斗态、菜单态、对话态等）
+- 导航与寻路的音频交互方案
+- 无障碍设计原则
+- 操作容错与撤销机制
+
+#### 任务 4：技术架构概要（从第四层前置）
+- 客户端架构（HTML5 + Web Audio API + WebSocket）
+- 移动浏览器限制调研（后台暂停、音频自动播放策略、内存限制）
+- 服务端架构（游戏逻辑服务 + 音频资源服务）
+- 通信协议设计
+- 数据存储方案
+- 音频资源缓存策略
+- 服务端权威状态设计（离线收益由服务端结算，不依赖客户端持续运行）
+
+### 第二层：核心系统（依赖第一层）
+
+#### 任务 5：角色与修炼系统
+- 角色创建流程（纯音频引导）
+- 基础属性体系（根骨、悟性、灵力等）
+- 修炼境界体系（练气→筑基→金丹→元婴→…）
+- 功法/技能树设计
+- 属性成长与突破机制
+
+#### 任务 6：地图与导航系统
+- 地图数据结构（房间/节点 + 连接，MUD经典模式）
+- 区域设计（新手村、城镇、野外、秘境、副本入口等）
+- 导航语音播报方案（到达/离开/方位描述）
+- 环境氛围音设计（每个区域的声景特征）
+- 随机事件触发机制
+
+#### 任务 7：音频系统设计
+- 音频分层架构（BGM层、氛围层、音效层、语音层）
+- 语音播报规范（播报优先级、队列管理、打断规则）
+- 音效设计清单（按场景/动作分类）
+- BGM设计清单（按区域/情境分类）
+- 语音拼装方案（预生成片段 + 动态拼接规则）
+- 音频资源生产管线（对接本机 TTS/音乐/音效工具链）
+
+### 第三层：玩法系统（依赖第二层）
+
+#### 任务 8：战斗系统
+- 回合制战斗流程（纯音频版）
+- 技能/功法在战斗中的使用
+- 战斗音频反馈设计（攻击、防御、闪避、暴击等音效）
+- PvE 怪物设计（种类、AI行为）
+- PvP 对战规则
+- 战斗结算与奖励
+
+#### 任务 9：副本系统
+- 副本类型（单人、组队、公会）
+- 副本结构设计（线性/分支）
+- Boss 机制设计（纯音频下如何传达Boss技能预警）
+- 副本奖励与难度分级
+- 组队匹配机制
+
+#### 任务 10：任务与剧情系统
+- 主线剧情大纲
+- 支线任务类型（日常、悬赏、奇遇、门派）
+- 任务追踪与播报方式
+- 剧情分支与选择机制
+- NPC对话系统（对话树 + 语音播报）
+
+#### 任务 11：经济与物品系统
+- 货币体系（灵石、贡献点等）
+- 物品分类（装备、丹药、材料、法宝）
+- 装备系统（穿戴、强化、品质）
+- 交易系统（玩家间交易、NPC商店）
+- 背包管理的音频交互方案
+
+### 第四层：社交与运营（依赖第三层）
+
+#### 任务 12：多人社交系统
+- 玩家登录与账号系统
+- 好友系统
+- 门派/公会系统
+- 聊天系统（文字转语音播报）
+- 玩家间互动（切磋、交易、组队）
+
+#### 任务 13：AI游历修士系统（原"机器人"）
+- 游历修士行为模型（巡逻、修炼、社交、战斗）
+- 游历修士人格与对话风格
+- 动态填充策略（根据在线人数调节数量）
+- 游历修士明确标识为NPC，不伪装真人玩家
+- 与真实玩家的交互规则
+
+#### 任务 14：内容生产管线与版本规划
+- 音频资源生产流程（TTS → 音效 → BGM → 拼装 → 质检）
+- 对接本机工具链的具体方案
+- MVP版本范围定义
+- 后续版本迭代路线图
+
+---
+
+## 依赖关系图
+
+```
+第一层（并行）               第二层（并行）        第三层（并行）         第四层（并行）
+┌──────────┐             ┌──────────┐        ┌──────────┐        ┌──────────┐
+│ 1.游戏概述 │──┬────────→│ 5.角色修炼 │───┬──→│ 8.战斗系统 │───┬──→│12.社交系统 │
+└──────────┘  │          └──────────┘   │    └──────────┘   │    └──────────┘
+┌──────────┐  │          ┌──────────┐   │    ┌──────────┐   │    ┌──────────┐
+│ 2.世界观   │──┼────────→│ 6.地图导航 │───┼──→│ 9.副本系统 │───┼──→│13.AI游历修士│
+└──────────┘  │          └──────────┘   │    └──────────┘   │    └──────────┘
+┌──────────┐  │          ┌──────────┐   │    ┌──────────┐   │    ┌──────────┐
+│ 3.交互设计 │──┼────────→│ 7.音频系统 │───┘──→│10.任务剧情 │───┘──→│14.生产管线 │
+└──────────┘  │          └──────────┘        └──────────┘        └──────────┘
+┌──────────┐  │                              ┌──────────┐
+│ 4.技术架构 │──┘                              │11.经济物品│
+│  (前置!)   │                               └──────────┘
+└──────────┘
+```
+
+> **变更说明**：技术架构从第四层提升至第一层。手势识别、音频引擎、WebSocket协议、移动浏览器限制等技术约束会直接决定玩法设计能否落地，必须前置验证。
+
+---
+
+## 输出标准
+
+每个任务模块在策划案中应包含：
+1. **设计目标** — 该模块要解决什么问题
+2. **详细设计** — 具体规则、数值、流程
+3. **音频需求清单** — 该模块需要哪些语音/音效/BGM资源
+4. **交互流程** — 玩家操作手势 → 系统响应音频 的完整流转
+5. **边界条件** — 异常情况处理（网络延迟、操作冲突等）