音频证据包 Esper967/dsh-music-insight

dsh-music-insight

「让模型感受音乐」

把音频压成一句感受 + 三个情绪词 + 一行走向 不调用任何第三方接口。需要长报告时仍然有（--mode strict 的证据清单）

音频 ──▶ 测量层（确定性算法） ──▶ 感官层（vibe-v2：数字 → 一句感受 / 三个词 / 一行走向） ──▶ 证据层（JSON / PNG / Markdown，需要时才看） ──▶ 任意 LLM 说一句像刚听完的话

纯 CPU、零 API、离线可跑（可选依赖只用于解码与非 WAV 格式）。

测量面板示例

默认输出长这样

听完《雨上がりの空》

glassmoon · 2:59 · 112 BPM · C 大调

感觉

像雨停之后一个人走回家：先是空的，中间暖起来，最后散了。听完是松的。

很亮 / 偏慢 / 空

走向

0:00 起 → 0:26 涨 → 1:34 满 → 2:50 收

112 BPM · 亮 · 暖 · 空

数据

2:59 · 112.3 BPM · C 大调 · -20.8 dB · 2.4/s · 中频 68%

和弦：C 92.9s / F 26.6s / G 23.7s / Am 17.3s（C 大调 / A 小调 二选一）

两种模式

| 模式 | 给谁 | 输出 | 解读提示词 |
| vibe（默认） | 想听感受的人、聊天、播客脚本 | 一句感受 + 三个词 + 一行走向 | LLM_PROMPT_FUN（2–4 句 / ≤100 字，带 1 处数据） |
| strict | 要引用、要核对、要跑评估 | 证据清单，每条结论指回字段 | LLM_PROMPT |

同一份 measurements，两种排法。短的是措辞，不是数据。

vibe 模式要求模型像一个懂行的朋友：第一句说人话、说情绪，然后顺口带 1 处具体数据（1:34 那段 / 最满 -20 dB / C 大调 / 一直绕着 C-F-G），最多 2 个数据点、1 个术语。
数据是给感受撑腰的，不是用来报参数的——所以插件会把「调性 / 高频和弦 / 关键时间点响度」单独喂给模型，让它有东西可引用，又不会变成念报告。

现在能做什么（实测数字）

在 POP909（909 首中文流行）的合成钢琴音频上评估：

| 能力 | 水平 | 说明 |
| 时长 / BPM / 响度 / 明暗 / 结构 | ✅ 可用 | BPM 误差通常在 ±2% 内 |
| 和弦（根音 / 性质） | 🟡 73.8% / 73.0% | 用 librosa 拍点；真实录音更低 |
| 调性 | 🟡 关系大小调二选一 | 由和弦序列反推，歧义会明确标注 |
| 旋律 | 🔴 不可用（19.5%） | 复调遮蔽，见「已知限制」 |
| 感官层（感受 / 情绪词 / 走向） | 🟡 规则映射 | 阈值表可读、可改，不是学习出来的 |

以上是合成音频上的数字，真实录音会更差。完整评估过程与失败记录见 docs/EVAL.md。

它是什么 / 不是什么

| 是 | 不是 |
| 把音频变成可复现的测量数据 | 音乐理解模型 |
| 把测量值压成一句感受（感官层） | 情绪识别 / 扒谱工具 |
| 生成给 LLM 读的听感底稿和提示词 | 自动乐评 SaaS |
| 明确标注置信度与失效条件 | 音频 LLM（它根本听不到声音） |

快速开始

git clone https://github.com/Esper967/music-insight.git
cd music-insight
pip install -e ".[decode]" # numpy + pillow，av 用于 mp3/m4a/flac
pip install -e ".[dev]" # 跑测试

1. 生成两段无版权的测试音频
python examples/make_demo.py out/demo.wav # 19 秒，平的
python examples/make_arc_demo.py out/arc_demo.wav # 36 秒，有起—满—收

2. 一句感受（默认 vibe） music-insight out/arc_demo.wav --out out/demo

3. 证据清单（可引用） music-insight out/arc_demo.wav --out out/demo --mode strict

4. 加上节拍 / 和弦 / 由和弦反推调性 music-insight out/arc_demo.wav --out out/demo --chords

5. 批量分析一个文件夹
python examples/batch.py "某处/音乐文件夹" --out out/batch

输出：

out/demo/
├── panel.png # 波形 + 梅尔谱 + 音高类 + 结构条 ├── analysis.json # 测量值、结构、情绪先验、感官层、元信息 ├── timeline.csv # 8 秒粒度时间线 ├── report.md # 一句感受（vibe）或证据清单（strict） └── LIMITS.md # 失效条件——限制外置，不挡正文

设计原则：短的是措辞，不是数据

- 测量层只放确定性算法，每个数字都能复现、能被基准检验。
- 感官层（vibe.py）只做一件事：把测量值按阈值表压成一句话。
v2 刻意删掉了骨架表、手感表、听感锚点——那些信息留在 analysis.json 里给机器看。
它不新增音频计算，也不判断乐器 / 人声 / 流派。
- strict 模式保留完整的证据索引，供核对。
- 限制外置成 LIMITS.md：限制不会消失，但不该让模型一打开正文就先读到免责声明。
- 全程离线：没有网络层、没有评论抓取、没有性格预设。
「听完什么感觉」这件事，只由这首歌的测量值和一行提示词决定。
- 标题不可信：歌名 / 歌手 / 专辑只是文件标签，可能是错的、被改过的、同名不同曲。
模型在输出前会被告知：不要搜索、不要引用任何网络信息，只按测量转化出的感受说话。

为什么不直接让模型自己翻译数字？因为它每次翻的都不一样，而且容易翻错。
把翻译固化在代码里，措辞就可以被 review、被 git diff、被你说「这句太文艺了，改掉」。

已知限制

- 旋律提取不可用：完整混音上 RPA 19.5%，单独旋律轨 68–77%——瓶颈是复调遮蔽。
- 和弦性质依赖语料先验：QUALITY_PRIORS 来自中文流行，换到古典/爵士会偏。
- 调性只能到关系大小调层级：两者共享全部调内和弦，报告会并列两个候选。
- 节拍跟踪较弱：自研 F-measure 0.21，librosa 0.34；对和弦聚合影响 5–6 个点。
- 感官层的措辞是规则，不是理解：阈值表决定它说你「亮」还是「暗」，改表就能改性格；它不会因为这首歌真的悲伤就说什么。
- 无流派 / 年代 / 乐器识别：需要另外的嵌入模型。
- 完整失效条件见每次运行生成的 LIMITS.md（源码里的 report.LIMITS_MD）。

作为 DeepSeek Harness 插件使用

dsh-plugin/ 是一个符合 DSH 的 Host 插件 bundle，注册一个 music_insight 工具：给一条音频路径，返回一句感受 + 三个情绪词 + 一行走向与文件路径。全程本地离线。

dsh plugin --profile <你的 profile 名> add <本仓库路径>/dsh-plugin

也可以让 agent 调用 plugin_manager 的 install_bundle，target 填 dsh-plugin 的绝对路径。

配置在 dsh-plugin/cordis.patch.yml：

| 键 | 作用 |
| pythonPath | 装了 numpy + pillow（mp3 还需 av）的 Python；留空用 PATH 上的 python |
| repoRoot | music-insight 仓库路径；插件在仓库内时自动推导 |
| defaultChords | 是否默认跑节拍/和弦（默认 true） |
| defaultMode | 默认报告模式：vibe（默认）或 strict |

工具参数：

| 参数 | 说明 |
| file_path | 必需。音频路径，相对路径按会话工作目录解析 |
| mode | vibe（默认）/ strict，覆盖配置默认值 |
| chords | 是否跑节拍/和弦，覆盖配置默认值 |
| output_dir | 可选。输出目录，默认 <歌名>-分析/（放在音频同目录） |

工具描述本身就是给模型的指令：要求「2–4 句、≤100 字、先说感觉、情绪直接说、不总结不排比」，所以模型拿到结果后不会再甩一张频谱表。

已验证：WAV（标准库解码）与 MP3（PyAV，含 ID3 标签）都能跑通。

改完插件里的措辞后，不用重启 DSH 就能预览模型会读到什么：

node dsh-plugin/preview-summary.mjs out/demo/analysis.json vibe

测试

pip install -e ".[dev]"
pytest -q # 31 个测试，不需要下载数据集，也不联网

Roadmap

1. 旋律提取（dominant melody extraction，例如 Basic Pitch）——当前最大空白
2. 和弦继续提升：更多和弦类型、更大评测集、真实录音验证
3. 调性定到绝对调名（需要旋律或终止式信息）
4. CLAP / MERT 嵌入 → 流派与情绪标签（有监督、可评估）
5. 可选音频 LLM 后端：真的把声音给模型听，而不是只看测量（唯一能拿到音色的路）

Prior art

- MOSS-Music-Data-Pipeline — 训练语料标注管线
- review-music — MIR → 结构化评论，思路最接近
- Musia — 本地音乐工具链封装
- LTU / Music Flamingo — 训练音频编码器的路线，需要 GPU 与数据

差异点：测量与措辞分层（数字可核对、措辞可 review）、零 API 纯本地、全程离线。
「听完什么感觉」只由这首歌本身决定，不掺别人的评论、不套性格预设。

许可

MIT