本地音频工坊 sukai213/dsh-audio

dsh-audio — DSH 本地音频插件（YuE2 歌曲生成 + Qwen3-TTS 语音克隆）

一个 DeepSeek Harness (DSH) 插件，通过 MCP stdio 将两个完全本地的音频模型作为 agent 工具暴露出来：YuE2-3B（带人声的完整歌曲生成）和 Qwen3-TTS-12Hz-1.7B（语音克隆 / 音色设计）。无需 API key，无需云端，无按次调用费用。

给 DSH 装两个本地音频模型：一句话出一首带人声的歌，和克隆/设计音色念稿。
装完之后直接对 agent 说「生成一首歌」「用这把声音念这段」，不用记命令。

- 🔒 全本地：模型跑在自己机器上，不联网、不花钱、不上传内容
- 🧭 零配置：模型放哪儿都能找到（桌面优先），挪走了下次调用自动重找
- 🧩 零依赖安装：server.py 只用 Python 标准库，不需要 pip install 任何东西
- 🪟 目前只在 Windows 10/11 上验证过（见「平台说明」）

目录

- 能力
- 环境要求
- 安装
- 模型放哪儿
- 用法
- 避坑手册 ← 重点，全是踩出来的
- 排障
- 平台说明
- 许可

能力

插件提供 6 个工具，工具名前缀是 mcp__audio__：

| 工具 | 干什么 | 大概耗时 |
| yue2_song | YuE2-3B 生成整首歌（歌词 + 风格标签 → 带人声的 wav），48kHz 立体声 | 12 秒歌 ≈ 45s；60 秒歌 ≈ 4~5 分钟（CPU） |
| qwen3_tts | Qwen3-TTS 合成语音。mode=clone 克隆音色 / mode=design 用自然语言描述音色，24kHz | 5 秒语音 ≈ 15s（CPU） |
| audio_clip | 从 wav 剪一段并转单声道（给克隆准备参考音） | 秒回 |
| audio_status | 自检：模型在哪找到的、权重齐不齐、内存/显存；rescan=true 强制重扫 | 秒回 |
| audio_play | 系统播放器播放 wav（异步） | 秒回 |
| audio_unload | 卸载常驻内存的 TTS 模型（省约 4.5GB） | 秒回 |

环境要求

| 项 | 要求 | 说明 |
| 系统 | Windows 10/11 x64 | audiocpp_cli.exe 是 win-x64 二进制；audio_play 用 winsound |
| Python | 3.10+ | 只给 server.py 和 Qwen3-TTS 用；YuE2 那条路不 import 任何第三方包 |
| 依赖 | torch(CPU 版即可) qwen-tts transformers librosa soundfile | 只有 TTS 需要。实测 CPU 版 venv 约 1.06GB |
| 内存 | 建议 ≥ 16GB | YuE2 Q8 权重 4GB + arena；本机测试机是 15.2GB，能跑但余量很小 |
| 显存 | 不需要 | 实测全 CPU 更稳；vulkan 后端在有其他程序占显存时会 OOM |
| 磁盘 | YuE2 ≈ 11GB，Qwen3-TTS ≈ 8GB | 见 docs/MODELS.md |

⚠️ 只想要歌曲生成的话，可以完全不装 Python 依赖（torch 那些只被 TTS 用）。
但 server.py 本身仍然需要机器上有一个 Python 3.10+ 来跑。

安装

1. 拿模型

两个都是开源权重的本地模型，本插件不含权重，自己下：

- YuE2-3B GGUF → HuggingFace audio-cpp/Yue2-3B-GGUF
（上游权重 m-a-p/YuE2-3B）。
⚠️ 这是 audio.cpp 原生 GGUF，不是 transformers 权重，必须配 audio.cpp 的 dev 分支（仓库里带编译好的 audio-cpp/ 目录就不用自己编）。
⚠️ 许可 CC BY-NC 4.0，仅限非商业用途。

- Qwen3-TTS-12Hz-1.7B → ModelScope / HuggingFace Qwen/Qwen3-TTS-12Hz-1.7B-Base、 Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign、Qwen/Qwen3-TTS-Tokenizer-12Hz（三个都要）。

文件名、体积、哪些是必需文件见 docs/MODELS.md。

2. 建 Python 环境

py -3.12 -m venv C:\dsh-audio-venv
& C:\dsh-audio-venv\Scripts\python.exe -m pip install -U pip
CPU 版 torch 就够（约 200MB，CUDA 版 3GB 起，本插件用不上） & C:\dsh-audio-venv\Scripts\python.exe -m pip install torch torchaudio --index-url https://download.pytorch.org/whl/cpu & C:\dsh-audio-venv\Scripts\python.exe -m pip install qwen-tts transformers librosa soundfile

3. 放插件

git clone https://github.com/sukai213/dsh-audio.git %USERPROFILE%\dsh-plugins\dsh-audio

放哪儿都行，只要 profile 里的路径对得上。

4. 挂进 DSH profile

编辑 ~/.dsh/profiles//cordis.patch.yml，加一段 - insert:： yaml
- insert:
- id: mcp-audio
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: audio # 工具名前缀 mcp____ transport: stdio command: 'C:\dsh-audio-venv\Scripts\python.exe' # ← 第 2 步建的 venv，绝对路径
args: ['C:\Users\你\dsh-plugins\dsh-audio\server.py'] # ← 第 3 步 clone 的位置，绝对路径
toolCallTimeoutMs: 3600000 # 必须放大！生成一首歌要几分钟，默认 60s 必超时 env: PYTHONUTF8: '1' PYTHONIOENCODING: 'utf-8' DSH_AUDIO_OUT: 'D:\audio-out' # 可选：默认输出目录

也可以直接跑仓库里的一键脚本（幂等、自动备份、尽量校验 YAML）： powershell .\install.ps1 -VenvPython 'C:\dsh-audio-venv\Scripts\python.exe'

5. 重启 DSH Desktop

profile 只在宿主启动时读，必须重启，重启后新会话才看得到 mcp__audio__ 工具。

6. 验证 powershell & C:\dsh-audio-venv\Scripts\python.exe .\test_client.py audio_status "{}"

看到 "found": true 两个模型就对了。

模型放哪儿

不用配路径。 插件每次调用都会校验上次找到的目录是否还有效，失效就重新扫描，所以模型挪走 / 换机器 / 重新下载之后不用重启 DSH，下次调用自动找到。

扫描顺序（先命中先用）：

1. 环境变量 DSH_YUE2_ROOT / DSH_QWEN_TTS_ROOT（可以直接指目录，也可以指它的上级）
2. %USERPROFILE%\Desktop（往下 3 层）← 桌面优先
3. Desktop\AI工作区 → %USERPROFILE%\AI工作区 → D:\AI工作区 → E:\语音模型
4. %USERPROFILE%
5. 各盘根目录（D/E/F/G 先于 C），往下 3 层

判定标准：

- YuE2：目录里同时有 audio-cpp\audiocpp_cli.exe 和 yue2-.gguf
- Qwen3-TTS：目录里同时有 Qwen3-TTS-12Hz-1.7B-Base 和 Qwen3-TTS-12Hz-1.7B-VoiceDesign 两个子目录

扫不到的常见原因：埋得太深（超过 3 层）、或者路径里有 Program Files / node_modules / venv 这类会被主动跳过的目录名。这两种情况用环境变量指一下就行： yaml env: DSH_YUE2_ROOT: 'E:\my\deep\path\YuE2-3B-GGUF' DSH_QWEN_TTS_ROOT: 'E:\my\deep\path\千问TTS'

其它可调环境变量见 plugin.yml。

用法

装好之后直接用自然语言让 agent 调，或者自己指定参数。

生成一首歌

用 yue2_song 生成一首 24 秒的英文歌，indie folk 风格，输出到 D:\out\song.wav jsonc { "lyrics": "[Verse]\nMorning light is on the window.\n[Chorus]\nStay with the rhythm tonight.", "style": "English, indie folk, warm acoustic guitar, gentle female vocal", "seconds": 24, "seed": 42, "out": "D:\\out\\song.wav" }

- seconds 换算：≈ 25 语义 token / 秒音频，所以 24 秒 ≈ 600 token
- 歌词用 [Verse] / [Chorus] / [Bridge] 分段，英文效果明显更好
- 换 seed = 换旋律
- cot: off（默认，最快）/ melody / full（先规划曲式，更慢）

设计一个音色念稿

用 qwen3_tts 的 design 模式，低沉沙哑的中年男声、语速偏慢，念这段：……
jsonc
{
"text": "要念的内容", "mode": "design", "instruct": "低沉沙哑的中年男声，语速偏慢，情绪克制", "language": "Chinese", "out": "D:\\out\\voice.wav" }

克隆一把声音 jsonc { "text": "要念的内容", "mode": "clone", "ref_audio": "D:\\out\\reference.wav" }

从生成的歌里克隆音色（三段式）

yue2_song → audio_clip（切一段主歌）→ qwen3_tts(mode=clone, ref_audio=切片) jsonc // 1) 先切一段（选主歌/稀疏段，别选副歌） { "file": "D:\\out\\song.wav", "start": 5, "seconds": 8, "out": "D:\\out\\ref.wav" } // 2) 再拿它当参考音克隆 { "text": "要念的内容", "mode": "clone", "ref_audio": "D:\\out\\ref.wav" }

避坑手册

完整版（含原始报错文本、复现步骤、为什么）见 docs/PITFALLS.md。
这里是速查：

① audiocpp_cli.exe 打不开中文路径 🔥 最大的坑

症状（三选一）：

audiocpp_cli failed: model path does not exist: D:\AI工作区\YuE2-3B-GGUF gguf_init_from_file: failed to open GGUF file 'D:\AI工作区\...\yue2-3b-q8_0.gguf' (No such file or directory)

或者生成成功了，但文件出现在一个乱码目录里：

D:\AI宸ヤ綔鍖篭闊抽\20260925-yue2-mv-seg1.wav ← 你本来想要 D:\AI工作区\音频\

原因：CLI 把 argv 当 UTF-8 读，但打开文件用的是窄字符（ANSI）API，路径里有中文就错位。

没用的解法（都实测过，别浪费时间）：

| 尝试 | 结果 |
| 给中文目录建 ASCII junction，指 junction | ❌ 它把路径规范化回中文真名 |
| subst Y: 虚拟盘 | ❌ 同样被规范化 |
| 8.3 短名 D:\AI5108~1\... | ❌ 中间目录根本没有短名 |
| 把控制台/系统区域设成 UTF-8 | ❌ 治不了它内部的窄字符调用 |

有效解法：让 --model 和 --out 都是纯 ASCII 路径。
插件已经自动做了两件事：

1. 模型：检测到 YuE2 在非 ASCII 路径时，在模型真正所在的卷上建一个影子目录
（默认 :\dsh-yue2-ascii，可用 DSH_YUE2_ASCII_DIR 改），把 yue2-.gguf 和 sidecars\
用硬链接放进去（同卷，零额外空间；源文件换了会自动重链），只把它当 --model 用。
影子建不出来时退回本机另一份纯 ASCII 的副本。
2. 输出：--out 一律先写到 %TEMP%\dsh-audio-.wav，成功后再 shutil.move 到你指定的位置—— 所以照常传中文路径即可。

想彻底躲开这个坑：把 YuE2 直接放在纯英文路径（例如 D:\yue2），插件就完全不用建影子。
Qwen3-TTS 走 Python/torch，中文路径没有这个问题。

② 内存不够 → NAR 阶段崩

症状：

GGML_ASSERT(ctx->mem_buffer != NULL) failed

原因：audio.cpp 默认 graph arena 合计约 13GB（prefill 4096 / decode 1536 / nar 6144 / vae 1536）， 16GB 内存的机器必崩。必须压小，下面是实测唯一通过的组合：

| 参数 | 值 | 说明 |
| yue2.model_weight_context_mb | 6144（Q8_0）/ 10240（BF16） | 要同时装下 AR 权重 + NAR 权重。Q8 用 5120 会报 failed to allocate yue2.nar.weights backend weight buffer |
| yue2.vae_weight_context_mb | 1024 | |
| yue2.ar_prefill_graph_arena_mb | 1024 | |
| yue2.ar_decode_graph_arena_mb | 512 | |
| yue2.nar_graph_arena_mb | 跟着长度涨：≤700 token → 2560；≤1200 → 4096；更长 → 5120 | 600 token 配 2560 实测通过；1000 token 用 2560 就崩 |
| yue2.vae_graph_arena_mb | 512 | |

插件已按上面的规则自动算好，不用手填。

另外：显存/内存被别的程序占了（比如 ComfyUI 常驻 5GB 显存 + 19GB 提交内存）时，先在那边卸掉模型再跑长歌。

③ 只能 CPU，别用 vulkan

编译版的 backend 列表里只有 cpu 和 vulkan。本机实测 vulkan 会在 AR decode 建图时 Device memory allocation failed*（有别的程序占显存时必挂）。backend 保持默认 cpu。

④ PowerShell 管道喂 JSON 会毁掉中文

症状：tokenizer 报 TypeError: TextEncodeInput must be Union[...]。

原因：PowerShell 管道按 cp936 转码，UTF-8 中文变成孤立代理字符。

解法：参数走 @文件.json（UTF-8），或者直接用 DSH 工具调，不要手搓管道：

& $py .\test_client.py qwen3_tts "@args_tts.json" # ✅
'{"text":"中文"}' | & $py .\server.py # ❌

⑤ 改了 profile 不生效 / 整个 profile 起不来

- 必须重启 DSH Desktop，profile 只在宿主启动时读。
- 改完一定校验 YAML，语法错会让整个 profile 加载失败（连模型都选不了）。用 profile 自带目录里的 yaml 模块解析一遍：

cd ~\.dsh\profiles
node -e "const y=require('yaml'),f=require('fs');const d=y.parse(f.readFileSync('desktop/cordis.patch.yml','utf8'));console.log('OK, entries =', d.length)"

⑥ 从整轨混音里克隆音色 → 说话带旋律感

用户原话：「说话跟唱歌一样」。实测规律：
- 从副歌（编曲满）切 → 旋律感重；从主歌/稀疏段切 → 明显更像说话
- 给 ref_text 会更糟（同一句话从 5 秒拖到 10.5 秒）。克隆只用音色向量（x_vector_only_mode，不传 ref_text）反而更稳
- 时长是客观判据：22 字中文正常 4~5 秒，生成超过 8 秒基本就是在唱了
- 想要稳定「正常说话」：直接用 mode="design" + instruct 写「平静自然地说话，不要旋律感和拖长音」
- 想真正拿到干净人声：得先做人声分离（audio.cpp 的 --task sep，需要 bs_roformer / htdemucs 权重）

⑦ TTS 模型常驻内存

每次调用 qwen3_tts 之后模型常驻内存约 4.5GB（故意设计，避免重复加载）。
跑完不打算再用了就调 audio_unload。

⑧ 下面这些警告是正常的，不用管

Warning: flash-attn is not installed. Will only run the manual PyTorch version.
SoX could not be found!

两个都只影响速度/边缘功能，不影响推理结果。

⑨ 首次调用慢

TTS 首次加载模型 1~6 秒（之后常驻）；YuE2 每次都要重新加载权重，所以短歌也至少要几十秒，不要以为卡死了。

排障

不经过 DSH，直接按 MCP 协议跑一遍（server.py 自带一个最小客户端）：

$py = 'C:\dsh-audio-venv\Scripts\python.exe'
& $py .\test_client.py audio_status "{}"
& $py .\test_client.py yue2_song "@examples\args_song.json"
& $py .\test_client.py qwen3_tts "@examples\args_tts_design.json"

audio_status 会说清楚：模型在哪儿找到的、走的哪条路（auto-scan / 环境变量）、权重齐不齐、有没有建 ASCII 影子目录、当前内存和显存。

平台说明

代码本身没有 Windows-only 的依赖，但：

- audiocpp_cli.exe 是 win-x64 二进制（上游 audio.cpp 有 Linux/macOS 构建，可自行编译后指定 DSH_YUE2_ROOT）
- audio_play 用 winsound，非 Windows 需要改
- 中文路径那一堆坑是 Windows ANSI/UTF-8 混用导致的，Linux/macOS 上大概率不存在，但没验证过

欢迎 PR 补 Linux/macOS 的实测结果。

目录结构

dsh-audio/
├── server.py # MCP stdio server（纯标准库，torch 惰性导入） ├── plugin.yml # 插件清单 + 可直接复制的 profile 行配置 ├── install.ps1 # 一键挂进 DSH profile（幂等 + 备份 + 校验） ├── test_client.py # 不经 DSH 直接跑一遍，排障用 ├── examples/ # 参数样例 └── docs/ ├── MODELS.md # 模型从哪下、多大、哪些文件必需、许可 └── PITFALLS.md # 避坑手册（完整版）

许可

- 本仓库代码：MIT，见 LICENSE
- YuE2-3B 权重：CC BY-NC 4.0，仅限非商业用途 —— 用它生成的音乐也受这个限制，商业用途请自行确认授权
- Qwen3-TTS 权重：见 Qwen/Qwen3-TTS-12Hz-1.7B-Base 的许可

致谢

- audio.cpp（YuE2 的 GGUF 推理实现）
- m-a-p/YuE2（YuE2 上游权重）
- Qwen3-TTS
- DeepSeek Harness