🎵 Audio Sonic MCP

Convierte cualquier canción en una "firma sónica" estructurada: extrae tempo, tonalidad musical, un embedding de vibra CLAP de 512 dimensiones, etiquetas de vibra legibles por humanos y un perfil de producción, todo desde una única llamada local.

Audio Sonic MCP se ejecuta completamente en tu máquina local (sin necesidad de claves API, servidores externos ni dependencias en la nube) y expone dos puntos de acceso premium al mismo motor de análisis de audio de alta fidelidad:

🎹 Prueba rápida: Lo que obtienes

1. Resumen CLI para músicos (modo --summary)

🎵 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. JSON completo (devuelto por MCP y CLI por defecto)

{
  "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

⚡ Características principales

• 🥁 Detección de tempo y ritmo — Cálculo completo de BPM con detección de deriva de tempo variable y ventanas transitorias.

• 🎹 Mapeo de tonalidad y armónico — Calcula la tonalidad y el modo musical estructural, generando un key_map detallado que rastrea las modulaciones sección por sección.

• 🌈 Embeddings de vibra y estilo — Compila un embedding CLAP de 512 dimensiones y etiquetas de estilo legibles por humanos (que cubren energía, textura, estado de ánimo y género) mediante clasificación de vocabulario musical de cero disparos.

• 🎚️ Analítica de producción — Mide la presencia espacial vocal, los coeficientes de impacto transitorio, la anchura estéreo y los picos de frecuencia dominantes.

• 🤖 Sistema nativo MCP — Expone completamente 4 herramientas estandarizadas del Protocolo de Contexto de Modelo para una integración instantánea en herramientas de IA.

• 🪶 Degradación elegante y robusta — Utiliza automáticamente una GPU CUDA si está presente y recurre a la CPU; se degrada con elegancia a HPSS y matrices de características estándar de librosa si se omiten los paquetes pesados de aprendizaje profundo ([clap]).

• 🔒 100% sin conexión y privado — Toda la conversión, separación e inferencia ocurren localmente.

📦 Instalación y configuración

Requisitos previos del sistema

Asegúrate de tener Python 3.10+ y FFmpeg instalados y accesibles en tu PATH del sistema.

Instalación de FFmpeg:

• macOS: brew install ffmpeg

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

• Windows: Ejecuta winget install Gyan.FFmpeg mediante PowerShell (Administrador), o descárgalo manualmente desde ffmpeg.org y añade el directorio bin a las variables de entorno de tu sistema.

Instalación paso a paso

1. Clona el repositorio

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

2. Inicializa el entorno virtual

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

3. Instala las dependencias Elige entre el motor central ligero o el conjunto completo de ML de alta fidelidad:

   • Opción A: Conjunto completo de ML de alta fidelidad (recomendado) Incluye separación de stems (Demucs) y vectores de vibra de cero disparos (CLAP). Requiere ~4 GB de espacio en disco.

     pip install -e ".[clap]"

   • Opción B: Pipeline central ligero Utiliza procesamiento digital de señales estándar (HPSS/librosa). Instalación rápida y huella mínima.

     pip install -e .

[!NOTA] El stack opcional [clap] instala torch, torchaudio, transformers y demucs. Sin estos, el servidor cambia automáticamente a alternativas ligeras (HPSS en lugar de Demucs, matrices de características estándar en lugar de vectores CLAP, y omite vibe_tags).

🤖 Guía de configuración del cliente MCP

Audio Sonic MCP se registra como un script de paquete estándar. Esto te permite ejecutarlo usando el nombre ejecutable global (audio-sonic-mcp) directamente desde la carpeta bin de tu entorno virtual, o ejecutar el archivo de script manualmente.

1. Configuración de Claude Desktop

Abre tu archivo de configuración de Claude:

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

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

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

Añade el servidor a tu objeto mcpServers:

{
  "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"
      }
    }
  }
}

[!IMPORTANTE] Usuarios de Windows: Usa siempre doble barra invertida (\\) en las rutas de configuración JSON. Apunta el ejecutable directamente al .exe dentro de tu directorio .venv\Scripts\.

2. Integración con Cursor IDE

Para integrar Audio Sonic MCP en el panel de IA de Cursor:

1. Navega a Configuración ➔ Funciones ➔ MCP.

2. Haz clic en + Añadir nuevo servidor MCP.

3. Rellena los parámetros:

   • Nombre: audio-sonic-mcp

   • Tipo: command

   • Comando: /path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp (usa la extensión .exe en Windows)

3. Integración con Windsurf

Abre tu archivo de configuraciones MCP de Windsurf (normalmente en ~/.codeium/windsurf/mcp_config.json) y añade la configuración:

{
  "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. Configuración de Cline (extensión de VS Code)

Abre el archivo de configuración MCP de Cline (normalmente en %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json o almacenamiento equivalente de la plataforma) y añade:

{
  "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"
      }
    }
  }
}

🤖 Flujo de interacción para agentes de IA y LLMs

Los LLMs aprenden automáticamente a usar este servidor leyendo las definiciones de herramientas expuestas. Debido a que la separación de stems de audio y los embeddings CLAP son computacionalmente exigentes, Audio Sonic MCP utiliza un patrón de trabajo asíncrono de tipo "dispara y olvida".

Flujo de trabajo automatizado para LLMs

  [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]

Prompts naturales para probar

• "Comprueba el estado de mi servidor audio-sonic-mcp para asegurarte de que todos los componentes de ML están listos."

• "Envía esta pista de YouTube para análisis sónico: https://www.youtube.com/watch?v=XXXXXX."

• "Comprueba el progreso de mi trabajo de firma sónica sig_a1b2c3d4 y resume el BPM, la anchura de producción y la vibra cuando esté completo."

🎚️ Uso de la CLI (archivos locales)

Para músicos, ingenieros y productores que trabajan directamente en la terminal, puedes analizar un archivo local de larga duración directamente sin ejecutar ningún servidor en segundo plano:

# 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

Referencia de opciones de comandos de la CLI

Formatos de archivo compatibles: wav, mp3, flac, ogg, m4a, aac.

🔧 Referencia de variables de entorno

Configura las opciones de entorno declarando estas variables en tu sesión de terminal activa, entorno de contenedor o bloque env de tu archivo de configuración MCP:

🐳 Ejecución con Docker / Podman

Si prefieres evitar configurar bibliotecas Python locales, ejecutar mediante contenedores encapsula FFmpeg, yt-dlp y las dependencias Python principales (pipeline basado en CPU):

# 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

Para conectar Claude Desktop a tu contenedor Docker, configura 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"
      ]
    }
  }
}

⚙️ Cómo funciona internamente

Los pipelines de Audio Sonic MCP se construyen de forma modular, utilizando puntos de control transaccionales para garantizar la fiabilidad.

  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. Separación de stems: El Demucs (mdx_extra) de Meta AI separa la pista en stems aislados (vocals, drums, bass, other). Si falta, se degrada con elegancia a Separación de Fuentes Armónico-Percusiva (HPSS).

2. Motor de análisis: librosa extrae estructuras rítmicas y tonales, comparando patrones de acordes y movimientos de subgraves con los motores de plantillas Krumhansl-Schmuckler y Frigio.

3. Etiquetado semántico de vibra: LAION CLAP (laion/larger_clap_music_and_speech) ejecuta inferencia de cero disparos contra descriptores estéticos de alta cobertura (estados de ánimo, texturas, géneros), eligiendo los mejores candidatos entre polos estilísticos.

🩺 Resiliencia y solución de problemas

1. Retrasos de descarga de configuración única

En el primer trabajo de análisis que utilice el pipeline completo de ML, demucs y transformers descargarán sus pesos de modelo preentrenados (aproximadamente 400 MB para Demucs y 200 MB para CLAP).

• El servidor redirige los indicadores de progreso de descarga a stderr para que no corrompan el flujo estándar JSON-RPC.

• Durante esta descarga, get_job_status permanecerá en running. Permite de 1 a 3 minutos dependiendo de la velocidad de tu red. Los arranques posteriores tardan menos de 10 segundos.

2. Controles de concurrencia de FastMCP

La inferencia de modelos en arquitecturas de múltiples etapas consume mucha CPU/VRAM. Para proteger el hardware de consumo y los entornos virtuales de fallos (excepciones OutOfMemory), Audio Sonic MCP aplica un bloqueo estricto de serialización global (CONCURRENCY_LOCK).

• Si envías varias URL simultáneamente, se procesarán secuencialmente.

• Consultar get_job_status para trabajos posteriores informará queued o running mientras esperan en la cola del pipeline.

3. Corrección del bloqueo de Librosa en Windows

El despacho de hilos de FastMCP en Windows puede provocar bloqueos de compilación de Numba dentro de los hilos de trabajo en segundo plano. Para evitarlo, Audio Sonic MCP incorpora una Rutina de precalentamiento (_prewarm_librosa() y _prewarm_demucs()) al iniciarse. Fuerza la compilación JIT de las funciones de remuestreo, HPSS y mezcla mono en el hilo principal antes de iniciar el listener RPC.

4. Precisión del BPM y el campo bpm_engine

El tempo se estima mediante el detector de pulsos RNN de madmom. madmom es una dependencia opcional: no recibe mantenimiento (última versión 0.16.1, los clasificadores llegan hasta Python 3.7) y requiere una compilación de Cython, por lo que no se puede instalar de forma fiable en todos los entornos y no forma parte de la instalación predeterminada.

Cuando madmom no está disponible, el pipeline recurre a librosa. Ese recurso funciona bien con material de cuatro por cuatro constante, pero puede fijarse en un múltiplo 2:3 o de octava del tempo real: en uno de nuestros fixtures de regresión informa 99.4 BPM frente a un valor real de 148.

Por lo tanto, el tempo nunca se informa sin calificar. Cada payload incluye un campo bpm_engine que indica el motor que realmente produjo el número:

check_health informa explícitamente del estado de madmom. Para habilitar la ruta precisa:

pip install ".[beats]"

Si la compilación falla en una versión reciente de Python, usa 3.10 para el entorno de análisis: madmom no tiene wheels para intérpretes más nuevos.

5. Diagnóstico con check_health

Si el servidor informa como degraded o faltan herramientas, llama a la herramienta check_health o revisa las advertencias de la CLI. Consulta:

• Disponibilidad de ffmpeg en la ruta de ejecución.

• Estado de instalación de los paquetes de Python (librosa, soundfile, mcp, etc.).

• Presencia del detector de pulsos opcional madmom, y qué bpm_engine se utilizará como resultado.

• Permisos de acceso al directorio JOBS_ROOT.

🛠️ Desarrollo y pruebas

Ejecuta las pruebas unitarias dentro de tu entorno virtual para verificar los pipelines matemáticos utilizando formas de onda de audio sintetizadas:

# 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

📄 Licencia

Distribuido bajo la Licencia MIT. Consulta LICENSE para más detalles.

© 2026 Ripunjay Kashyap. Todos los derechos reservados.