前言¶
在 DeepSeek Harness（DSH）里和模型聊音乐，常见做法是丢一段歌词、曲名或你自己的听感描述。模型听不到文件本身，也很难从纯文本还原编曲、段落和节奏结构。若希望对话建立在可核对的事实上——例如 BPM、主调、副歌大概从哪一秒起来、低频是否偏重——需要先把音频变成模型能「看见」的材料。
mukiyou/dsh-music-analyze（维护者 MukiyoU，社区分类为模型推理）为 DSH 增加一个 music_analyze 工具：输入本地音频或视频路径，输出一张四联图和一组文字指标。模型结合 read_image 与 report 字段，即可围绕具体片段讨论结构与技术特征，而不是空泛评价。
这是什么¶
一句话：把音频/视频路径变成 四张图 + 一组数字，供多模态模型看图、看数后与你讨论这首曲子。
插件当前版本为 0.2.0（见仓库 package.json），许可 MIT。它不能替代听感——README 明确写：图能说明「音乐长什么样」，不能说明「好不好听」；形态可测量，感受仍需人听完后告诉模型。
核心功能¶
工具输出¶
调用 music_analyze 后，主要产物包括：
- 四联图（默认
music_report.png）： - 波形：节奏强弱、安静与爆发段
- 梅尔频谱：频率分布（贝斯、人声、镲片大致位置）
- 色度图：12 个音高类，用于调性与和弦走向（README 称讨论音乐时最关键的一张）
- 段落能量：每秒 RMS，便于看前奏/主歌/副歌分界
- 文字指标（在返回的
report字段）：时长、BPM、主调；低/中低/中高/高/超高频能量占比；动态范围（dB）；最响 5 个时刻与最安静 3 个时刻。
可选参数：start / end 只分析一段时间区间；label 写入图标题；outDir 指定输出目录。
BPM 估计（v0.2.0）¶
单一 librosa beat_track 在无鼓独奏上容易把 BPM 算成两倍。本插件用三个独立估计器（动态规划节拍跟踪、onset 自相关、循环节拍图），再用奇偶拍 RMS 强度比裁决是否应取半速；不成立则不改数，并在报告中写出候选与依据。无鼓独奏曲仍可能不可靠，工具会标 bpmReliable: false。
运行环境¶
- Node >= 18（插件宿主）
- Python 侧依赖：librosa、soundfile、matplotlib；视频/部分格式需 ffmpeg（系统 PATH、
FFMPEG_BIN，或pip install imageio-ffmpeg） - 抽取音频统一为 22050Hz 单声道，与 librosa 分析参数对齐
安装与启用¶
插件以当前 DSH 进程权限运行 Python 子进程分析本地文件。安装前请自行查看 GitHub 源码 与 MIT 许可证，确认路径与依赖符合你的环境。
1. 安装 Python 依赖
国内网络建议用镜像，避免 scipy / numba 等大包过慢：
python -m pip install -i https://mirrors.aliyun.com/pypi/simple/ librosa soundfile matplotlib
2. 准备 ffmpeg（三选一）
- 系统已有
ffmpeg且在 PATH → 无需额外步骤 - 设置环境变量
FFMPEG_BIN指向可执行文件 - 或
pip install imageio-ffmpeg
3. 安装插件 bundle
在 DeepSeek Harness 中使用官方 README 写法（不要用凭名称拼接的 dsh plugin add）：
plugin_manager install_bundle <这个目录的绝对路径>
也可将 bundle 放入 profile 的 bundles 配置中。未配置时，插件会依次尝试 python / python3 / py，并对每个解释器执行 import librosa 自检。
可选配置（插件 Config）
pythonPath: 'C:\\path\\to\\venv\\Scripts\\python.exe' # 指定解释器
timeoutMs: 600000 # 分析超时（毫秒）
典型用法¶
模型侧直接调用工具，例如：
music_analyze(path="D:\\Music\\song.mp3")
music_analyze(path="...", start=60, end=120) # 只分析 1:00–2:00
music_analyze(path="...", label="くじら") # 图标题带名字
README 强调：模型应使用 read_image 打开返回的 imagePath 看图，再结合 report 讨论；只看数字不看图，信息会丢大半。
适用场景与注意¶
适合：本地曲库、MV 文件的结构化讨论（段落、速度、频段、调性中心）；需要可引用的时间点与图表时。
局限（来自 README「踩过的坑」）：
- 无鼓钢琴/指弹：BPM 可能翻倍或不可信，留意
bpmReliable。 - 特殊调弦：主调字母可能不准，色度图比单个 key 字段更可靠。
- 讨论编曲优先看梅尔频谱，波形 mainly 反映响度。
- matplotlib 中文标题依赖系统字体（已尝试 YaHei / SimHei / PingFang SC / Noto Sans CJK）；无字体时标题可能方块，不影响曲线数据。
- 若用同一环境做 MV 语音转写，faster-whisper 的 VAD 可能把演唱当音乐滤掉；转写需加
--no-vad（与音乐分析并列使用时注意）。
DSH 生态是「一切皆插件」；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。
