dsh-music-analyze —— 让模型「看见」音乐

给 DeepSeek Harness 加一个工具：把音频变成四张图 + 一组数字，模型看图看数字，就能和你讨论这首曲子。

---

它做了什么

一个 music_analyze 工具，输入音频/视频路径，输出：

四联图（music_report.png）

面板	看什么
波形	节奏、强弱、哪段安静哪段爆发
梅尔频谱	频率分布——贝斯在底下、人声在中间、镲片在上面
色度图	12 个音高类别 → 调性和和弦走向（讨论音乐最关键的一张）
段落能量	每秒 RMS，前奏/主歌/副歌的分界

文字指标（同时返回在 report 字段里）

• 时长、BPM、主调
• 频段能量占比（低/中低/中高/高/超高频）
• 动态范围（dB）
• 最响的 5 个时刻、最安静的 3 个时刻

---

它做不到什么

图能告诉你「音乐长什么样」，不能告诉你「好不好听」。

• ✅ 「A 小调、87 BPM、副歌在 1:12 进来、贝斯偏重」
• ❌ 「这段旋律很动人」

形态可以测量，感受得靠听的人说给模型听。

---

BPM 是怎么定的（v0.2.0）

单一算法的 BPM 经常翻倍。 librosa 的 beat_track 在无鼓的指弹/钢琴独奏上会把八分音符当拍点——一首舒缓的曲子能算出 123 BPM。

所以这个插件用三个独立估计器 + 一个裁决判据：

估计器	原理
动态规划节拍跟踪	找让 onset 强度路径总和最大的那条
onset 自相关	看起音强度的周期性，峰值对应拍速
循环节拍图	频域看拍速的周期结构

裁决：奇偶拍强度比

拿 DP 吐出的真实拍点，按奇偶分组，比两组的中位强度。

比值 ≥ 1.35 → 判定真实速度是共识的一半（重音每两拍一次）

为什么用 RMS 而不是 onset 强度：实测发现 onset 强度对振幅太钝——合成信号里振幅差 3.3 倍，onset 比值只有 1.19，而 RMS 比值能到 1.4 以上。

验证过的用例

信号	真实拍点密度	判定
节拍器 120	120	117.45 ✅
节拍器 87	87	86.13 ✅
节拍器 62	62	61.52 ✅
强弱交替 124（听感 62）	124	61.52 ✅
强弱交替 174（听感 87）	174	86.13 ✅

报告里会把候选和依据一起写出来：

速度      : 123 BPM
            判定依据：三估计器一致（DP + acf/tempogram）
            三估计器：动态规划 123.0 / 自相关 123.0 / 节拍图 123.0
            候选：半速 61.5，原值 123.0，倍速 246.1

不成立就不改数。 三个方法都说 123、又没有强弱交替，那就是 123——不硬凑成 62。

---

安装

1. 装 Python 依赖

python -m pip install -i https://mirrors.aliyun.com/pypi/simple/ librosa soundfile matplotlib

国内建议用阿里云镜像，PyPI 官方源下 scipy/numba 这种大包会非常慢。

2. 装 ffmpeg（三选一）

• 系统里已有 ffmpeg 在 PATH 上 → 什么都不用做
• 设环境变量 FFMPEG_BIN 指向 ffmpeg.exe
• pip install imageio-ffmpeg（会自动带一份）

3. 装插件

在 DeepSeek Harness 里：

plugin_manager install_bundle  <这个目录的绝对路径>

或者放到 profile 的 bundles 里。

---

用法

模型侧直接调用：

music_analyze(path="D:\\Music\\song.mp3")
music_analyze(path="...", start=60, end=120)   # 只分析 1:00–2:00
music_analyze(path="...", label="くじら")       # 图标题带名字

想换输出目录：outDir="..."。

模型拿到结果后应该用 read_image 打开返回的 imagePath 自己看一遍，再结合 report 讨论——只看数字不看图，等于没看懂。

---

配置（可选）

插件 Config：

pythonPath: 'C:\\path\\to\\venv\\Scripts\\python.exe'   # 指定解释器
timeoutMs: 600000                                       # 分析超时

不配也行：插件会依次尝试 python / python3 / py，并对每个跑一次 import librosa 做体检。

---

踩过的坑（这一段比代码有用）

1. 无鼓的独奏曲，BPM 会翻倍或检测不到

librosa 的节拍检测依赖打击点。纯钢琴/指弹独奏里，它会把八分音符当成拍点——一首抒情的曲子会被算成 123 BPM，实际大概 61。工具会标 bpmReliable: false，别硬信这个数。

2. 主调（key）对特殊调弦不准

指弹常用降 D、开放 C# 之类。色度分析能看出「调性中心在 C/C# 附近」，但分不清是大调小调、还是调弦造成的偏移。看色度图比看那个字母靠谱。

3. 频谱图比波形图信息量大得多

波形只能看出「响不响」，频谱能看出「什么东西在响」。看一首歌的编曲，直接看频谱。

4. matplotlib 的中文字体

默认字体不含中文，图标题会变成方块。脚本里已按 Microsoft YaHei → SimHei → PingFang SC → Noto Sans CJK 依次尝试；你的系统一个都没有的话，标题会是英文/方块——不影响数据。

5. MPLCONFIGDIR 权限

matplotlib 默认往 ~/.matplotlib 写字体缓存，某些受限环境会报 Permission denied。脚本已经把它指到插件目录下的 _mplcache/。

6. 抽取音频统一转 22050Hz 单声道

不为音质，为了和 librosa 的分析参数对齐。要做高精度音高分析可以自己改采样率。

7. 音乐/唱歌视频做语音转写要关 VAD

如果你顺手拿它分析 MV，注意：faster-whisper 的 VAD 会把「演唱」当成「音乐」滤掉，转写出来 0 段。加 --no-vad。

---

许可

MIT。随便改、随便用。