{
  "markdown": "# audio_visualizer_rs\n\n**An MCP server that gives Claude the ability to hear music.**\n\nPoint Claude at any audio file and it can tell you the key, tempo, dynamics, timbre, percussive character, stereo field, structural sections, and how the music evolves over time -- all from raw audio analysis, no images, no guessing, under 1% context window usage.\n\nCompare two tracks side-by-side. Detect where the music changes structurally — intro, verse, chorus, bridge — and zoom into the moments that matter.\n\n## What is this?\n\nLLMs can see (vision) and read (text), but they can't hear. This project bridges that gap by running real audio analysis -- the same DSP techniques used in music information retrieval research -- and returning structured numerical data that Claude can reason about.\n\nIt's an [MCP server](https://modelcontextprotocol.io/) that exposes audio analysis as tools Claude can call on demand. Ask Claude to analyze a song and it will decode the audio, run spectral/harmonic/rhythm/percussive analysis, and return the results as compact text. No spectrograms, no images, no wasted tokens.\n\nFull analysis of a 60-second track completes in under 2 seconds (including source separation). Pure Rust. No Python, no FFmpeg, no system dependencies.\n\n## Features\n\n- **Audio decoding** -- mp3, wav, flac, ogg, aac via Symphonia (pure Rust)\n- **Spectral analysis** -- centroid (brightness), bandwidth (richness), rolloff, flatness (tonality)\n- **Frequency band energy** -- RMS energy across 7 standard producer bands (sub-bass through brilliance) for mix diagnosis\n- **Spectral contrast** -- peak vs valley per band in dB, reveals clarity vs muddiness\n- **Dynamic range** -- crest factor, loudness range (95th-5th percentile), peak dBFS\n- **LUFS loudness** -- EBU R128 integrated loudness (ITU-R BS.1770-4 stereo channel summing), true peak (dBTP), loudness range (LRA), streaming platform targets. Validated to 0.0 dB of FabFilter Pro-L 2.\n- **Stereo field analysis** -- phase correlation (mono compatibility), stereo width (mid/side ratio), L/R balance, mono compatibility score. Per-frame time-series to pinpoint where phase issues occur.\n- **Temporal features** -- RMS energy (loudness), zero crossing rate (texture)\n- **Timbre** -- 13 MFCCs (Mel-frequency cepstral coefficients)\n- **Harmonic analysis** -- chromagram, key detection (Krumhansl-Schmuckler algorithm), tonnetz\n- **Rhythm analysis** -- tempo estimation, beat tracking, onset detection, tempo stability\n- **Percussive character** -- harmonic/percussive source separation (HPSS), attack sharpness, onset density\n- **Section boundary detection** -- multi-feature novelty analysis detects structural changes (energy, spectral, harmonic, texture). Enables a summary→zoom workflow: get the map, then dive into interesting moments\n- **A/B comparison** -- analyse two tracks side-by-side, get a compact diff table highlighting differences in loudness, dynamics, spectral balance, stereo field, key, and tempo\n- **Time-series data** -- track how every feature evolves over time at selectable resolution\n- **Token-efficient** -- downsampled output calibrated to fit comfortably in the context window\n\n## See it in action\n\n[Watch a fresh Claude analyse four tracks in one session](https://claude.ai/share/e40ea498-fe3e-4b22-9a70-81edf6637514) — an original piano/brass composition, Bohemian Rhapsody's full structure mapped with section boundaries, an A/B mix comparison with production advice, and a thunderstorm field recording where it triages music metrics as \"meaningless\" vs \"physically real.\" All four analyses fit in a single context window.\n\n## Installation\n\n### Claude Desktop — one-click install\n\nDownload the `.mcpb` bundle for your platform from [GitHub Releases](https://github.com/JuzzyDee/audio-analyzer-rs/releases) and open it. Claude Desktop will handle the rest — no config files, no terminal, no setup.\n\n| Platform | File |\n|----------|------|\n| macOS (Apple Silicon) | `audio-analyzer-darwin-arm64.mcpb` |\n| macOS (Intel) | `audio-analyzer-darwin-x64.mcpb` |\n| Windows | `audio-analyzer-win32-x64.mcpb` |\n| Linux | `audio-analyzer-linux-x64.mcpb` |\n\n### Claude Code — Homebrew (macOS)\n\n```bash\nbrew tap JuzzyDee/tap\nbrew install audio-analyzer\nclaude mcp add --scope user audio-analyzer -- $(which audio-analyzer-mcp)\n```\n\n### Claude Code — manual (all platforms)\n\nDownload the `mcp-server` binary for your platform from [GitHub Releases](https://github.com/JuzzyDee/audio-analyzer-rs/releases), then:\n\n```bash\nclaude mcp add --scope user audio-analyzer -- /path/to/mcp-server\n```\n\n### Build from source\n\n```bash\ngit clone https://github.com/JuzzyDee/audio-analyzer-rs.git\ncd audio-analyzer-rs\ncargo build --release\nclaude mcp add --scope user audio-analyzer -- target/release/mcp-server\n```\n\nRestart Claude Desktop. The audio analysis tools will be available in your conversations.\n\n**Note**: This is a local MCP server using stdio transport, so it requires Claude Code or Claude Desktop. It does not work with claude.ai in the browser or mobile apps.\n\n## Usage\n\n**Important**: This tool analyses files on your local machine. Give Claude the full file path (e.g., `/Users/you/Music/song.mp3`) -- don't try to upload or attach files to the chat. Claude will read the file directly from disk.\n\n### CLI (standalone)\n\n```bash\ncargo run --bin cli -- /path/to/song.mp3\ncargo run --bin cli -- compare /path/to/mix_v1.mp3 /path/to/mix_v2.mp3\n```\n\n### MCP tools\n\nOnce configured, Claude can call these tools directly:\n\n| Tool | What it does |\n|------|-------------|\n| `audio_info` | Basic file info: duration, sample rate, sample count |\n| `spectral_features` | Brightness, richness, loudness, texture, timbre (MFCCs), frequency band energy, spectral contrast, dynamic range, LUFS loudness, stereo field |\n| `harmonic_analysis` | Key detection, pitch class distribution, tonnetz |\n| `rhythm_analysis` | Tempo (BPM), beat positions, tempo stability |\n| `full_analysis` | Everything above in one call, plus percussive character (HPSS), stereo field, and section boundaries. Recommended workflow: call without resolution first to get summary + section map, then zoom into interesting sections with `start_time`/`end_time` at high resolution |\n| `compare` | A/B two tracks -- analyses both and returns a compact diff table |\n\n### Example: full_analysis output\n\nHere's what `full_analysis` returns for a 60-second jazz trio track:\n\n```\n═══ Full Audio Analysis ═══\nFile: /music/jazz_trio.mp3\nDuration: 60.62 sec | Sample rate: 48000 Hz | Samples: 2909952\nAnalysis completed in: 2.02s\n\n── Spectral/Temporal Features ──\nCentroid (brightness):  2812 Hz — moderate\nBandwidth (richness):   3933 Hz — complex\nRolloff (energy focus): 6489 Hz\nFlatness (tonality):    0.0824 — strongly tonal\nRMS Energy (loudness):  0.1160\nZero Crossing Rate:     0.0402 — mixed\nMFCCs (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]\n\n── Frequency Band Energy ──\nSub bass  (20–60 Hz):     0.007803\nBass      (60–250 Hz):    0.013043\nLow-mid   (250–500 Hz):   0.004906\nMid       (500–2k Hz):    0.002165\nUpper-mid (2k–4k Hz):     0.000203\nPresence  (4k–6k Hz):     0.000166\nBrilliance(6k–20k Hz):    0.000089\n\n── Spectral Contrast (peak–valley dB) ──\nSub bass  (20–60 Hz):     10.4\nBass      (60–250 Hz):    20.4\nLow-mid   (250–500 Hz):   26.0\nMid       (500–2k Hz):    30.9\nUpper-mid (2k–4k Hz):     19.4\nPresence  (4k–6k Hz):     16.6\nBrilliance(6k–20k Hz):    55.2\n\n── Harmonic Content ──\nEstimated key: E minor (confidence: 0.538)\nTop pitch classes:\n   1. G  0.627 ███████████████\n   2. E  0.561 ██████████████\n   3. C  0.512 ████████████\n   4. D# 0.495 ████████████\n   5. F# 0.487 ████████████\n   6. C# 0.459 ███████████\n\n── Rhythm ──\nTempo: 84.0 BPM (confidence: 0.316)\nBeats detected: 69\nMean tempo: 84.3 BPM | Median: 84.0 BPM\nStability: 0.951 (0=free, 1=locked)\n\n── Percussive Character ──\nPercussive ratio:    0.277 — harmony-dominated\nOnset density:       7.0/sec — very dense\nPeak attack sharp:   1.000\n\n── Dynamic Range ──\nPeak:            -0.44 dBFS\nCrest factor:    16.2 dB — very dynamic\nLoudness range:  76.4 dB — very dynamic\nQuiet sections:  -87.5 dBFS | Loud sections: -11.1 dBFS\n\n── Loudness (EBU R128) ──\nIntegrated:      -12.1 LUFS\nTrue peak:       0.0 dBTP\nLoudness range:  3.7 LU\nSpotify (-14):   turned DOWN 1.9 dB | Apple (-16): turned DOWN 3.9 dB | YouTube (-14): turned DOWN 1.9 dB\n\n── Stereo Field ──\nPhase correlation:   0.257 avg, -0.822 min — some phase issues\nPhase warnings:      20.6% of frames have negative correlation\nStereo width:        0.812 avg, 2.747 max — wide\nBalance:             -0.095 — slightly left\nMono compatibility:  0.620 avg, 0.117 min — significant mono loss\n\n── Section Boundaries ──\n  Working BPM:     84 (confidence: 0.32)\n  Boundaries:      2\n     0:18.3s  energy+spectral+texture (confidence: 0.85)\n     0:42.1s  energy+harmonic (confidence: 0.67)\n```\n\nWhen you add `resolution: \"medium\"`, the output also includes a time-series table showing how every feature changes over the track's duration -- letting Claude see the intro build, the dynamic solo section, and the quiet outro.\n\n## Time-series resolution\n\nAll analysis tools accept an optional `resolution` parameter that controls time-series output:\n\n| Preset | Data points/sec | Use case |\n|--------|----------------|----------|\n| `\"low\"` | ~0.5/sec | Broad overview, equivalent to what you'd eyeball from a spectrogram image |\n| `\"medium\"` | ~1/sec | Good default for most analysis tasks |\n| `\"high\"` | ~4/sec | Detailed view for short passages or zooming in on transitions |\n\nYou can also pass a numeric string (e.g., `\"20\"`) for custom rates.\n\nWithout `resolution`, tools return summary statistics only (averages across the whole track). With it, you get a compact TSV table showing how features evolve over time -- centroid, RMS, dynamic range, chroma, onset strength, percussive ratio, band energy, spectral contrast, and more, all aligned to the same time axis.\n\nThe presets are calibrated for token efficiency. A 3-minute track at `\"medium\"` resolution produces roughly 180 rows of data -- enough to track musical structure without blowing up the context window.\n\n## Architecture\n\n```\naudio file\n    |\n    +---> load_audio()          -- Symphonia decodes to mono f32 samples\n    |         |\n    |         v\n    |     compute_spectrogram() -- STFT via rustfft, time-frequency matrix\n    |         |\n    |         +---> spectral.rs    -- centroid, bandwidth, rolloff, flatness, MFCCs, band energy, contrast\n    |         +---> temporal.rs    -- RMS energy, zero crossing rate, dynamic range\n    |         +---> harmonic.rs    -- chromagram, key detection, tonnetz\n    |         +---> rhythm.rs      -- onset detection, tempo, beat tracking\n    |         +---> percussive.rs  -- HPSS (source separation), attack sharpness, onset density\n    |         +---> sections.rs    -- section boundary detection (multi-feature novelty)\n    |\n    +---> load_audio_stereo()   -- preserves L/R channels\n              |\n              +---> stereo.rs      -- phase correlation, width, balance, mono compatibility\n              +---> temporal.rs    -- LUFS loudness (ITU-R BS.1770-4 stereo channel summing)\n    |\n    v\ndownsample.rs                   -- bin-average to target resolution, format as TSV\n```\n\nTwo binaries share the same analysis library:\n- **`cli`** (`src/main.rs`) -- runs all analyses and prints results\n- **`mcp-server`** (`src/mcp_server.rs`) -- exposes tools over stdio JSON-RPC via rmcp\n\nKey dependencies: [symphonia](https://github.com/pdeljanov/Symphonia) (audio decoding), [rustfft](https://github.com/ejmahler/RustFFT) (FFT), [rmcp](https://github.com/anthropics/rmcp) (MCP SDK).\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md) for version history.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n",
  "bytes": 11825,
  "sha": "8c8e2a02aa7419922d8d6cf1fe1f265a77723cbe49b0d8c397dd8f68e91ee2c6",
  "repo_slug": "juzzydee/audio-analyzer-rs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_juzzydee_audio_analyzer_1ce5c932/readme"
}