前言¶
在 DeepSeek Harness（DSH）里做视频、播客或音乐相关任务时，常见做法是：把音频丢给云端 ASR，或让模型凭画面猜台词。前者有费用和隐私成本，后者在快嘴说唱、纯音频片段上容易错。社区插件 dsh-soundtry（维护者 CixiSVesper，当前版本 1.0.2，MIT）走另一条路：转写、节奏、旋律、和弦、结构六类能力都在本机跑，默认不依赖云端推理 API。下面介绍它是什么、怎么装、六个工具怎么用，以及 Windows 与 Python 环境上需要提前知道的限制。
这是什么¶
dsh-soundtry 是 DSH 的本地听觉插件，分类属于模型推理。一句话定位：给 agent 提供离线音频理解——Whisper medium 转写，外加 BPM/切点、人声旋律、和弦时间轴、段落结构等分析。
与「只转文字」的 ASR 不同，它把音乐性信息也结构化输出，并刻意在 BPM、和弦品质等不可信处用字段标明不确定性。README 说明该插件可单独分析音乐，也可与画面理解类插件配合理解视频；维护者提到可与 dsh-bili-whale 等场景组合使用，但本地推理速度因机器而异，一般建议在其它依据不足以理解内容时再上音频分析。
核心功能¶
六个工具¶
| 工具 | 作用 | 典型场景 |
|---|---|---|
sound_read |
一次输出转写时间码 + BPM/切点 + 旋律 + 和弦 | 快速弄清「在说什么、什么调、什么和弦」 |
sound_transcribe |
语音/歌词转带时间码文本，可写 SRT、可切时间窗 | 字幕、引用台词、确认旁白 |
sound_rhythm |
BPM（含 ambiguous/level/conflict 等状态）、鼓组能量、切点 | 判断是否跟音乐剪辑、节奏变化 |
sound_melody |
人声轨音域、调性、音高轮廓 | 副歌是否升调、乐句跨度 |
sound_chords |
拍点级和弦轴（根音相对可信，品质需保守解读） | 四和弦循环、副歌换和弦 |
sound_structure |
前奏/主歌/副歌/间奏等边界与人声、鼓进入时刻 | 按段落切片、找高潮 |
README 中的调用示例：
sound_read input="D:/片子.mp4"
sound_transcribe input="D:/课.mp4" start=600 end=720 srt="D:/课_10min.srt"
sound_rhythm input="D:/歌.mp4" video="D:/歌.mp4"
sound_structure input="D:/歌.flac"
sound_melody input="D:/歌.mp4" windows=["副歌:78:82","主歌:33:37"]
sound_chords input="D:/歌.flac"
人声分离与转写（1.0.2 要点）¶
默认人声分离改为 UVR MDX-Net（ONNX + onnxruntime），主路径不需要 torch。权重不进 Git 仓库：deps.manifest.json 记录 URL、字节数与 MD5，首次运行下载（分离模型约 63.7 MB，Whisper medium 约 1.46 GB）。
分离后端可在插件详情页或参数中切换，降级顺序为 ONNX → Demucs → HPSS；也可强制：
--separator auto （默认）
--separator onnx 强制 MDX（无 torch）
--separator demucs 需要 torch
--separator hpss 零依赖兜底，质量较差
--separator none 不分离
为减少 Whisper 在无人声处「编词」，默认路径会先分离人声、按能量切块再识别；若关闭分离或 vadMode="off"，输出会带警告。转写报告里应出现人声切分说明行，否则说明门控可能被绕过。
插件内设置¶
打开 插件 → 已安装 → dsh-soundtry，详情页「声音分析」可改：
| 项 | 说明 |
|---|---|
| 推理设备 | 自动 / 仅 GPU / 仅 CPU；显存 < 4 GB 时强制 CPU 并提示 |
| 分离后端 | 自动 / MDX-Net ONNX / Demucs / HPSS |
| 转写模型 | medium / large-v3（后者需另下约 1.5 GB） |
写入 ~/.dsh/soundtry.json，下次工具调用生效，无需重启 DSH；手写的 python、comfyui 等字段不会被覆盖。
安装与启用¶
DSH 生态是「一切皆插件」；SkillHub 是社区目录站点，与 DeepSeek / 幻方无官方从属关系。本插件目录页：
https://www.skillhub.cn/plugins/CixiSVesper/dsh-soundtry
安装说明以目录页「发送给 DeepSeek Harness 安装」为准，原文为：
请安装 DSH 插件 CixiSVesper/dsh-soundtry。先读取..
（完整句子以目录页展示为准；勿自行拼接未在官方资料出现的 CLI 格式。）
运行要求（README）：
| 项 | 要求 |
|---|---|
| 操作系统 | Windows 10/11 x64（路径按 Windows 实现，macOS/Linux 会失败） |
| Python | 3.10 – 3.12 |
| Node | ≥ 20（DSH 宿主） |
| 磁盘 | 约 3 GB 起（venv、Whisper、MDX、ffmpeg 与缓存） |
| 内存 | 可用 6 GB，8 GB 推荐 |
| ffmpeg | 需要；首次运行从 PATH、邻近插件或 SOUNDTRY_FFMPEG 复制到 vendor/ |
Python 环境两条路（README）：
告诉 DSH：用我已有的 python → borrow 模式（默认）→ venv 约 160 MB
告诉 DSH：没有 python → standalone 模式 → 整套 venv 约 7 GB
可在 ~/.dsh/soundtry.json 的 python 字段指向已有解释器（例如 ComfyUI 的 python.exe），或通过 SOUNDTRY_PYTHON、自动扫描 ComfyUI 路径、PATH 上的 python 探测。注意： borrow 模式若 pip 安装 demucs 且环境无 torch，可能额外拉取约 2.5 GB 的 torch；只用 MDX 时可跳过 demucs 或设 separator: "onnx"。
依赖与模型在第一次调用工具时自动安装；也可在插件目录手动触发：
node src/deps.js
等价于 npm run setup。进度在 stderr，就绪后写入 runtime/ready.json；依赖源或模型变化时会重装，删除该文件可强制重装。
典型用法¶
1、在 DSH 中按 SkillHub 说明安装 CixiSVesper/dsh-soundtry，确认 Node ≥ 20 与 Windows x64。
2、（推荐）在 ~/.dsh/soundtry.json 指定已有 Python 3.10–3.12，或让插件在 standalone 模式下自建环境。
3、在 agent 对话中让模型调用工具，例如对本地 mp4/flac 使用 sound_read 或 sound_transcribe；首次调用会下载模型并建 venv，耗时取决于网络与磁盘。
4、在插件详情页调整 CPU/GPU、分离后端、Whisper 型号；显存不足时保持 CPU 即可，MDX 分离固定走 CPU。
5、读输出里的不确定性标记（BPM 的 ambiguous、和弦说明、切点双阈值等），勿把「根音可信、品质不可信」的和弦当成精确 jazz 谱。
诊断环境可运行（在插件包内）：
npm run doctor
适用场景与注意¶
适合： 需要在 DSH 里离线分析口播/歌词/音乐结构、生成带时间码文本或 SRT、配合其它插件理解视频音轨，且接受 Windows 本机算力与首次下载体积的开发者。
务必知晓：
- 插件以当前 DSH 进程权限运行，会执行 Python 子进程、下载模型与写本地配置；安装前应阅读 GitHub 源码 与 MIT 许可证，自行评估信任边界。
- 仅支持 Windows；不要在 Linux/macOS 上预期可用。
- 本地推理几乎不消耗 LLM token，但 CPU 分离约 2.3× 实时（README 实测 207 秒歌 MDX 分离约 89 秒）；GPU 主要加速 Whisper/Demucs，MDX 默认 CPU。
- 1.0.1 起对 Demucs 与 Whisper 同进程崩溃做了隔离与安全退出；若仍遇分离问题，可查阅 README 中的
vadMode、SOUNDTRY_INPROC_SEPARATE等逃生参数。 - 问题反馈：README 提供 QQ 群 1130719501 与 GitHub 仓库评论区。
结尾¶
dsh-soundtry 把转写与音乐结构分析收进 DSH 工具层，默认 MDX-Net 分离去掉 torch 主路径依赖，依赖与模型在首次运行时按 manifest 自举。若你的 agent 需要「听得见」而不是猜画面，可在 Windows 上装好后从 sound_read 或 sound_transcribe 试起。
- 社区目录：https://www.skillhub.cn/plugins/CixiSVesper/dsh-soundtry
- 源码与完整说明：https://github.com/CixiSVesper/dsh-soundtry
