接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
docker run -i --rm ghcr.io/ripunjay-kashyap/audio-sonic-mcp:1.2.0Claude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
JOBS_ROOT=<value> KEEP_JOB_FILES=<value> claude mcp add ripunjay-kashyap-audio-sonic-mcp -- docker run -i --rm ghcr.io/ripunjay-kashyap/audio-sonic-mcp:1.2.0在終端機中執行。
{ "mcpServers": { "ripunjay-kashyap-audio-sonic-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/ripunjay-kashyap/audio-sonic-mcp:1.2.0" ], "env": { "JOBS_ROOT": "<value>", "KEEP_JOB_FILES": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令? 兩種安裝方式的差異
來自發布者
Local MCP server + CLI turning YouTube & local audio into rich sonic signatures. Extracts BPM, section-by-section key, vocal presence, transient punch, and 512-dim CLAP vibe embeddings. Powered by Demucs stem separation & librosa. 100% private, offline-first, and GPU-accelerated with graceful CPU/HPSS degradation.
Turn any song into a structured "sonic signature" — extracting tempo, musical key, a 512-dimension CLAP vibe embedding, human-readable vibe tags, and a production profile — from a single local call.
Audio Sonic MCP runs entirely on your local machine (requiring no API keys, external servers, or cloud dependencies) and exposes two premium access points to the same underlying high-fidelity audio analysis engine:
--summary mode)🎵 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)
{
"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
}
}
key_map tracking section-by-section modulations.[clap]) are omitted.Ensure you have Python 3.10+ and FFmpeg installed and accessible on your system PATH.
brew install ffmpegsudo apt update && sudo apt install -y ffmpegwinget install Gyan.FFmpeg via PowerShell (Administrator), or download manually from ffmpeg.org and add the bin directory to your system environment variables.Clone the Repository
git clone https://github.com/ripunjay-kashyap/audio-sonic-mcp.git
cd audio-sonic-mcp
Initialize Virtual Environment
python -m venv .venv
# Activate on macOS/Linux:
source .venv/bin/activate
# Activate on Windows (PowerShell):
.venv\Scripts\activate
Install Dependencies Choose between the lightweight core engine or the full high-fidelity ML suite:
pip install -e ".[clap]"
pip install -e .
[!NOTE] The optional
[clap]stack installstorch,torchaudio,transformers, anddemucs. Without these, the server automatically switches to light fallbacks (HPSS instead of Demucs, standard feature matrices instead of CLAP vectors, and leaves outvibe_tags).
Audio Sonic MCP registers itself as a standard package script. This enables you to run it using the global executable name (audio-sonic-mcp) directly from your virtual environment's bin folder, or run the script file manually.
Open your Claude configuration file:
%APPDATA%\Claude\claude_desktop_config.json~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonAdd the server to your mcpServers object:
{
"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 Users: Always use double backslashes (
\\) in JSON configuration paths. Point the executable directly to the.exeinside your.venv\Scripts\directory.
To integrate Audio Sonic MCP into Cursor's AI pane:
audio-sonic-mcpcommand/path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp (use .exe extension on Windows)Open your Windsurf MCP configurations file (typically found at ~/.codeium/windsurf/mcp_config.json) and append the configuration:
{
"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"
}
}
}
}
Open Cline's MCP setting file (usually located at %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json or equivalent platform storage) and add:
{
"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"
}
}
}
}
LLMs automatically learn how to use this server by reading its exposed tool definitions. Because audio stem separation and CLAP embeddings are computationally demanding, Audio Sonic MCP uses an Asynchronous Fire-and-Forget Job Pattern.
[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]
https://www.youtube.com/watch?v=XXXXXX."sig_a1b2c3d4 and summarize the BPM, production width, and vibe once complete."For musicians, engineers, and producers working directly in the terminal, you can analyze a full-length local file directly without running any background servers:
# 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
Supported File Formats: wav, mp3, flac, ogg, m4a, aac.
Configure environment options by declaring these variables in your active terminal session, container environment, or the env block of your MCP configuration file:
If you prefer to avoid setting up local Python libraries, running via containers encapsulates FFmpeg, yt-dlp, and the core Python dependencies (CPU-based 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
To connect Claude Desktop to your Docker container, configure 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"
]
}
}
}
Audio Sonic MCP pipelines are constructed modularly, using transactional checkpoints to ensure reliability.
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)
mdx_extra) separates the track into isolation stems (vocals, drums, bass, other). If missing, it gracefully drops back to Harmonic-Percussive Source Separation (HPSS).laion/larger_clap_music_and_speech) runs zero-shot inference against high-coverage aesthetic descriptors (moods, textures, genres), choosing top candidates across stylistic poles.Upon the very first analysis job utilizing the full ML pipeline, demucs and transformers will download their pre-trained model weights (approximately 400 MB for Demucs, and 200 MB for CLAP).
stderr so they do not corrupt the JSON-RPC standard stream.get_job_status will remain in running. Allow 1–3 minutes depending on your network speed. Subsequent startups take under 10 seconds.Model inference on multi-staged architectures is highly CPU/VRAM intensive. To protect consumer hardware and virtual environments from crashing (OutOfMemory exceptions), Audio Sonic MCP enforces a strict global serialization lock (CONCURRENCY_LOCK).
get_job_status for subsequent jobs will report queued or running while they wait in the pipeline queue.FastMCP thread dispatching under Windows can cause Numba compilation deadlocks inside background worker threads. To prevent this, Audio Sonic MCP incorporates a Pre-warming Routine (_prewarm_librosa() and _prewarm_demucs()) on launch. It forces JIT compile of resampling, HPSS, and mono-mixing functions in the main thread before starting the RPC listener.
bpm_engine FieldTempo is estimated by madmom's RNN beat tracker. madmom is an optional dependency: it is unmaintained (latest release 0.16.1, classifiers stop at Python 3.7) and requires a Cython build, so it cannot be installed reliably everywhere and is not part of the default install.
When madmom is unavailable the pipeline falls back to librosa. That fallback is good on steady four-on-the-floor material but can lock onto a 2:3 or octave multiple of the true tempo — on one of our regression fixtures it reports 99.4 BPM against a ground truth of 148.
So the tempo is never reported unqualified. Every payload carries a bpm_engine field naming the engine that actually produced the number:
check_health reports madmom's status explicitly. To enable the accurate path:
pip install ".[beats]"
If the build fails on a recent Python, use 3.10 for the analysis environment — madmom has no wheels for newer interpreters.
check_healthIf the server reports as degraded or tools are missing, call the check_health tool or check CLI warnings. It queries:
ffmpeg on the execution path.librosa, soundfile, mcp, etc.).madmom beat tracker, and which bpm_engine will be used as a result.JOBS_ROOT directory.Run unit tests inside your virtual environment to verify the mathematical pipelines using synthesized audio waveforms:
# 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
Distributed under the MIT License. See LICENSE for details.
© 2026 Ripunjay Kashyap. All rights reserved.
Local MCP server + CLI turning YouTube & local audio into rich sonic signatures. Extracts BPM, section-by-section key, vocal presence, transient punch, and 512-dim CLAP vibe embeddings. Powered by De
{ "mcpServers": { "ripunjay-kashyap-audio-sonic-mcp": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/ripunjay-kashyap/audio-sonic-mcp:1.2.0" ], "env": { "JOBS_ROOT": "<value>", "KEEP_JOB_FILES": "<value>" } } }}總覽
Local MCP server + CLI turning YouTube & local audio into rich sonic signatures. Extracts BPM, section-by-section key, vocal presence, transient punch, and 512-dim CLAP vibe embeddings. Powered by Demucs stem separation & librosa. 100% private, offline-first, and GPU-accelerated with graceful CPU/HPSS degradation.
工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式,而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數:JOBS_ROOT, KEEP_JOB_FILES。
Audio Sonic 透過 stdio 在本機執行。
上次檢查時間:2026-10-27。 Local MCP server + CLI turning YouTube & local audio into rich sonic signatures. Extracts BPM, section-by-section key, vocal presence, transient punch, and 512-dim CLAP vibe embeddings. Powered by Demucs stem separation & librosa. 100% private, offline-first, and GPU-accelerated with graceful CPU/HPSS degradation.