前言¶
在 DSH 對話裏處理視頻相關問題時，常見需求是「這條片子背景樂是什麼」「第幾十秒那首叫什麼」。自己打開鏈接、拖進度條、再換 App 識曲，步驟多，也不方便讓 agent 串進後續流程。若把「取鏈、抽音頻、識曲、整理元數據」收成一條工具調用，智能體可以直接根據 URL 或時間點返回答案。
下面介紹社區插件 dsh-song-id（維護者 A-2788553793，分類：聯網工具）。它在 DSH 中註冊工具 song_identify：用 yt-dlp 解析鏈接並取音頻，ffmpeg 切片後並行查詢 Shazam（shazamio）與網易雲音樂兩個識曲引擎，返回歌名、歌手、專輯、流派、封面與命中位置等信息。README 寫明目前主要測過 B 站鏈接；url 也支持 yt-dlp 能處理的其它站點。
這是什麼¶
dsh-song-id 是標準 DSH bundle（package.json 裏 dsh.bundle.patch 指向 cordis.patch.yml），npm 包名 dsh-song-id，當前版本 0.1.1，許可證 MIT，要求 Node >= 20。插件本身零 npm 依賴；識曲依賴本機上的 yt-dlp、ffmpeg、Python 3.9+，以及首次運行時自動裝進插件目錄 vendor/py 的 shazamio。網易雲側使用自帶 wasm 指紋器（vendor/afp/），無需 API key 或登錄。
串燒、混剪、DJ 串燒類視頻會在輸出裏彙總多段採樣命中的不同曲目，而不是隻報第一首。
核心功能¶
工具與參數¶
agent 調用 song_identify。主要參數如下（摘自 README）：
| 參數 | 默認 | 說明 |
|---|---|---|
url |
必填 | B 站鏈接 / BV 號 / av 號 / b23.tv 短鏈 / yt-dlp 支持的任意鏈接 |
at |
— | 從第幾秒開始認；指定後從該點往後連續取樣，不再按比例撒點 |
clips |
3 |
試幾段（1–5） |
clipSeconds |
12 |
每段長度（5–30） |
cookies |
— | cookies.txt 路徑，或環境變量 DSH_VIDEO_COOKIES |
工具聲明爲併發安全，timeoutMs 爲 300 秒。未認出時會返回 ❓ 沒認出來 及已試位置，並建議調整 at / clipSeconds。
識別流程（概要）¶
- 歸一化鏈接並查緩存（
$DSH_HOME/storages/song-id/cache.json，TTL 7 天）。 - yt-dlp 僅解析元數據；直播、播放列表會拒絕；超過 60 分鐘且未給
at會拒絕。 - 默認在時長約 12% / 42% / 72% 取 3 段；必要時追加更多采樣點或變調（×1.06 / ×1.12）再試。
- 每段經 ffmpeg 切成識曲用音頻後，Shazam 與網易雲並行查詢；合併時 Shazam 同片段有結果則丟棄該處網易雲候選，主答案優先 Shazam，僅網易雲命中時標「存疑」，變調命中會標「可能不準」。
環境變量（可選）¶
除 DSH_VIDEO_COOKIES 外，README 還提到：DSH_YTDLP_PATH、DSH_FFMPEG_PATH、DSH_PYTHON_PATH，用於指定可執行文件路徑。
安裝與啓用¶
插件以 DSH 的 bundle 方式安裝。安裝命令須使用資料原文，不要憑倉庫名拼接其它 add 命令。
1. 安裝 bundle¶
在 DSH 對話中讓 agent 執行，或使用 DSH 插件管理；將 <插件目錄> 換成本倉庫的絕對路徑：
plugin_manager install_bundle target="link:<插件目錄>"
裝完後會更新 profile 的 package.json、把 dsh-song-id 寫入 dsh.profile.bundles，並在 node_modules 建立指向該目錄的符號鏈接。開發時也可在 profile 的 package.json 中手工添加 link:<插件目錄> 依賴並列入 bundles。
裝完必須重啓一次 DSH；bundle 樹在宿主啓動時組合，熱裝進 profile 不會動態加載。
2. 安裝外部依賴¶
| 組件 | 作用 | Linux 示例 |
|---|---|---|
| yt-dlp | 解析鏈接、下載音頻 | pipx install yt-dlp 或發行版包管理器 |
| ffmpeg | 切片、轉碼 | sudo apt install ffmpeg |
| Python 3.9+ | 運行 shazamio | sudo apt install python3 |
B 站接口變動頻繁，建議定期更新 yt-dlp（如 yt-dlp -U）。shazamio 首次識曲時自動 pip install 到插件 vendor/py；也可預裝：
node scripts/install-vendor.mjs
3. 自檢¶
在插件目錄執行：
node bin/doctor.mjs
檢查 yt-dlp、ffmpeg、python、shazamio、網易雲指紋器與接口可達性；任一項失敗會給出修復提示。
典型用法¶
在對話裏¶
重啓 DSH 後，直接用自然語言附帶鏈接即可，例如：
- 「試試能不能聽歌識曲 https://www.bilibili.com/video/BVxxxxxxxxxx/」
- 「BVxxxxxxxxxx 第 75 秒那首是什麼」
- 「這個視頻的 BGM 是什麼：https://b23.tv/xxxx」
agent 會調用 song_identify 並以 Markdown 彙總結果（含引擎來源、視頻標題、命中時間點、Shazam 鏈接等）。
命令行調試¶
node scripts/smoke.mjs "https://www.bilibili.com/video/BVxxxxxxxxxx" 70
node scripts/smoke.mjs "https://www.bilibili.com/video/BVxxxxxxxxxx" --fresh
第二行用於忽略緩存。
適用場景與注意¶
適合：需要在 DSH 工作流里根據視頻 URL 或時間點查 BGM、驗證混剪曲目列表、區分降調版與曲庫 DJ 版等場景；願意在本機安裝 yt-dlp / ffmpeg / Python 的開發者。
注意：
- 插件在當前 DSH 進程權限下運行，會訪問網絡（yt-dlp、Shazam、網易雲接口）並在
$DSH_HOME/storages/song-id/讀寫緩存與臨時文件。安裝前請查閱倉庫源碼與 MIT 許可證，自行評估隱私與合規（README「隱私」一節有說明）。 - README 寫明「目前只測試了 b 站視頻鏈接」；其它站點依賴 yt-dlp 支持情況，需自行驗證。
- 變調識別易誤判；輸出中的變調、存疑標記應作爲覈對提示，而非最終裁斷。
- 社區目錄 SkillHub 插件頁 與 GitHub 由社區維護，與 DeepSeek / 幻方無官方從屬關係；DSH 生態遵循「一切皆插件」，按需選用即可。
結尾¶
dsh-song-id 把「視頻鏈接 → 雙引擎識曲 → 結構化 Markdown」收成單一 DSH 工具，適合在 agent 對話裏直接問 BGM 或指定秒數的曲目。安裝以 plugin_manager install_bundle 與本地 link: 路徑爲準，裝依賴後跑 node bin/doctor.mjs，重啓 DSH 即可使用。
- 目錄頁：https://www.skillhub.cn/plugins/A-2788553793/dsh-song-id
- 源碼與文檔：https://github.com/A-2788553793/dsh-song-id
