Audio MCP

audio-mcp

AI エージェントのための音声認識。 言語モデルは音を聞くことができません。この MCP サーバーは、音声をモデルが推論できる情報に変換します。測定値、平易な言葉による問題の報告、スペクトログラム画像、音符のリスト、イベントのタイムライン、文字起こし、変更前後の差分などです。音声の編集や合成もできるため、エージェントは音を作成または修正 → 測定 → 確認 → 変更を検証というループで作業できます。

すべてローカルで実行されます。GPU も API キーも不要です。主な依存関係は numpy、scipy、soundfile、matplotlib です。

同梱のデモ scripts/demo.py の実際の出力（JSON を省略）：

> audio_analyze voice_raw.wav          # speech recorded with mains hum and hiss
  levels: lufs_integrated -32.16, true_peak_dbtp -11.76, clipped_samples 0
  issues: [warning] Mains hum at 60 Hz (peaks at 60, 180 Hz). Fix: notch each with
                    {"op":"eq","hz":60,"db":-30,"q":30}, {"op":"eq","hz":180,"db":-30,"q":30};
                    for voice, highpass at ~80-100 Hz also removes the fundamental.
          [info]    Noise floor around -33.4 dBFS in the quietest parts; hiss or background noise may be audible.

> audio_events sfx.wav                 # a zap, a noise hit, another hit, a rising chirp
  0.09-0.36s | -4dB  | tonal | balanced          | glide G#6->B3 (-33st) | sharp attack
  0.59-0.69s | -16dB | noisy | very bright/harsh | sharp attack
  ...

> audio_melody melody.wav              # "Mary Had a Little Lamb", transcribed blind
  E4(0.23) D4(0.24) C4(0.23) D4(0.24) E4(0.25) E4(0.25) E4(0.5) D4(0.24) D4(0.26) D4(0.49) E4(0.25) G4(0.26) G4(0.47)

ツール

ツール	エージェントが得られる情報
audio_analyze	ピーク、トゥルーピーク、RMS、LUFS ラウドネス、クリッピング、DC オフセット、ラウドネスのスパークライン、無音とノイズフロア、ステレオ相関／幅／バランス、帯域エネルギー、明るさ、音色かノイズか、音名で示す最も強い周波数、ピッチ、オンセット、テンポ、エッジクリック、ループの継ぎ目の品質、さらに平易な言葉で推奨修正を示す issues リスト
audio_events	音声を個別の音に分割し、それぞれのタイミング、レベル、アタック、音色かノイズか、明るさ、ピッチまたはグライドを説明します
audio_view	PNG の波形および／またはスペクトログラムを表示します。ピッチのオーバーレイも指定できます。各列は時間全体をカバーするため、長いファイルでも短いクリック音を見落としません
audio_timeline	時間経過に伴うレベルと明るさを表示します。ファイルをストリーミングするため、どの長さの録音でも機能します
audio_melody	1 行の文字起こし：音符、タイミング、セント、簡潔なテキスト
audio_transcribe	ローカル Whisper による音声のテキスト化：単語ごとのタイミング、言語、話す速度、長い休止、不確かな単語（オプションの追加機能）
audio_compare	A/B の要約、指標の差分、帯域ごとの dB 変化、修正または新たに発生した問題、ヌルテスト（同一か、ゲイン変更のみか、軽微な変更があるか）
audio_process	新しいファイルに書き込む、順序指定可能な編集チェーン：ゲイン、ピーク／LUFS 正規化、トゥルーピークリミッター、コンプレッサー、ノイズ低減、RMS 正規化、トリミング、フェード、クロップ、パディング、ハイパス／ローパス、ピーキング EQ、シェルフ、DC 除去、極性、モノラル／ステレオ、リサンプリング、逆再生、シームレスループのクロスフェード、ミックス、連結
audio_batch_survey	フォルダーを監査して一貫性を確認します（ラウドネスの外れ値、サンプルレート／チャンネル／形式の混在、冒頭の無音のばらつき）。すぐに実行できる修正も返します
audio_batch_process	多数のファイルに 1 つの編集チェーンを適用し、出力フォルダーに書き込みます
audio_synthesize	宣言型シンセ：位相制御付き帯域制限オシレーター、ノイズカラー（ピンク／ブラウン、シームレスにループ）、スイープ、ADSR、ビブラート、トレモロ、フィルター、パン、音符シーケンス、正確なテスト信号（インパルス、DC、無音）
audio_info	ファイルのメタデータ、またはフォルダー内の音声ファイル一覧
audio_check_delivery	納品仕様に照らした合否判定（Apple Podcasts、Spotify、YouTube、EBU R 128、ATSC A/85、ACX オーディオブック、ゲームの効果音）。出典を明記し、ファイルに対してすでに試行した修正も提示します
audio_check_game_project	Godot 4 プロジェクトの音声を監査します：カテゴリごとのラウドネスの一貫性、ループ設定とクリック音の出る継ぎ目、欠陥、壊れた、または未使用の res:// 参照

WAV、FLAC、OGG/Vorbis、Opus、MP3、AIFF、CAF をネイティブに読み込みます（libsndfile 経由）。FFmpeg をインストールすると、M4A/AAC（スマートフォン、Zoom、ボイスメモ）、WMA、および動画ファイルの音声（MP4、MOV、WebM、MKV）も読み込めます。Windows では winget install Gyan.FFmpeg、macOS では brew install ffmpeg、Debian/Ubuntu では sudo apt install ffmpeg を実行するか、AUDIO_MCP_FFMPEG にバイナリを指定してください。各ファイルはセッションごとに 1 回だけデコードされます。編集したファイルは WAV/FLAC/OGG/AIFF/MP3 として書き込まれます。

納品チェック

audio_check_delivery は、ファイルがプラットフォームの仕様を満たしているか、満たしていない場合はどう修正するかを教えてくれます。各基準には、必要な条件、測定結果、合否が表示されます。推奨される修正は、ファイルに対してすでにシミュレーション済みの、順序付きの audio_process チェーンです（ゲイン調整の前にノイズ処理を行い、最後にトゥルーピークリミッターを適用します）。自動修正できない場合や、強い背景ノイズがあり人による判断が必要な場合は、ツールが明確に伝えます。仕様の数値には、公式ソースと確認日が記載されています。

ゲームプロジェクト（Godot 4）

audio_check_game_project(project_dir) は、Godot 4 プロジェクト内のすべての .wav/.ogg/.mp3 を監査します。フォルダー名とファイル名からカテゴリ（UI、効果音、音声、音楽、環境音）を推測するほか、独自のマッピングも使用できます。.import 設定を読み取り、ループしない音楽、永久にループする効果音、クリック音が発生するループのつなぎ目を検出します。各カテゴリ内でラウドネスを比較し（短い音は最も音量が大きい瞬間、音楽は統合 LUFS を使用）、外れ値と、直接実行できる修正方法を報告します。また、シーンとスクリプトをスキャンし、res:// の音声参照切れ、大小文字の誤り、未使用の参照を検出します。プロジェクトを変更することはありません。

インストール

pip install audio-mcp              # or: uv tool install audio-mcp
pip install "audio-mcp[speech]"    # adds audio_transcribe (faster-whisper; downloads a ~145 MB model on first use)

MCP クライアントへの接続

Claude Code

claude mcp add audio -- uvx audio-mcp
# or, if installed with pip:
claude mcp add audio -- audio-mcp

Claude Desktop、Cursor、その他のクライアント（JSON 設定）：

{
  "mcpServers": {
    "audio": { "command": "uvx", "args": ["audio-mcp"] }
  }
}

その後、「./sfx の効果音に問題がないか確認して」、「ポッドキャスト用に interview.wav をクリーンアップして」、*「短い UI 確認音を作成して、耳障りでないか確認して」*などと依頼できます。

ファイルアクセスの制限

デフォルトでは、サーバーはユーザーアカウントがアクセスできるすべてのファイルを読み書きできます。アクセス範囲を限定するには、AUDIO_MCP_ALLOWED_DIRS にディレクトリのリストを設定します（Windows では ;、それ以外では : で区切ります）。

{ "command": "uvx", "args": ["audio-mcp"], "env": { "AUDIO_MCP_ALLOWED_DIRS": "/home/me/audio" } }

パスは .. とシンボリックリンクを解決した後にチェックされます。その他の設定：AUDIO_MCP_MAX_SECONDS（1 回の呼び出しでメモリーに読み込む最大区間。デフォルトは 1800）、AUDIO_MCP_WHISPER_MODEL（デフォルトは base）、AUDIO_MCP_ROOT（相対パスの基準ディレクトリ）。

精度の検証方法

テストでは主に、正解が構成上あらかじめ分かっている合成信号を使用するため、「クラッシュしない」ことだけでなく、正しく動作することを検証します。

• ラウドネス： ストリーミング方式の BS.1770 メーターは、8〜96 kHz で pyloudnorm の exact-filter モードと 0.01 LU 以内で一致し、EBU 基準音（997 Hz、0 dBFS）を −3.01 LUFS として測定します。
• リミッター： +15 dBTP の入力は、セーフティクリップでサンプルに変更を加えることなく、正確に −1.0 dBTP で出力されます。
• ピッチとメロディー： サイン波、チャープ、合成メロディーを、繰り返し音を含めて音符単位で復元します。82 Hz〜1760 Hz の範囲で、ピッチの誤差は 1 セント以内です。
• テンポ、オンセット、イベント、無音、ステレオ位相、ハム、クリッピング、アライメントのオフセット： それぞれを構成済みの信号と照合して検証します。
• 契約テスト： すべてのツールを、すべてのコンテンツ種別（無音、DC、ノイズ、フルスケールの矩形波）、長さ（1 サンプル〜3 秒）、形式（16/24 ビット／浮動小数点 WAV、FLAC、Vorbis）、チャンネル数（1、2、6）、サンプルレート（8〜96 kHz）で実行します。各呼び出しは成功するか、内容が分かる AudioError を返して失敗しなければなりません。
• メモリー： 解析はチャンク単位で行います。48 kHz のステレオ音声ファイル（20 分）は、ピークメモリー使用量約 1.2 GB（うち音声データが 0.7 GB）で、約 19 秒で解析できます。

設計原則

• デフォルトでは破壊的な操作を行いません。 編集結果は <name>_processed.wav に書き出されます。上書きには overwrite=true が必要で、バッチ出力先に入力フォルダーを指定することはできません。
• エラーには次に行うことを示します。 不明な op が指定された場合は、パラメーターを含むすべての op を一覧表示します。デコードできないファイルの場合は、対応フォーマットと、その他のフォーマットを扱うための FFmpeg のインストール方法を示します。予期しないエラーは隠さず、バグとして報告します。
• 不確実性を正直に扱います。 和音の場合は確信を持てない誤った音程を報告せず polyphony_likely を設定し、確信度の低いテンポには低い確信度の注記を付けます。Whisper で不確かな単語は一覧表示し、0.4 秒未満のクリップでは LUFS を null にします。
• 出力は簡潔です。 数値の丸め、スパークライン、1 行のイベント要約により、エージェントのコンテキストに収まる小さな応答を維持します。

制限事項

• 音高、メロディー、イベントごとの音高は、一度に 1 音だけ鳴ることを前提としています。和音やミックス全体は文字起こしせず、フラグを付けます。
• ノイズ除去は、（ヒスノイズ、ハム音、ファンの音、室内の環境音などの）定常的なノイズに対するスペクトルゲートです。クリック音、音楽、その他の声は除去しません。sensitivity を上げすぎると小さな子音が鈍るため、音声の編集結果は audio_transcribe で確認してください。
• テンポは従来型の自己相関による推定です。複雑な音楽では、半分または倍のテンポとして誤って推定されることがあります。
• ツールは音を説明しますが、好み（「これは心地よいか？」）を判断するものではありません。

参照信号

audio-mcp-assets は、ある AI エージェントがこれらのツールだけを使って作成した、テストおよびキャリブレーション用音声（トーン、スイープ、校正済みノイズ、ラウドネス、ステレオおよび位相のテスト、インパルス、問題のあるファイル）のパブリックドメインパックです。すべてのファイルは、既知の正解データと照合し、このプロジェクトとは独立した方法を含めて、2 回検証されています。

コントリビューション

人間や AI エージェントからの改善提案を歓迎します。CONTRIBUTING.md を参照してください。AI コーディングエージェントは AGENTS.md もお読みください。機能追加の基準は、1 つのことを適切に行い、既知の正解データに対するテストがあることです。

ライセンス

MIT