前言¶
在 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
