🎵 Audio Sonic MCP

Verwandle jeden Song in eine strukturierte „Sonic-Signatur" – mit Tempo, musikalischer Tonart, einem 512-dimensionalen CLAP-Vibe-Embedding, menschenlesbaren Vibe-Tags und einem Produktionsprofil – aus einem einzigen lokalen Aufruf.

Audio Sonic MCP läuft vollständig auf deinem lokalen Rechner (ohne API-Schlüssel, externe Server oder Cloud-Abhängigkeiten) und bietet zwei Premium-Zugangspunkte zu derselben hochauflösenden Audioanalyse-Engine:

🎹 Kurzer Vorgeschmack: Was du bekommst

1. Musikerfreundliche CLI-Zusammenfassung (--summary-Modus)

🎵 SONIC SIGNATURE — my_demo.mp3  (3:24)

  TEMPO    153.8 BPM  (steady)
  KEY      G Major  ·  shifts to G Phrygian @0:30   (confidence 74%)
  VIBE     aggressive · dark · driving · hip-hop · gritty

  PRODUCTION
     Vocals     forward
     Punch      0.62  (moderate)
     Stereo     wide
     Low end    ~55 Hz dominant

  Overall confidence: 88%   ·   analyzed in 0:28 (GPU-accelerated)

2. Umfassendes JSON (standardmäßig von MCP und CLI zurückgegeben)

{
  "header": {
    "job_id": "sig_a3f9b2c1",
    "status": "success",
    "confidence_score": 0.88,
    "source_metadata": {
      "title": "Acoustic Vibe Demo",
      "duration_sec": 204,
      "source_type": "file"
    }
  },
  "sonic_signature": {
    "bpm": 153.8,
    "bpm_engine": "madmom",
    "bpm_variable": false,
    "key": "G Major",
    "key_variable": true,
    "key_map": [
      { "start_sec": 0.0,  "end_sec": 30.0, "key": "G Major" },
      { "start_sec": 30.0, "end_sec": 90.0, "key": "G Phrygian" }
    ],
    "mode_confidence": 0.74,
    "vibe_vector": [0.012, -0.034, "... 512 float dimensions ..."],
    "vibe_tags": ["aggressive", "dark", "driving", "hip-hop", "gritty"],
    "production_profile": {
      "vocal_presence": "forward",
      "transient_punch": 0.62,
      "stereo_width": "wide",
      "dominant_freq_peaks_hz": {
        "harmonic": [55.0, 110.2],
        "percussive": [125.0, 250.1]
      }
    }
  },
  "telemetry": {
    "inference_time_sec": 28.0
  }
}

Related MCP server: music-perception-mcp

⚡ Hauptfunktionen

• 🥁 Tempo- und Beat-Tracking — Vollständige BPM-Berechnung mit Erkennung von Temposchwankungen und Transienten-Fensterung.

• 🎹 Tonart- und Harmoniekartierung — Berechnet die strukturelle musikalische Tonart + den Modus und erzeugt eine detaillierte key_map, die Modulationen Abschnitt für Abschnitt verfolgt.

• 🌈 Vibe- und Stil-Embeddings — Erstellt ein 512-dimensionales CLAP-Embedding und menschenlesbare Stil-Tags (für Energie, Textur, Stimmung und Genre) mithilfe einer Zero-Shot-Klassifikation des Musikvokabulars.

• 🎚️ Produktionsanalysen — Misst räumliche Präsenz des Gesangs, Transienten-Punch-Koeffizienten, Stereobreite und dominante Frequenzspitzen.

• 🤖 MCP-natives System — Stellt vollständig 4 standardisierte Model-Context-Protocol-Tools für die sofortige Integration in KI-Tools bereit.

• 🪶 Robuste, sanfte Degradierung — Nutzt automatisch eine CUDA-GPU, falls vorhanden, und fällt auf die CPU zurück; degradiert sanft auf HPSS und standardmäßige librosa-Feature-Arrays, wenn schwere Deep-Learning-Pakete ([clap]) weggelassen werden.

• 🔒 100% offline und privat — Alle Konvertierungen, Trennungen und Inferenzen erfolgen lokal.

📦 Installation & Einrichtung

Systemvoraussetzungen

Stelle sicher, dass Python 3.10+ und FFmpeg installiert und über deinen System-PATH zugänglich sind.

FFmpeg installieren:

• macOS: brew install ffmpeg

• Linux (Debian/Ubuntu): sudo apt update && sudo apt install -y ffmpeg

• Windows: Führe winget install Gyan.FFmpeg über PowerShell (Administrator) aus oder lade es manuell von ffmpeg.org herunter und füge das bin-Verzeichnis zu deinen Systemumgebungsvariablen hinzu.

Schritt-für-Schritt-Installation

1. Repository klonen

   git clone https://github.com/ripunjay-kashyap/audio-sonic-mcp.git
   cd audio-sonic-mcp

2. Virtuelle Umgebung initialisieren

   python -m venv .venv
   # Activate on macOS/Linux:
   source .venv/bin/activate
   # Activate on Windows (PowerShell):
   .venv\Scripts\activate

3. Abhängigkeiten installieren Wähle zwischen der leichten Kern-Engine oder der vollständigen High-Fidelity-ML-Suite:

   • Option A: Vollständige High-Fidelity-ML-Suite (empfohlen) Enthält Demixing-Stems (Demucs) und Zero-Shot-Vibe-Vektoren (CLAP). Benötigt ~4 GB Speicherplatz.

     pip install -e ".[clap]"

   • Option B: Kern-Leichtgewicht-Pipeline Verwendet standardmäßige digitale Signalverarbeitung (HPSS/librosa). Schnelle Installation und minimaler Platzbedarf.

     pip install -e .

[!NOTE] Der optionale [clap]-Stack installiert torch, torchaudio, transformers und demucs. Ohne diese wechselt der Server automatisch zu leichten Fallbacks (HPSS statt Demucs, standardmäßige Feature-Matrizen statt CLAP-Vektoren und lässt vibe_tags weg).

🤖 MCP-Client-Konfigurationsanleitung

Audio Sonic MCP registriert sich als standardmäßiges Paketskript. Dadurch kannst du es über den globalen ausführbaren Namen (audio-sonic-mcp) direkt aus dem bin-Ordner deiner virtuellen Umgebung ausführen oder die Skriptdatei manuell ausführen.

1. Claude-Desktop-Einrichtung

Öffne deine Claude-Konfigurationsdatei:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Füge den Server zu deinem mcpServers-Objekt hinzu:

{
  "mcpServers": {
    "audio-sonic-mcp": {
      "command": "C:\\path\\to\\audio-sonic-mcp\\.venv\\Scripts\\audio-sonic-mcp.exe",
      "args": [],
      "env": {
        "JOBS_ROOT": "C:\\path\\to\\audio-sonic-mcp\\jobs"
      }
    }
  }
}

[!IMPORTANT] Windows-Benutzer: Verwende immer doppelte Backslashes (\\) in JSON-Konfigurationspfaden. Zeige mit der ausführbaren Datei direkt auf die .exe in deinem .venv\Scripts\-Verzeichnis.

2. Cursor-IDE-Integration

Um Audio Sonic MCP in den KI-Bereich von Cursor zu integrieren:

1. Navigiere zu Einstellungen ➔ Funktionen ➔ MCP.

2. Klicke auf + Neuen MCP-Server hinzufügen.

3. Fülle die Parameter aus:

   • Name: audio-sonic-mcp

   • Typ: command

   • Befehl: /path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp (unter Windows die .exe-Erweiterung verwenden)

3. Windsurf-Integration

Öffne deine Windsurf-MCP-Konfigurationsdatei (normalerweise unter ~/.codeium/windsurf/mcp_config.json) und füge die Konfiguration hinzu:

{
  "mcpServers": {
    "audio-sonic-mcp": {
      "command": "/path/to/audio-sonic-mcp/.venv/bin/python",
      "args": ["/path/to/audio-sonic-mcp/server.py"],
      "env": {
        "JOBS_ROOT": "/path/to/audio-sonic-mcp/jobs"
      }
    }
  }
}

4. Cline (VS-Code-Erweiterung) Einrichtung

Öffne die MCP-Einstellungsdatei von Cline (normalerweise unter %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json oder dem entsprechenden Plattformspeicher) und füge hinzu:

{
  "mcpServers": {
    "audio-sonic-mcp": {
      "command": "/path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp",
      "args": [],
      "env": {
        "JOBS_ROOT": "/path/to/audio-sonic-mcp/jobs"
      }
    }
  }
}

🤖 Interaktionsablauf für KI-Agenten und LLMs

LLMs lernen automatisch, wie sie diesen Server verwenden, indem sie die bereitgestellten Tool-Definitionen lesen. Da Audio-Stem-Trennung und CLAP-Embeddings rechenintensiv sind, verwendet Audio Sonic MCP ein asynchrones Fire-and-Forget-Job-Muster.

Automatisierter LLM-Workflow

  [User Prompts LLM]
          │
          ▼
1. Submit URL ──────────────► [Tool: get_sonic_signature]
                                      │ (Returns Job ID instantly)
                                      ▼
2. Notify User ◄───────────── [LLM acknowledges job is queued]
          │
          ├───► 3. Wait 10-15s (Or proceed with other tasks)
          │
          ▼
4. Check Progress ──────────► [Tool: get_job_status]
                                      │ (Checks status: running/success/error)
                                      ▼
5. Present Signature ◄─────── [LLM formats rich output for user]

Natürliche Eingabeaufforderungen zum Ausprobieren

• „Überprüfe den Zustand meines audio-sonic-mcp-Servers, um sicherzustellen, dass alle ML-Komponenten bereit sind."

• „Reiche diesen YouTube-Track zur Klanganalyse ein: https://www.youtube.com/watch?v=XXXXXX."

• „Überprüfe den Fortschritt meines Sonic-Signatur-Jobs sig_a1b2c3d4 und fasse BPM, Produktionsbreite und Vibe zusammen, sobald er abgeschlossen ist."

🎚️ CLI-Nutzung (lokale Dateien)

Für Musiker, Ingenieure und Produzenten, die direkt im Terminal arbeiten, kannst du eine vollständige lokale Datei direkt analysieren, ohne Hintergrundserver auszuführen:

# Get a visual, musician-friendly sonic signature digest (recommended)
python analyze_file.py "my_demo.wav" --summary

# Print full raw JSON directly to the stdout stream
python analyze_file.py "my_demo.wav"

# Dump JSON payload to a file while keeping the stdout clean
python analyze_file.py "my_demo.wav" > signature.json

Referenz der CLI-Befehlsoptionen

Unterstützte Dateiformate: wav, mp3, flac, ogg, m4a, aac.

🔧 Referenz der Umgebungsvariablen

Konfiguriere Umgebungsoptionen, indem du diese Variablen in deiner aktiven Terminalsitzung, in der Containerumgebung oder im env-Block deiner MCP-Konfigurationsdatei deklarierst:

🐳 Docker-/Podman-Ausführung

Wenn du die Einrichtung lokaler Python-Bibliotheken vermeiden möchtest, kapselt die Ausführung über Container FFmpeg, yt-dlp und die Kern-Python-Abhängigkeiten (CPU-basierte Pipeline):

# Build the container image
docker build -t audio-sonic-mcp .

# Run the MCP server over stdio, mounting local folders for job persistence
docker run -i --rm \
  -v "$(pwd)/jobs:/app/jobs" \
  -v "$(pwd)/models:/app/models" \
  audio-sonic-mcp

Um Claude Desktop mit deinem Docker-Container zu verbinden, konfiguriere claude_desktop_config.json:

{
  "mcpServers": {
    "audio-sonic-mcp-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/absolute/path/to/jobs:/app/jobs",
        "-v", "/absolute/path/to/models:/app/models",
        "audio-sonic-mcp"
      ]
    }
  }
}

⚙️ So funktioniert es im Hintergrund

Die Pipelines von Audio Sonic MCP sind modular aufgebaut und verwenden transaktionale Checkpoints, um Zuverlässigkeit zu gewährleisten.

  LLM Agent / Claude Desktop                 Musician (Terminal)
            │                                          │
            │  MCP (stdio JSON-RPC)                    │  analyze_file.py
            ▼                                          ▼
┌──────────────────────────────────────────────────────────────────────────┐
│  Modular 6-Stage Analysis Pipeline                                       │
│                                                                          │
│  Stage 1: Ingestion   │ Pre-checks format, scans duration metadata       │
│  Stage 2: Download    │ Fetches audio tracks via yt-dlp (URLs only)      │
│  Stage 3: Conversion  │ normalizes sample formats to 44.1kHz WAV (FFmpeg)│
│  Stage 4: Separation  │ Splits stems: Vocals, Drums, Bass, Other (Demucs)│
│  Stage 5: Analysis    │ Computes BPM, modulations, key, punch (librosa)  │
│  Stage 6: Embeddings  │ Generates 512-dim zero-shot music vibe tags (CLAP)│
└─────────────────────────────────────┬────────────────────────────────────┘
                                      ▼
             Result Payload: (header · sonic_signature · telemetry)

1. Stem-Demixing: Das Demucs (mdx_extra) von Meta AI trennt den Track in isolierte Stems (vocals, drums, bass, other). Falls nicht vorhanden, fällt es sanft auf Harmonic-Percussive Source Separation (HPSS) zurück.

2. Analyse-Engine: librosa extrahiert rhythmische und tonale Strukturen und gleicht Akkordmuster und Sub-Bass-Bewegungen mit den Krumhansl-Schmuckler- und phrygischen Vorlagen-Engines ab.

3. Semantisches Vibe-Tagging: LAION CLAP (laion/larger_clap_music_and_speech) führt Zero-Shot-Inferenz gegen hochabdeckende ästhetische Deskriptoren (Stimmungen, Texturen, Genres) durch und wählt die besten Kandidaten über stilistische Pole hinweg.

🩺 Belastbarkeit & Fehlerbehebung

1. Einmalige Download-Verzögerungen bei der Einrichtung

Beim allerersten Analyse-Job, der die vollständige ML-Pipeline nutzt, laden demucs und transformers ihre vortrainierten Modellgewichte herunter (ungefähr 400 MB für Demucs und 200 MB für CLAP).

• Der Server leitet Download-Fortschrittsanzeigen an stderr um, damit sie den JSON-RPC-Standardstream nicht beschädigen.

• Während dieses Downloads bleibt get_job_status auf running. Erlaube 1–3 Minuten, abhängig von deiner Netzwerkgeschwindigkeit. Nachfolgende Starts dauern unter 10 Sekunden.

2. FastMCP-Parallelitätssteuerung

Modellinferenz auf mehrstufigen Architekturen ist stark CPU/VRAM-intensiv. Um Verbraucherhardware und virtuelle Umgebungen vor Abstürzen (OutOfMemory-Ausnahmen) zu schützen, erzwingt Audio Sonic MCP eine strikte globale Serialisierungssperre (CONCURRENCY_LOCK).

• Wenn Sie mehrere URLs gleichzeitig übermitteln, werden sie sequenziell verarbeitet.

• Das Abfragen von get_job_status für nachfolgende Aufträge meldet queued oder running, während sie in der Pipeline-Warteschlange warten.

3. Windows-Librosa-Deadlock-Fix

Die Thread-Verteilung von FastMCP unter Windows kann Numba-Kompilierungs-Deadlocks in Hintergrund-Worker-Threads verursachen. Um dies zu verhindern, integriert Audio Sonic MCP eine Pre-Warming-Routine (_prewarm_librosa() und _prewarm_demucs()) beim Start. Sie erzwingt die JIT-Kompilierung von Resampling-, HPSS- und Mono-Mixing-Funktionen im Hauptthread, bevor der RPC-Listener gestartet wird.

4. BPM-Genauigkeit und das bpm_engine-Feld

Das Tempo wird vom madmom-RNN-Beat-Tracker geschätzt. madmom ist eine optionale Abhängigkeit: Es wird nicht mehr gewartet (neueste Version 0.16.1, Klassifikatoren enden bei Python 3.7) und erfordert einen Cython-Build, daher kann es nicht überall zuverlässig installiert werden und ist nicht Teil der Standardinstallation.

Wenn madmom nicht verfügbar ist, greift die Pipeline auf librosa zurück. Dieser Fallback ist bei gleichmäßigem Four-on-the-Floor-Material gut, kann aber auf ein 2:3- oder Oktav-Vielfaches des tatsächlichen Tempos fixieren – bei einem unserer Regressionstestdaten meldet es 99,4 BPM gegenüber einer Ground Truth von 148.

Daher wird das Tempo nie ohne Qualifikation gemeldet. Jede Nutzlast enthält ein bpm_engine-Feld, das die Engine benennt, die die Zahl tatsächlich erzeugt hat:

check_health meldet den Status von madmom explizit. Um den genauen Pfad zu aktivieren:

pip install ".[beats]"

Wenn der Build auf einem aktuellen Python fehlschlägt, verwenden Sie 3.10 für die Analyseumgebung – madmom hat keine Wheels für neuere Interpreter.

5. Diagnose mit check_health

Wenn der Server als degraded meldet oder Tools fehlen, rufen Sie das check_health-Tool auf oder prüfen Sie CLI-Warnungen. Es fragt ab:

• Verfügbarkeit von ffmpeg im Ausführungspfad.

• Installationsstatus von Python-Paketen (librosa, soundfile, mcp usw.).

• Vorhandensein des optionalen madmom-Beat-Trackers und welche bpm_engine dadurch verwendet wird.

• Zugriffsrechte auf das JOBS_ROOT-Verzeichnis.

🛠️ Entwicklung & Tests

Führen Sie Unit-Tests in Ihrer virtuellen Umgebung aus, um die mathematischen Pipelines mit synthetisierten Audio-Wellenformen zu verifizieren:

# Install development test framework
pip install -e ".[dev]"

# Execute full suite (requires no network or model downloads)
pytest

# Test specifically CLI execution code paths
pytest tests/test_cli.py

📄 Lizenz

Verteilt unter der MIT-Lizenz. Siehe LICENSE für Details.

© 2026 Ripunjay Kashyap. Alle Rechte vorbehalten.