audio-analyzer

audio_visualizer_rs

一个能让 Claude 听见音乐的 MCP 服务。

将任意音频文件交给 Claude，它就能告诉你音调、速度、动态、音色、打击乐特征、立体声声场、结构段落，以及音乐如何随时间演变——所有结论都来自原始音频分析，没有图像、没有猜测，且仅使用不到 1% 的上下文窗口。

并排比较两首曲目。检测音乐在结构上的变化位置——前奏、主歌、副歌、桥段——并放大查看重要片段。

这是什么？

大模型能看（视觉）也能读（文本），但无法听。本项目通过运行真正的音频分析来弥合这一差距——采用音乐信息检索研究中使用的同类 DSP 技术，并返回结构化数值数据，供 Claude 推理。

这是一个 MCP 服务，它将音频分析作为 Claude 可按需调用的工具提供。让 Claude 分析一首歌，它就会解码音频、运行频谱／谐波／节奏／打击乐分析，并以精简文本返回结果。没有频谱图，没有图像，也不浪费令牌。

一首 60 秒曲目的完整分析可在 2 秒内完成（包括声源分离）。纯 Rust 实现。无需 Python、FFmpeg 或系统依赖项。

功能

• 音频解码 —— 通过 Symphonia 支持 mp3、wav、flac、ogg、aac（纯 Rust）
• 频谱分析 —— 质心（明亮度）、带宽（丰富度）、滚降点、平坦度（音调性）
• 频段能量 —— 计算 7 个标准制作频段（从超低音到极高频）的 RMS 能量，用于混音诊断
• 频谱对比度 —— 以 dB 表示各频段的峰值与谷值之差，揭示清晰度与浑浊度
• 动态范围 —— 峰值因子、响度范围（第 95 至第 5 百分位）、峰值 dBFS
• LUFS 响度 —— EBU R128 综合响度（ITU-R BS.1770-4 立体声声道求和）、真峰值（dBTP）、响度范围（LRA）、流媒体平台目标值。与 FabFilter Pro-L 2 的结果误差经验证为 0.0 dB。
• 立体声声场分析 —— 相位相关性（单声道兼容性）、立体声宽度（中／侧比）、左右声道平衡、单声道兼容性评分。提供逐帧时间序列，以精确定位相位问题。
• 时域特征 —— RMS 能量（响度）、过零率（质感）
• 音色 —— 13 个 MFCC（梅尔频率倒谱系数）
• 谐波分析 —— 色度图、调性检测（Krumhansl-Schmuckler 算法）、Tonnetz
• 节奏分析 —— 速度估算、节拍跟踪、起音检测、速度稳定性
• 打击乐特征 —— 谐波／打击乐声源分离（HPSS）、起音锐度、起音密度
• 段落边界检测 —— 通过多特征新颖度分析检测结构变化（能量、频谱、谐波、质感）。支持“先概览、再放大”的工作流：先获取结构图，再深入分析感兴趣的片段
• A/B 对比 —— 并排分析两首曲目，获取精简的差异表，重点呈现响度、动态、频谱平衡、立体声声场、调性和速度方面的差异
• 时间序列数据 —— 以可选分辨率跟踪每项特征随时间的变化
• 令牌高效 —— 对输出进行降采样，以确保能轻松容纳在上下文窗口中

实际演示

观看 Claude 在一次会话中分析四首曲目 —— 一首原创钢琴／铜管乐作品、标出完整段落结构和段落边界的《波希米亚狂想曲》、附带制作建议的 A/B 混音对比，以及一段雷暴现场录音，Claude 将其中的音乐指标区分为“无意义”和“真实物理现象”。四项分析均可容纳在一个上下文窗口中。

安装

Claude Desktop — 一键安装

从 GitHub Releases 下载适用于你平台的 .mcpb 捆绑包并打开。Claude Desktop 会处理剩下的工作——无需配置文件、无需终端、无需设置。

平台	文件
macOS（Apple Silicon）	audio-analyzer-darwin-arm64.mcpb
macOS（Intel）	audio-analyzer-darwin-x64.mcpb
Windows	audio-analyzer-win32-x64.mcpb
Linux	audio-analyzer-linux-x64.mcpb

Claude Code — Homebrew（macOS）

brew tap JuzzyDee/tap
brew install audio-analyzer
claude mcp add --scope user audio-analyzer -- $(which audio-analyzer-mcp)

Claude Code — 手动安装（所有平台）

从 GitHub Releases 下载适用于你平台的 mcp-server 二进制文件，然后：

claude mcp add --scope user audio-analyzer -- /path/to/mcp-server

从源代码构建

git clone https://github.com/JuzzyDee/audio-analyzer-rs.git
cd audio-analyzer-rs
cargo build --release
claude mcp add --scope user audio-analyzer -- target/release/mcp-server

重启 Claude Desktop。音频分析工具即可在对话中使用。

注意：这是一个使用 stdio 传输的本地 MCP 服务，因此需要 Claude Code 或 Claude Desktop。它无法在浏览器中的 claude.ai 或移动应用中运行。

用法

重要：此工具会分析你本地计算机上的文件。向 Claude 提供完整的文件路径（例如，/Users/you/Music/song.mp3）——不要尝试将文件上传或附加到聊天中。Claude 会直接从磁盘读取文件。

CLI（独立运行）

cargo run --bin cli -- /path/to/song.mp3
cargo run --bin cli -- compare /path/to/mix_v1.mp3 /path/to/mix_v2.mp3

MCP 工具

配置完成后，Claude 可以直接调用这些工具：

工具	功能
audio_info	基本文件信息：时长、采样率、采样数
spectral_features	亮度、丰富度、响度、纹理、音色（MFCC）、频段能量、频谱对比度、动态范围、LUFS 响度、立体声场
harmonic_analysis	调性检测、音级分布、tonnetz
rhythm_analysis	速度（BPM）、节拍位置、速度稳定性
full_analysis	一次调用即可获取以上所有内容，另含打击乐特征（HPSS）、立体声场和乐段边界。推荐工作流：先不指定 resolution 调用以获取摘要和乐段图，然后使用高分辨率的 start_time/end_time 深入分析感兴趣的乐段
compare	对两首曲目进行 A/B 对比——分析两者并返回简明的差异表

示例：full_analysis 输出

以下是对一段 60 秒爵士三重奏曲目调用 full_analysis 后的返回结果：

═══ Full Audio Analysis ═══
File: /music/jazz_trio.mp3
Duration: 60.62 sec | Sample rate: 48000 Hz | Samples: 2909952
Analysis completed in: 2.02s

── Spectral/Temporal Features ──
Centroid (brightness):  2812 Hz — moderate
Bandwidth (richness):   3933 Hz — complex
Rolloff (energy focus): 6489 Hz
Flatness (tonality):    0.0824 — strongly tonal
RMS Energy (loudness):  0.1160
Zero Crossing Rate:     0.0402 — mixed
MFCCs (timbre):         [-141.3, 13.7, 0.9, 7.7, -2.5, 3.1, -1.7, 2.3, -0.9, 1.0, -0.5, 0.9, 0.6]

── Frequency Band Energy ──
Sub bass  (20–60 Hz):     0.007803
Bass      (60–250 Hz):    0.013043
Low-mid   (250–500 Hz):   0.004906
Mid       (500–2k Hz):    0.002165
Upper-mid (2k–4k Hz):     0.000203
Presence  (4k–6k Hz):     0.000166
Brilliance(6k–20k Hz):    0.000089

── Spectral Contrast (peak–valley dB) ──
Sub bass  (20–60 Hz):     10.4
Bass      (60–250 Hz):    20.4
Low-mid   (250–500 Hz):   26.0
Mid       (500–2k Hz):    30.9
Upper-mid (2k–4k Hz):     19.4
Presence  (4k–6k Hz):     16.6
Brilliance(6k–20k Hz):    55.2

── Harmonic Content ──
Estimated key: E minor (confidence: 0.538)
Top pitch classes:
   1. G  0.627 ███████████████
   2. E  0.561 ██████████████
   3. C  0.512 ████████████
   4. D# 0.495 ████████████
   5. F# 0.487 ████████████
   6. C# 0.459 ███████████

── Rhythm ──
Tempo: 84.0 BPM (confidence: 0.316)
Beats detected: 69
Mean tempo: 84.3 BPM | Median: 84.0 BPM
Stability: 0.951 (0=free, 1=locked)

── Percussive Character ──
Percussive ratio:    0.277 — harmony-dominated
Onset density:       7.0/sec — very dense
Peak attack sharp:   1.000

── Dynamic Range ──
Peak:            -0.44 dBFS
Crest factor:    16.2 dB — very dynamic
Loudness range:  76.4 dB — very dynamic
Quiet sections:  -87.5 dBFS | Loud sections: -11.1 dBFS

── Loudness (EBU R128) ──
Integrated:      -12.1 LUFS
True peak:       0.0 dBTP
Loudness range:  3.7 LU
Spotify (-14):   turned DOWN 1.9 dB | Apple (-16): turned DOWN 3.9 dB | YouTube (-14): turned DOWN 1.9 dB

── Stereo Field ──
Phase correlation:   0.257 avg, -0.822 min — some phase issues
Phase warnings:      20.6% of frames have negative correlation
Stereo width:        0.812 avg, 2.747 max — wide
Balance:             -0.095 — slightly left
Mono compatibility:  0.620 avg, 0.117 min — significant mono loss

── Section Boundaries ──
  Working BPM:     84 (confidence: 0.32)
  Boundaries:      2
     0:18.3s  energy+spectral+texture (confidence: 0.85)
     0:42.1s  energy+harmonic (confidence: 0.67)

添加 resolution: "medium" 后，输出还会包含一个时间序列表格，展示每项特征如何随曲目时长变化——让 Claude 能够识别前奏的渐强、力度丰富的独奏段以及安静的尾奏。

时间序列分辨率

所有分析工具都接受可选的 resolution 参数，用于控制时间序列输出：

预设	每秒数据点	适用场景
"low"	~0.5/sec	宏观概览，效果相当于通过频谱图大致观察
"medium"	~1/sec	适用于大多数分析任务的默认选项
"high"	~4/sec	用于查看短片段或放大观察过渡的详细视图

你也可以传入数字字符串（例如，"20"）来设置自定义速率。

不指定 resolution 时，工具只返回汇总统计信息（整首曲目的平均值）。指定后，则会得到一份精简的 TSV 表格，展示各项特征随时间的变化——质心、RMS、动态范围、色度、起音强度、打击乐比例、频段能量、频谱对比度等，且都与同一时间轴对齐。

这些预设经过校准，可提高令牌效率。一个 3 分钟的曲目在 "medium" 分辨率下会生成约 180 行数据——足以追踪音乐结构，又不会撑爆上下文窗口。

架构

audio file
    |
    +---> load_audio()          -- Symphonia decodes to mono f32 samples
    |         |
    |         v
    |     compute_spectrogram() -- STFT via rustfft, time-frequency matrix
    |         |
    |         +---> spectral.rs    -- centroid, bandwidth, rolloff, flatness, MFCCs, band energy, contrast
    |         +---> temporal.rs    -- RMS energy, zero crossing rate, dynamic range
    |         +---> harmonic.rs    -- chromagram, key detection, tonnetz
    |         +---> rhythm.rs      -- onset detection, tempo, beat tracking
    |         +---> percussive.rs  -- HPSS (source separation), attack sharpness, onset density
    |         +---> sections.rs    -- section boundary detection (multi-feature novelty)
    |
    +---> load_audio_stereo()   -- preserves L/R channels
              |
              +---> stereo.rs      -- phase correlation, width, balance, mono compatibility
              +---> temporal.rs    -- LUFS loudness (ITU-R BS.1770-4 stereo channel summing)
    |
    v
downsample.rs                   -- bin-average to target resolution, format as TSV

两个二进制文件共用同一个分析库：

• cli（src/main.rs）——运行所有分析并打印结果
• mcp-server（src/mcp_server.rs）——通过 rmcp 使用 stdio JSON-RPC 暴露工具

主要依赖项：symphonia（音频解码）、rustfft（FFT）、rmcp（MCP SDK）。

Changelog

See CHANGELOG.md for version history.

License

MIT License. See LICENSE for details.