audio_visualizer_rs

Un servidor MCP que le da a Claude la capacidad de oír música.

Señala a Claude cualquier archivo de audio y puede decirte la tonalidad, el tempo, la dinámica, el timbre, el carácter percusivo, el campo estéreo, las secciones estructurales y cómo evoluciona la música con el tiempo, todo a partir del análisis de audio sin procesar, sin imágenes, sin adivinanzas, con menos del 1% del uso de la ventana de contexto.

Compara dos pistas una al lado de la otra. Detecta dónde cambia la música estructuralmente (intro, verso, estribillo, puente) y haz zoom en los momentos que importan.

¿Qué es esto?

Los LLM pueden ver (visión) y leer (texto), pero no pueden oír. Este proyecto cubre esa brecha ejecutando análisis de audio reales (las mismas técnicas de DSP utilizadas en la investigación de recuperación de información musical) y devolviendo datos numéricos estructurados sobre los que Claude puede razonar.

Es un servidor MCP que expone el análisis de audio como herramientas que Claude puede invocar bajo demanda. Pídele a Claude que analice una canción y decodificará el audio, ejecutará análisis espectral, armónico, rítmico y percusivo, y devolverá los resultados como texto compacto. Sin espectrogramas, sin imágenes, sin tokens desperdiciados.

El análisis completo de una pista de 60 segundos se completa en menos de 2 segundos (incluida la separación de fuentes). Rust puro. Sin Python, sin FFmpeg, sin dependencias del sistema.

Related MCP server: Claud-Ear

Características

• Decodificación de audio -- mp3, wav, flac, ogg, aac mediante Symphonia (Rust puro)

• Análisis espectral -- centroide (brillo), ancho de banda (riqueza), rolloff, planitud (tonalidad)

• Energía por bandas de frecuencia -- energía RMS en 7 bandas estándar de productor (desde sub-graves hasta brillo) para diagnóstico de mezcla

• Contraste espectral -- pico vs valle por banda en dB, revela claridad vs turbidez

• Rango dinámico -- factor de cresta, rango de sonoridad (percentil 95-5), pico dBFS

• Sonoridad LUFS -- sonoridad integrada EBU R128 (suma de canales estéreo ITU-R BS.1770-4), pico verdadero (dBTP), rango de sonoridad (LRA), objetivos de plataformas de streaming. Validado a 0,0 dB de FabFilter Pro-L 2.

• Análisis de campo estéreo -- correlación de fase (compatibilidad mono), ancho estéreo (relación mid/side), balance L/R, puntuación de compatibilidad mono. Serie temporal por fotograma para localizar dónde ocurren problemas de fase.

• Características temporales -- energía RMS (sonoridad), tasa de cruces por cero (textura)

• Timbre -- 13 MFCC (coeficientes cepstrales de frecuencia Mel)

• Análisis armónico -- cromagrama, detección de tonalidad (algoritmo de Krumhansl-Schmuckler), tonnetz

• Análisis rítmico -- estimación de tempo, seguimiento de pulsos, detección de ataques, estabilidad del tempo

• Carácter percusivo -- separación de fuentes armónicas/percusivas (HPSS), nitidez de ataque, densidad de ataques

• Detección de límites de sección -- análisis de novedad multifactorial detecta cambios estructurales (energía, espectral, armónico, textura). Permite un flujo de trabajo resumen→zoom: obtén el mapa y luego sumérgete en los momentos interesantes

• Comparación A/B -- analiza dos pistas una al lado de la otra, obtén una tabla de diferencias compacta que resalta diferencias en sonoridad, dinámica, balance espectral, campo estéreo, tonalidad y tempo

• Datos de serie temporal -- sigue cómo evoluciona cada característica a lo largo del tiempo con resolución seleccionable

• Eficiente en tokens -- salida reducida calibrada para caber cómodamente en la ventana de contexto

Véalo en acción

Mira a un Claude nuevo analizar cuatro pistas en una sola sesión — una composición original de piano/metal, la estructura completa de Bohemian Rhapsody mapeada con límites de sección, una comparación de mezcla A/B con consejos de producción, y una grabación de campo de tormenta donde clasifica las métricas musicales como "sin sentido" frente a "físicamente reales". Los cuatro análisis caben en una sola ventana de contexto.

Instalación

Claude Desktop — instalación con un clic

Descarga el paquete .mcpb para tu plataforma desde GitHub Releases y ábrelo. Claude Desktop se encargará del resto: sin archivos de configuración, sin terminal, sin configuración.

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 — manual (todas las plataformas)

Descarga el binario mcp-server para tu plataforma desde GitHub Releases y luego:

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

Compilar desde el código fuente

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

Reinicia Claude Desktop. Las herramientas de análisis de audio estarán disponibles en tus conversaciones.

Nota: Este es un servidor MCP local que utiliza transporte stdio, por lo que requiere Claude Code o Claude Desktop. No funciona con claude.ai en el navegador ni en aplicaciones móviles.

Uso

Importante: Esta herramienta analiza archivos en tu máquina local. Dale a Claude la ruta completa del archivo (por ejemplo, /Users/you/Music/song.mp3) — no intentes subir o adjuntar archivos al chat. Claude leerá el archivo directamente desde el disco.

CLI (independiente)

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

Herramientas MCP

Una vez configurado, Claude puede llamar a estas herramientas directamente:

Ejemplo: salida de full_analysis

Esto es lo que devuelve full_analysis para una pista de trío de jazz de 60 segundos:

═══ 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)

Cuando agregas resolution: "medium", la salida también incluye una tabla de serie temporal que muestra cómo cambia cada característica a lo largo de la duración de la pista, lo que permite a Claude ver la construcción de la intro, la sección de solo dinámica y el outro tranquilo.

Resolución de serie temporal

Todas las herramientas de análisis aceptan un parámetro opcional resolution que controla la salida de serie temporal:

También puedes pasar una cadena numérica (por ejemplo, "20") para tasas personalizadas.

Sin resolution, las herramientas devuelven solo estadísticas resumidas (promedios de toda la pista). Con él, obtienes una tabla TSV compacta que muestra cómo evolucionan las características con el tiempo: centroide, RMS, rango dinámico, croma, fuerza de ataque, relación percusiva, energía de banda, contraste espectral y más, todo alineado al mismo eje temporal.

Los ajustes preestablecidos están calibrados para la eficiencia de tokens. Una pista de 3 minutos con resolución "medium" produce aproximadamente 180 filas de datos, suficiente para seguir la estructura musical sin reventar la ventana de contexto.

Arquitectura

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

Dos binarios comparten la misma biblioteca de análisis:

• cli (src/main.rs) -- ejecuta todos los análisis e imprime resultados

• mcp-server (src/mcp_server.rs) -- expone herramientas sobre stdio JSON-RPC mediante rmcp

Dependencias clave: symphonia (decodificación de audio), rustfft (FFT), rmcp (SDK de MCP).

Historial de cambios

Consulta CHANGELOG.md para el historial de versiones.

Licencia

Licencia MIT. Consulta LICENSE para más detalles.