Audio Sonic MCP

🎵 Audio Sonic MCP

あらゆる曲を構造化された「音のシグネチャ」に変換します。テンポ、音楽キー、512 次元の CLAP バイブ埋め込み、人が読み取れるバイブタグ、プロダクションプロファイルを、ローカルでの単一の呼び出しから抽出します。

Audio Sonic MCP はローカルマシン上で完全に動作し（API キー、外部サーバー、クラウド依存関係は不要です）、同じ高精度オーディオ分析エンジンへの 2 つのプレミアムなアクセス手段を提供します。

	対象	主なインターフェースと仕組み
🤖 MCP サーバー	LLM、AI エージェント、IDE（Claude、Cursor、Windsurf、Cline）	YouTube URL を非同期で、呼び出し後すぐに制御を返して分析します。重いオーディオ処理中にクライアント LLM がブロックされるのを防ぎます。
🎚️ ローカル CLI	ミュージシャン、サウンドプロデューサー、オーディオエンジニア	ローカルファイルを対象とした高機能なコマンドラインツールです。曲全体を複数のウィンドウで分析し、高精度な出力を提供します。

---

🎹 お試し：得られる内容

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

---

⚡ 主な機能

• 🥁 テンポとビートの追跡 — 可変テンポのドリフト検出とトランジェントウィンドウ処理を用いて、BPM を完全に算出します。
• 🎹 キーとハーモニーのマッピング — 構造上の音楽キーとモードを算出し、セクションごとの転調を追跡する詳細な key_map を生成します。
• 🌈 バイブとスタイルの埋め込み — ゼロショットの音楽語彙分類を使って、512 次元の CLAP 埋め込みと、人が読み取れるスタイルタグ（エネルギー、質感、ムード、ジャンルを網羅）を生成します。
• 🎚️ プロダクション分析 — ボーカルの空間的な存在感、トランジェントのパンチ係数、ステレオ幅、主要な周波数ピークを測定します。
• 🤖 MCP ネイティブシステム — 標準化された 4 つの Model Context Protocol ツールを全面的に提供し、AI ツールにすぐ統合できます。
• 🪶 堅牢なグレースフルデグラデーション — CUDA GPU がある場合は自動的に使用し、ない場合は CPU にフォールバックします。大規模なディープラーニングパッケージ（[clap]）を省略した場合も、HPSS と標準の librosa 特徴量配列へグレースフルに切り替えます。
• 🔒 完全オフラインでプライベート — 変換、分離、推論はすべてローカルで実行されます。

---

📦 インストールとセットアップ

システム要件

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）とゼロショットのバイブベクトル（CLAP）が含まれます。約 4 GB のディスク容量が必要です。

     pip install -e ".[clap]"
     

   • オプション B：軽量なコアパイプライン 標準的なデジタル信号処理（HPSS/librosa）を使用します。インストールが速く、必要な容量も最小限です。

     pip install -e .
     

メモ

オプションの [clap] スタックをインストールすると、torch、torchaudio、transformers、demucs がインストールされます。これらがない場合、サーバーは自動的に軽量な代替手段に切り替わります（Demucs の代わりに HPSS、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"
      }
    }
  }
}

重要

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 は非同期のファイア・アンド・フォーゲット型ジョブパターンを採用しています。

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 コマンドオプションのリファレンス

オプション	短縮形	説明
path	なし	ローカル音声ファイルへの絶対パスまたは相対パスです（必須）。
--summary	-s	標準の JSON の代わりに、整形された見やすいターミナルサマリーを出力します。
--no-vector	なし	JSON シグネチャを生成しますが、512 次元の大容量な vibe 浮動小数点配列は省略します。
--out FILE	-o	最終的な JSON シグネチャを指定したファイルに直接出力します。
--keep	-k	jobs/ 内の中間 WAV ファイルや分離したステムファイルを削除しません。
--job-id ID	-j	内部識別子を明示的に指定します（バッチスクリプトで便利です）。

対応ファイル形式：wav、mp3、flac、ogg、m4a、aac。

---

🔧 環境変数のリファレンス

使用中のターミナルセッション、コンテナー環境、または MCP 設定ファイルの env ブロックでこれらの変数を宣言して、環境オプションを設定します。

変数	デフォルト値	説明／実用例
JOBS_ROOT	./jobs	音声ファイル、一時変換された WAV、ステムを処理するワークスペースディレクトリです。
KEEP_JOB_FILES	未設定	1 または true に設定すると、分離したステム WAV をディスク上に保持します（ジョブごとに約 75 MB 増加します。トラブルシューティングに便利です）。
FILE_MAX_DURATION_SEC	600	ローカルファイルの処理時間の安全上限です（YouTube のダウンロードは最大 60 分に制限されます）。
FFMPEG_BIN	未設定	ffmpeg バイナリがシステムの PATH にない場合、そのバイナリを含むフォルダーへのパスです。
YTDLP_PROXY	未設定	レート制限やネットワークブロックを回避するために、yt-dlp に直接渡す HTTP/SOCKS プロキシ文字列です。
TRANSPORT_MODE	stdio	サーバーが待ち受けるトランスポートです：stdio（デフォルト、ローカル MCP クライアント向け）、sse（HTTP 経由のリモート MCP）、または hybrid（MCP SSE および app_cloud.py の REST API）です。sse／hybrid には pip install ".[cloud]" が必要です。
PORT	8000	TRANSPORT_MODE が sse または hybrid の場合の待ち受けポートです。stdio では無視されます。

---

🐳 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）に分離します。利用できない場合は、調波・打楽器音源分離（HPSS） にフォールバックします。
2. 分析エンジン：librosa がリズムと調性の構造を抽出し、コードパターンやサブベースの動きを Krumhansl-Schmuckler および Phrygian のテンプレートエンジンと照合します。
3. セマンティックな雰囲気のタグ付け：LAION CLAP（laion/larger_clap_music_and_speech）が、幅広い美的特徴の記述（ムード、テクスチャ、ジャンル）に対してゼロショット推論を実行し、さまざまなスタイルの候補から上位のものを選びます。

---

🩺 耐障害性とトラブルシューティング

1. 初回セットアップ時のダウンロード遅延

ML パイプライン全体を使用する最初の分析ジョブでは、demucs と transformers が事前学習済みモデルの重みをダウンロードします（Demucs は約 400 MB、CLAP は約 200 MB です）。

• サーバーはダウンロードの進捗表示を stderr にリダイレクトするため、JSON-RPC の標準ストリームを破損しません。
• ダウンロード中、get_job_status は running のままになります。ネットワーク速度に応じて 1～3 分お待ちください。2 回目以降の起動は 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 にフォールバックします。このフォールバックは、安定した四つ打ちの素材では良好に動作しますが、実際のテンポに対して 2:3 または 2 倍の値を検出することがあります。回帰テスト用フィクスチャの一つでは、正解値が 148 BPM であるのに対し、99.4 BPM と報告されます。

そのため、テンポは必ずエンジン名とともに報告されます。すべてのペイロードには、実際に値を生成したエンジンを示す bpm_engine フィールドが含まれます。

bpm_engine	意味
madmom	RNN ビートトラッカー — 高精度です。
librosa-fallback	madmom を利用できません。BPM は概算として扱い、オクターブや三連符の誤検出が時折発生することを想定してください。

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.