Skip to main content
Glama
deenesjakoruzh
JuzzyDee

audio_visualizer_rs

by JuzzyDee
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Rust
Local

audio_visualizer_rs

一个让 Claude 能够“听”音乐的 MCP 服务器。

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

并排比较两首曲目。检测音乐在结构上发生变化的位置——前奏、主歌、副歌、桥段——并放大到关键时刻。

这是什么？

LLM 能看（视觉）能读（文本），但听不见。本项目通过运行真实的音频分析——与音乐信息检索研究中使用的 DSP 技术相同——并返回 Claude 可以推理的结构化数值数据，来弥合这一差距。

它是一个 MCP 服务器，将音频分析作为工具暴露给 Claude 按需调用。让 Claude 分析一首歌，它会解码音频，运行频谱/和声/节奏/打击乐分析，并以紧凑的文本形式返回结果。没有频谱图，没有图像，不浪费 token。

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

Related MCP server: Claud-Ear

特性

  • 音频解码 -- 通过 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 比较 -- 并排分析两首曲目，生成紧凑的差异表，突出显示响度、动态、频谱平衡、立体声场、调性和速度的差异

  • 时间序列数据 -- 以可选的精度跟踪每个特征随时间的演变

  • Token 高效 -- 降采样输出，校准后适合上下文窗口

实际效果

观看一个全新的 Claude 在单次会话中分析四首曲目 —— 一首原创钢琴/铜管作品、一首带段落边界的《波西米亚狂想曲》完整结构、一次带制作建议的 A/B 混音比较，以及一段雷雨天气的现场录音，其中它把音乐指标判定为“无意义”与“物理真实”的对比。所有四次分析都适合放在同一个上下文窗口中。

安装

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。

使用方法

重要：此工具分析您本地机器上的文件。请将完整文件路径（例如 /Users/you/Music/song.mp3）提供给 Claude——不要尝试上传或附加文件到聊天中。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）、立体声场和段落边界。推荐工作流：先不带分辨率调用以获取摘要和段落地图，然后使用高分辨率的 start_time/end_time 放大到感兴趣的段落

compare

A/B 比较两首曲目——分析两者并返回紧凑的差异表

示例：full_analysis 输出

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

═══ 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/秒

大致概览，相当于从频谱图图像中目测

"medium"

~1/秒

大多数分析任务的良好默认值

"high"

~4/秒

用于短段落或放大过渡的详细视图

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

如果不带 resolution，工具仅返回摘要统计信息（整个曲目的平均值）。带上的话，您将获得一个紧凑的 TSV 表格，显示特征随时间的演变——质心、RMS、动态范围、色度、起始点强度、打击乐比例、频段能量、频谱对比度等，全部对齐到同一时间轴。

预设针对 token 效率进行了校准。一首 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.md。

许可证

MIT 许可证。详情请参阅 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers