音乐分析器 MukiyoU/dsh-music-analyze

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。随便改、随便用。