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