🎵 Audio Sonic MCP

모든 노래를 구조화된 "소닉 시그니처"로 변환합니다 — 템포, 음악 키, 512차원 CLAP 바이브 임베딩, 사람이 읽을 수 있는 바이브 태그, 그리고 프로덕션 프로필을 단일 로컬 호출로 추출합니다.

Audio Sonic MCP는 전적으로 로컬 머신에서 실행되며(API 키, 외부 서버, 클라우드 의존성 불필요), 동일한 고충실도 오디오 분석 엔진에 대한 두 가지 프리미엄 액세스 포인트를 제공합니다:

🎹 빠른 맛보기: 무엇을 얻을 수 있나

1. 음악가 친화적 CLI 요약 (--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 (MCP 및 CLI에서 기본적으로 반환)

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

⚡ 주요 기능

• 🥁 템포 및 비트 추적 — 가변 템포 드리프트 감지 및 과도 윈도우 처리를 포함한 전체 BPM 계산.

• 🎹 키 및 화성 매핑 — 구조적 음악 키 + 모드를 계산하고, 섹션별 조옮김을 추적하는 상세한 key_map 생성.

• 🌈 바이브 및 스타일 임베딩 — 512차원 CLAP 임베딩과 사람이 읽을 수 있는 스타일 태그(에너지, 질감, 분위기, 장르 포함)를 zero-shot 음악 어휘 분류를 사용하여 컴파일.

• 🎚️ 프로덕션 분석 — 보컬 공간 존재감, 과도 펀치 계수, 스테레오 폭, 지배적 주파수 피크 측정.

• 🤖 MCP 네이티브 시스템 — AI 도구에 즉시 통합할 수 있도록 4개의 표준화된 Model Context Protocol 도구를 완전히 노출.

• 🪶 강력한 우아한 성능 저하 — CUDA GPU가 있으면 자동으로 사용하고 CPU로 폴백; 무거운 딥러닝 패키지([clap])가 없으면 HPSS 및 표준 librosa 특징 배열로 우아하게 저하.

• 🔒 100% 오프라인 및 프라이빗 — 모든 변환, 분리, 추론이 로컬에서 발생.

📦 설치 및 설정

시스템 사전 요구 사항

Python 3.10+ 및 FFmpeg가 설치되어 시스템 PATH에 액세스 가능한지 확인하세요.

FFmpeg 설치:

• macOS: brew install ffmpeg

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

• Windows: PowerShell(관리자)에서 winget install Gyan.FFmpeg 실행, 또는 ffmpeg.org에서 수동으로 다운로드하고 bin 디렉터리를 시스템 환경 변수에 추가.

단계별 설치

1. 저장소 복제

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

2. 가상 환경 초기화

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

3. 의존성 설치 경량 코어 엔진 또는 전체 고충실도 ML 제품군 중 선택:

   • 옵션 A: 전체 고충실도 ML 제품군 (권장) 데믹싱 스템(Demucs) 및 zero-shot 바이브 벡터(CLAP) 포함. 약 4GB 디스크 공간 필요.

     pip install -e ".[clap]"

   • 옵션 B: 코어 경량 파이프라인 표준 디지털 신호 처리(HPSS/librosa) 사용. 빠른 설치 및 최소 공간.

     pip install -e .

[!NOTE] 선택적 [clap] 스택은 torch, torchaudio, transformers, demucs를 설치합니다. 이것들이 없으면 서버는 자동으로 경량 폴백(HPSS 대신 Demucs, CLAP 벡터 대신 표준 특징 행렬, vibe_tags 제외)으로 전환합니다.

🤖 MCP 클라이언트 구성 가이드

Audio Sonic MCP는 표준 패키지 스크립트로 등록됩니다. 이를 통해 가상 환경의 bin 폴더에서 전역 실행 파일 이름(audio-sonic-mcp)으로 직접 실행하거나 스크립트 파일을 수동으로 실행할 수 있습니다.

1. Claude Desktop 설정

Claude 구성 파일을 엽니다:

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

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

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

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

[!IMPORTANT] Windows 사용자: JSON 구성 경로에서 항상 이중 백슬래시(\\)를 사용하세요. 실행 파일을 .venv\Scripts\ 디렉터리 안의 .exe로 직접 지정하세요.

2. Cursor IDE 통합

Audio Sonic MCP를 Cursor의 AI 창에 통합하려면:

1. Settings ➔ Features ➔ MCP로 이동.

2. + Add New MCP Server 클릭.

3. 매개변수 입력:

   • Name: audio-sonic-mcp

   • Type: command

   • Command: /path/to/audio-sonic-mcp/.venv/bin/audio-sonic-mcp (Windows에서는 .exe 확장자 사용)

3. Windsurf 통합

Windsurf MCP 구성 파일(일반적으로 ~/.codeium/windsurf/mcp_config.json에 위치)을 열고 구성을 추가합니다:

{
  "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 확장) 설정

Cline의 MCP 설정 파일(일반적으로 %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json 또는 해당 플랫폼 저장소에 위치)을 열고 추가합니다:

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

🤖 AI 에이전트 및 LLM을 위한 상호 작용 흐름

LLM은 노출된 도구 정의를 읽고 이 서버를 사용하는 방법을 자동으로 학습합니다. 오디오 스템 분리 및 CLAP 임베딩은 계산 집약적이므로 Audio Sonic MCP는 비동기 Fire-and-Forget 작업 패턴을 사용합니다.

자동화된 LLM 워크플로우

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

시도해 볼 자연스러운 프롬프트

• "내 audio-sonic-mcp 서버의 상태를 확인하여 모든 ML 구성 요소가 준비되었는지 확인해 줘."

• "이 YouTube 트랙을 소닉 분석에 제출: https://www.youtube.com/watch?v=XXXXXX."

• "내 소닉 시그니처 작업 sig_a1b2c3d4의 진행 상황을 확인하고 완료되면 BPM, 프로덕션 폭, 바이브를 요약해 줘."

🎚️ CLI 사용법 (로컬 파일)

터미널에서 직접 작업하는 음악가, 엔지니어, 프로듀서를 위해 백그라운드 서버를 실행하지 않고 전체 길이 로컬 파일을 직접 분석할 수 있습니다:

# 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

CLI 명령 옵션 참조

지원되는 파일 형식: wav, mp3, flac, ogg, m4a, aac.

🔧 환경 변수 참조

활성 터미널 세션, 컨테이너 환경 또는 MCP 구성 파일의 env 블록에서 이러한 변수를 선언하여 환경 옵션을 구성합니다:

🐳 Docker / Podman 실행

로컬 Python 라이브러리 설정을 피하려면 컨테이너를 통해 FFmpeg, yt-dlp 및 핵심 Python 의존성(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

Claude Desktop을 Docker 컨테이너에 연결하려면 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 파이프라인은 모듈식으로 구성되며, 신뢰성을 보장하기 위해 트랜잭션 체크포인트를 사용합니다.

  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. 스템 데믹싱: Meta AI의 Demucs (mdx_extra) 가 트랙을 분리 스템(vocals, drums, bass, other)으로 분리합니다. 없으면 Harmonic-Percussive Source Separation (HPSS) 로 우아하게 폴백합니다.

2. 분석 엔진: librosa가 리듬 및 음조 구조를 추출하고, 코드 패턴과 서브베이스 움직임을 Krumhansl-Schmuckler 및 Phrygian 템플릿 엔진과 매칭합니다.

3. 의미적 바이브 태깅: LAION CLAP (laion/larger_clap_music_and_speech)가 높은 커버리지의 미적 설명자(분위기, 질감, 장르)에 대해 zero-shot 추론을 실행하고, 스타일 극점에서 상위 후보를 선택합니다.

🩺 복원성 및 문제 해결

1. 일회성 설정 다운로드 지연

전체 ML 파이프라인을 사용하는 첫 번째 분석 작업에서 demucs 및 transformers가 사전 훈련된 모델 가중치(Demucs 약 400 MB, CLAP 약 200 MB)를 다운로드합니다.

• 서버는 다운로드 진행 표시기를 stderr로 리디렉션하여 JSON-RPC 표준 스트림을 손상시키지 않습니다.

• 이 다운로드 중 get_job_status는 running 상태로 유지됩니다. 네트워크 속도에 따라 1~3분 허용. 이후 시작은 10초 미만이 소요됩니다.

2. FastMCP 동시성 제어

다단계 아키텍처에서의 모델 추론은 CPU/VRAM 사용량이 매우 높습니다. 소비자 하드웨어와 가상 환경이 충돌(OutOfMemory 예외)하는 것을 보호하기 위해, Audio Sonic MCP는 엄격한 전역 직렬화 잠금(CONCURRENCY_LOCK)을 적용합니다.

• 여러 URL을 동시에 제출하면 순차적으로 처리됩니다.

• 후속 작업에 대해 get_job_status를 폴링하면 파이프라인 큐에서 대기하는 동안 queued 또는 running으로 보고됩니다.

3. Windows Librosa 교착 상태 수정

Windows에서 FastMCP 스레드 디스패칭은 백그라운드 작업자 스레드 내부에서 Numba 컴파일 교착 상태를 유발할 수 있습니다. 이를 방지하기 위해 Audio Sonic MCP는 시작 시 사전 워밍 루틴(_prewarm_librosa() 및 _prewarm_demucs())을 포함합니다. RPC 리스너를 시작하기 전에 메인 스레드에서 리샘플링, HPSS 및 모노 믹싱 함수의 JIT 컴파일을 강제합니다.

4. BPM 정확도 및 bpm_engine 필드

템포는 madmom의 RNN 비트 트래커로 추정됩니다. madmom은 선택적 의존성입니다: 유지 관리되지 않으며(최신 릴리스 0.16.1, 분류자는 Python 3.7에서 중단됨) Cython 빌드가 필요하므로 모든 환경에서 안정적으로 설치할 수 없으며 기본 설치의 일부가 아닙니다.

madmom을 사용할 수 없으면 파이프라인은 librosa로 대체됩니다. 이 대체는 꾸준한 four-on-the-floor 자료에서는 좋지만 실제 템포의 2:3 또는 옥타브 배수에 고정될 수 있습니다. 회귀 테스트 픽스처 중 하나에서 실제값 148에 대해 99.4 BPM으로 보고합니다.

따라서 템포는 단정적으로 보고되지 않습니다. 모든 페이로드에는 실제로 숫자를 생성한 엔진을 명명하는 bpm_engine 필드가 포함됩니다:

check_health는 madmom의 상태를 명시적으로 보고합니다. 정확한 경로를 활성화하려면:

pip install ".[beats]"

최신 Python에서 빌드가 실패하면 분석 환경에 3.10을 사용하십시오. madmom에는 최신 인터프리터용 휠이 없습니다.

5. check_health로 진단하기

서버가 degraded로 보고되거나 도구가 누락된 경우 check_health 도구를 호출하거나 CLI 경고를 확인하십시오. 다음을 조회합니다:

• 실행 경로에서 ffmpeg 사용 가능 여부.

• Python 패키지(librosa, soundfile, mcp 등)의 설치 상태.

• 선택적 madmom 비트 트래커의 존재 여부와 그 결과로 사용될 bpm_engine.

• JOBS_ROOT 디렉터리에 대한 액세스 권한.

🛠️ 개발 및 테스트

가상 환경 내에서 단위 테스트를 실행하여 합성 오디오 파형으로 수학적 파이프라인을 검증하십시오:

# 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

📄 라이선스

MIT License에 따라 배포됩니다. 자세한 내용은 LICENSE를 참조하십시오.

© 2026 Ripunjay Kashyap. All rights reserved.