Skip to content

Local AI BGM and sound effects for Claude Code and any MCP client. Stable Audio 3 on Apple Silicon (MLX) and Windows NVIDIA GPUs (PyTorch). No cloud, no API key.

29.5 KB
Raw Blame

Audio Studio MCP は、Claude Code、Claude Desktop、Cursor など任意の MCP クライアントに、自分の Mac や Windows PC で動くサウンドスタジオを追加します。BGM や効果音を普通の言葉で頼むと、Stable Audio 3 がローカルで生成します。さらにループ化やラウドネス調整をして、ゲームエンジンや動画編集ソフト向けに書き出せます。クラウドサービスも API キーも不要で、生成にお金はかかりません。

実際の Claude Code セッション:1 回の依頼で lo-fi BGM を 2 候補作り、Godot 用のシームレスループ OGG を書き出す
実際のセッション(一部省略)。ループの長さを 85 BPM のちょうど 11 小節に合わせ、繰り返してもリズムがずれないようにしています。

✨ 特長


生成
1 文から BGM、楽器ループ、効果音を生成。1 回で 1〜4 候補

編集
全体のスタイル変換、指定区間の再生成、曲の延長

仕上げ
シームレスループ、フェード、ラウドネス(LUFS)、48 kHz WAV / OGG / FLAC

ローカル
Apple Silicon(MLX)または NVIDIA GPU(PyTorch)で動作。何もアップロードしません
  • 再現できる: すべてのファイルに、プロンプト・シード・設定を記録した .json が付きます。
  • プロンプト作りも任せられる: サーバーが公式の Stable Audio 3 プロンプト形式をクライアントに伝えるので、「きしむドアの音」のような頼み方でも、モデルが理解できるプロンプトに書き換えられます。
  • 公式と同じ出力: Mac では、同じシードなら公式の sa3 CLI とビット単位で同じ結果になります。Windows では公式の Stable Audio 3 PyTorch API をそのまま呼び出します。

🎧 サンプル

すべてこのサーバーで M1 Mac 上で生成したもので、手作業での編集はしていません。サンプルページを開く →

サンプル プロンプト
Lo-fi カフェ
音楽 · 30 秒 · 85 BPM
Lo-fi hip-hop chill track with mellow electric piano, soft vinyl crackle, low-pass filtered drums…
壮大なオーケストラ
音楽 · 30 秒
Epic cinematic orchestral trailer music with thundering taiko drums, soaring French horns…
8bit アドベンチャー
音楽 · 20 秒 · 150 BPM
Upbeat 8-bit chiptune adventure theme with a bright square wave lead…
ガラスが割れる音
効果音 · 3 秒
source: glass bottle · action: shattering on impact · material: thick green glass · space: concrete floor
雨と雷
効果音 · 12 秒
source: heavy rain and distant thunder · space: outdoor forest at night, wide stereo
シンセウェーブの延長
編集 · 20 秒 → 40 秒
edit_audio continue:20 秒の曲を 40 秒まで延長

MP3 は docs/samples/ に、プロンプトとシードは samples.json にあります。

🧭 しくみ

flowchart LR
    U["あなた<br/>「カフェの BGM を作って」"] --> C["Claude Code · Desktop<br/>Cursor · 任意の MCP クライアント"]
    C -- "MCP" --> S["audio-studio-mcp<br/>生成 · 編集 · 仕上げ"]
    S --> M["Stable Audio 3<br/>Apple Silicon 上の MLX<br/>NVIDIA GPU 上の PyTorch"]
    M --> F["WAV / OGG / FLAC + .json<br/>ゲームや動画にそのまま"]

🚀 クイックスタート

macOS(Apple Silicon)

動作要件:

  • Apple Silicon Mac(M1 以降)、メモリ 16 GB 推奨
  • モデル用に約 6 GB のディスク容量
  • git と ffmpeg(brew install ffmpeg)
git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
cd audio-studio-mcp
./install.sh

インストーラーは次のことを行います:

  1. 必要なら uv を導入します。
  2. 公式 Stable Audio 3 ランタイムを、動作確認済みのコミットで vendor/ に clone します。
  3. .venv/ を作成します。
  4. Hugging Face から medium モデル(1.4B、約 5.9 GB)をダウンロードします。

最後に、登録用のコマンドがそのまま表示されます:

claude mcp add --scope user audio-studio -- /path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp

Windows(NVIDIA GPU)

動作要件:

  • 64 ビット版 Windows 10 / 11、NVIDIA GPU(VRAM 8 GB 以上)と新しめのドライバー。RTX 3060 12 GB で動作確認済み
  • モデルと PyTorch 用に約 14 GB のディスク容量
  • git(winget install Git.Git)と ffmpeg(winget install Gyan.FFmpeg)
  • 無料の Hugging Face アカウント。PyTorch 版の重みは利用規約への同意が必要です。stabilityai/stable-audio-3-medium を開き、一度ライセンスに同意してください
git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
cd audio-studio-mcp
powershell -ExecutionPolicy Bypass -File install.ps1

インストーラーの流れは macOS と同じですが、CUDA 版の PyTorch を導入し、medium モデルの公式 PyTorch 版の重み(約 10.4 GB)をダウンロードします。Hugging Face にまだログインしていない場合は、read 権限のアクセストークンを貼り付けるよう求められます(ここで作成)。コンソールのない環境(AI エージェントが実行した場合など)では入力を求めず、ログイン手順を表示して止まるので、ログインしてからもう一度実行してください。最後に登録用のコマンドが表示されます:

claude mcp add --scope user audio-studio -- "C:\path\to\audio-studio-mcp\.venv\Scripts\audio-studio-mcp.exe"

Flash Attention は不要です。入っていない場合、ランタイムは PyTorch 標準のアテンションを使います。

Claude Desktop、Cursor などのクライアント

claude_desktop_config.json、.cursor/mcp.json、またはクライアントの MCP 設定に追加します:

{
  "mcpServers": {
    "audio-studio": {
      "command": "/path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp"
    }
  }
}

Windows では command を C:\\path\\to\\audio-studio-mcp\\.venv\\Scripts\\audio-studio-mcp.exe にします(JSON ではバックスラッシュを 2 つ重ねます)。

インストーラーのオプション
macOS Windows 内容
--model all -Model all 小型で高速な sm-music と sm-sfx モデルも取得(macOS は +2.6 GB、Windows は +7 GB)
--skip-weights -SkipWeights 今はダウンロードせず、最初の生成時にダウンロード
-y -Yes 確認なしで uv を導入

macOS ではダウンロードにログインは不要で、hf auth login でログインすると Hugging Face の速度制限が緩くなります。Windows の PyTorch 版の重みは、ダウンロードするモデルごとにページでライセンスに同意し(medium、small-music、small-sfx)、ログインしておく必要があります。

[!TIP] エージェントにインストールを任せる。 Claude Code に次の文を貼り付けてください: 「https://github.com/kanaworksai-hue/audio-studio-mcp の README(AI エージェント向けの注意も含めて)に従ってインストールし、MCP サーバーとして登録して。」

AI エージェント向けの注意(Windows のみ。macOS はログイン不要): 重みは利用規約への同意が必要で、ユーザー本人の Hugging Face ログインが要ります。

  • 重みをダウンロードする前に hf auth whoami でログイン状態を確認してください(インストーラーを一度実行した後は .venv\Scripts\hf.exe auth whoami)。install.ps1 も確認し、未ログインなら ACTION NEEDED を表示して止まります。
  • 未ログイン、またはダウンロードが 401/403 で失敗した(ライセンス未同意、または別のアカウントで同意した)場合は作業を止め、インストーラーが表示した手順をユーザーに伝えてください:無料アカウントを作る、各モデルのページでライセンスに同意する、ユーザー自身のターミナルで hf auth login を実行する。終わったと言われてから、インストーラーを再実行します。
  • トークンをチャットに貼るようユーザーに頼まないでください。-SkipWeights で回避するのも不可です(後で生成するときに同じエラーで失敗します)。

あとは普通に頼むだけです:

  • 「カフェのシーン用に 85 BPM、60 秒の lo-fi BGM ループを作って。候補は 3 つ。」
  • 「石造りの廊下で重い木の扉がバタンと閉まる効果音を作って、Godot 用に OGG で書き出して。」
  • 「この曲を 90 秒まで延ばして、−16 LUFS に正規化して。」

🧰 ツール

ツール 内容
generate_audio テキストから BGM、楽器ループ/ステム、効果音を生成。1 回で 1〜4 候補、bpm と効果音用の構造化フィールドに対応
edit_audio variation(全体のスタイル変換)、inpaint(指定区間を再生成)、continue(延長)。1〜4 候補
process_audio トリミング → 無音カット → モノラル化 → リサンプリング/ラウドネス → シームレスループ → フェード → ピーク正規化または上限 → WAV / OGG / FLAC。元ファイルは変更しません
unload_models モデルが使っているメモリをすぐ解放
パラメータの補足
  • audio_type:music / instrument / sfx / raw。モデルの学習時と同じプレフィックス(TrackType: Music, VocalType: Instrumental, など)をサーバーが自動で付けます。SFX プレフィックスがないと、効果音が音楽になりがちです。
  • variations:1〜4 候補。シードは seed, seed+1, … です。seed を省略するか -1 にするとランダムになります。
  • sound_source / sound_action / sound_material / sound_space:効果音の音源、鳴り方と変化、素材・音色、空間を記述します。
  • peak_ceiling_db(既定 −1):安全上限です。ピークが超えた場合だけ全体を下げ、小さい音を持ち上げることはありません。正規化は process_audio で行います。
  • process_audio の正規化:効果音には peak がよく使われます。loudness は目標 LUFS に合わせます。目安は配信・動画 −14、ゲーム BGM −16、放送 −23 です。

生成ファイルは 44.1 kHz 24-bit ステレオ WAV で、このフォルダの outputs/ に保存され、それぞれ隣に <ファイル名>.json が付きます。後処理したファイルには、元の生成情報が source として残ります。

🌐 Web UI

チャットよりクリックで操作したい場合は、同じサーバーに付属するローカルの Web ページが使えます。BGM や効果音の生成、候補の聴き比べ、編集(バリエーション、一部の差し替え、延長)、ゲームや動画向けの書き出し、これまで作った音を一覧できるライブラリまで、ブラウザで操作できます。

Web UI の生成ページ:lo-fi 曲の 2 バージョンの聴き比べと、足音の効果音

Web UI の編集ページ:波形の選択範囲を差し替え、元の音と新しい 2 バージョンを聴き比べ

.venv/bin/audio-studio-mcp --web 8765

ブラウザで http://127.0.0.1:8765/ が開きます。ブラウザを開かずに起動するには --no-browser、起動時にモデルを読み込むには --preload を付けます。止めるときは Ctrl+C です。Windows では .venv\Scripts\audio-studio-mcp.exe --web 8765 で起動します。

同じポートの /mcp で MCP も提供されるので、ページと MCP クライアントで 1 つのプロセスと読み込み済みのモデルを共有できます。一度登録すれば両方を同時に使えます。ページからのリクエストとエージェントからのリクエストは 1 つのキューで順番に処理されます。

claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp
  • ファイルは出力フォルダ(outputs/、または AUDIO_STUDIO_OUTPUT_DIR)に書き出されます。ライブラリにはこのフォルダの中身が表示され、編集もこのフォルダ内のファイルが対象です。
  • 表示言語は英語・日本語・中国語で、ブラウザの言語に合わせて切り替わります。設定から変更することもできます。

[!WARNING] Web UI は自分のパソコンだけで使うためのものです。待ち受けは 127.0.0.1 のみで、ログイン機能はありません。ポート転送、リバースプロキシ、トンネルなどで他のマシンから開けるようにしないでください。開ける人は誰でも GPU を使い、出力フォルダにファイルを書き込めてしまいます。

⚙️ 設定

環境変数
環境変数 既定値 説明
AUDIO_STUDIO_OUTPUT_DIR <repo>/outputs 音声の出力先
AUDIO_STUDIO_IDLE_UNLOAD_MIN 10 何分使われなかったらモデルを解放するか(0 = 解放しない)
AUDIO_STUDIO_SA3_MODEL medium medium(最高品質、最長 380 秒)、sm-music または sm-sfx(小型・高速、最長 120 秒)
AUDIO_STUDIO_MLX_CACHE_GB 1 macOS:MLX のバッファキャッシュ上限。設定しないと、長い曲の生成後に約 6 GB 余分に残ることがあります
AUDIO_STUDIO_DEVICE CUDA があれば cuda Windows/Linux:PyTorch のデバイス。cuda、cuda:1、cpu など
AUDIO_STUDIO_SA3_DIR <repo>/vendor/stable-audio-3 別の stable-audio-3 チェックアウトを使う
AUDIO_STUDIO_BACKEND auto auto、sa3-mlx(Apple Silicon)、sa3-torch(PyTorch、NVIDIA)
AUDIO_STUDIO_FFMPEG PATH 上の ffmpeg ffmpeg のパス

claude mcp add ... -e 名前=値 で渡すか、クライアント設定の env に書きます。

複数のセッションで 1 つのサーバーを共有する

通常はクライアントのセッションごとにサーバープロセスが起動します。モデルは最初の呼び出しで読み込まれ、アイドル時間が過ぎると解放されます。すべてのセッションで常駐プロセスを 1 つだけ使いたい場合は、ローカル HTTP サーバーとして起動します。待ち受けは 127.0.0.1 のみです。

.venv/bin/audio-studio-mcp --http 8765 --preload
claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp

Windows では .venv\Scripts\audio-studio-mcp.exe --http 8765 --preload で起動します。

--web 8765 でも同じように動き、同じポートで Web UI も使えます。

⚡ パフォーマンス

M1 Mac 16 GB、medium モデル:

内容 所要時間
コールドスタート、3 秒の効果音 × 2 約 13 秒
ウォーム、20 秒の音楽 約 10 秒(実時間の 2 倍速)
35 秒まで延長(エンコーダーの初回読み込みを含む) 約 27 秒
sm-music でウォーム、15 秒の音楽 約 1 秒

Windows + RTX 3060 12 GB、medium モデル:

内容 所要時間
コールドスタート、3 秒の効果音 × 2(約 20 秒のモデル読み込みを含む) 約 25 秒
ウォーム、20 秒の音楽 約 1.3 秒
ウォーム、30 秒まで延長 約 2.2 秒
ウォーム、380 秒の音楽(最大) 約 15 秒
sm-music でウォーム、15 秒の音楽 約 0.7 秒

Mac ではモデルを読み込んでいる間、約 5〜7 GB のメモリを使います。RTX 3060 では medium モデルの VRAM 使用量のピークが約 5.3 GB でした。アイドル時間の経過、または unload_models で解放されます。

📝 プロンプトのコツ

公式 Stable Audio 3 プロンプトガイドより
  1. 英語で 1〜2 文、約 45 語まで。 vocals、singer、lyrics など歌に関する語は避けます。
  2. 音楽: ジャンル+形容詞 → メイン楽器 → 補助的なレイヤー → ドラム/リズム → ムード。テンポは bpm で指定します。

    Lo-fi hip-hop chill track with mellow electric piano, soft vinyl crackle, low-pass filtered drums and soft plucked bass for a relaxed, dreamy vibe.

  3. 効果音: 音源、動作、素材、空間の 4 項目を埋めます。

    source: glass bottle / action: shattering on impact, fragments scattering / material: thick green glass, sharp bright transient / space: concrete floor, close-up, dry

  4. 長さは内容に合わせる: 衝撃音 1〜3 秒、動作 3〜6 秒、環境音 6〜15 秒以上、ループ 6〜20 秒、フル楽曲 120〜300 秒(最大 380 秒)。
  5. 秒単位の構成指示(「15 秒でクライマックス」など)は確実には守られません。まず生成してから inpaint や continue で調整します。
  6. 既定の steps=8、cfg=1.0 が公式設定です。プロンプトへの忠実度を上げたい場合や negative_prompt を効かせたい場合は、cfg を 3〜7 にします(約 2 倍遅くなります)。
  7. シードによって結果が大きく変わります。variations を 2〜4 にして、いちばん良いものを選びましょう。

ガイド全文は、サーバーの instructions としてクライアントにも送られます。

❓ FAQ

Windows、Linux、Intel Mac で動きますか?

Windows: NVIDIA GPU があれば動きます。クイックスタートを参照してください。

Linux: NVIDIA GPU なら同じ PyTorch バックエンドで動くはずですが、未テストで、インストーラーもまだありません。上流のランタイムを vendor/stable-audio-3 に(install.sh で固定しているコミットで)clone し、uv sync --extra cuda と hf auth login を実行してください。

Intel Mac と AMD GPU には対応していません。

Apple Silicon の Mac なのに「Intel Macs are not supported」と出ます

Rosetta で動く x86_64 版の Python(たとえば /usr/local にある Intel 版 Homebrew の Python)で環境が作られ、MLX がインストールされなかったのが原因です。現在の install.sh は uv に arm64 の Python を指定し、そうした .venv は作り直すので、./install.sh を実行し直せば直ります。UV_PYTHON を自分で設定している場合は arm64 版を指定してください:UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh

歌入りの曲は作れますか?

作れません。Stable Audio 3 が生成するのはインストと効果音だけで、聞き取れる歌詞は歌えません。

生成した音声は商用利用できますか?

このプロジェクトのコードは MIT ライセンスです。モデルの重みには Stability AI Community License が適用され、モデルと生成物の利用条件はこのライセンスで決まります。商用利用の前に必ず確認してください。執筆時点では、年間収益 100 万米ドル未満の個人・組織による商用利用が認められています。

メモリ 8 GB の Mac でも使えますか?

テストしていません。medium モデルは読み込まれている間、約 5〜7 GB 使うため、16 GB を推奨します。小型の sm-music / sm-sfx モデルはもっと軽量です。

ループの継ぎ目でプチッと音がします。

ループには WAV か OGG を使ってください。MP3 は先頭と末尾に無音のパディングが入るので、シームレスにループできません。loop_crossfade_ms を長くするか、小節の区切りでカットするようモデルに頼む方法もあります。

🗺️ ロードマップ

  • Apple Silicon バックエンド(Stable Audio 3、MLX)
  • NVIDIA GPU 向けの Windows バックエンド(Stable Audio 3、PyTorch)
  • ローカル Web UI(--web)
  • LoRA 対応(上流のランタイムは対応済み)

Issue やプルリクエストを歓迎します。

⭐ Star で応援する

Audio Studio で作った音を実際に使ってもらえたなら、リポジトリページ上部の ⭐ Star を押してもらえるとうれしいです。無料で 1 秒で終わりますが、効果は見た目以上です:

  • もっと多くの人に届きます。 Star が増えるほど GitHub 上で見つけてもらいやすくなり、ゲームや動画を作る人に広がります。
  • 更新の励みになります。 Star は「使っている人がいる」という何よりのサインです。次のアップデート(LoRA 対応など)を進める力になります。

ほかの応援方法:不具合やアイデアは Issue へどうぞ。作った音を X でシェアして @KanaWorks_AI を付けてもらえるのも大歓迎です。

🛠️ 開発

uv run pytest                              # オフラインテスト(モデル不要)
.venv/bin/python scripts/smoke_test.py     # 実モデルでのエンドツーエンドテスト(M1 で約 30 秒)

Windows では .venv\Scripts\python scripts\smoke_test.py(RTX 3060 で約 45 秒、モデル読み込みを含む)。

src/audio_studio_mcp/
  server.py            MCP ツール(バックエンド非依存)
  prompts.py           プロンプトの組み立てと、クライアントに送る説明
  post.py              後処理と書き出し
  backends/base.py     バックエンドのインターフェース
  backends/sa3_mlx.py  Apple Silicon 上の Stable Audio 3(MLX)
  backends/sa3_torch.py  NVIDIA GPU 上の Stable Audio 3(PyTorch)
  web.py               Web UI のサーバー(--web)と JSON API
  static/              Web UI(HTML/JS/CSS、ビルド不要)

新しいプラットフォームは、backends/ にバックエンドとして追加します。

📄 ライセンスとクレジット

  • このプロジェクト: MIT
  • Stable Audio 3 ランタイム: インストール時に vendor/ へダウンロードされます。© Stability AI、MIT ライセンスです。
  • モデルの重み: Stability AI Community License が適用されます。重みは Hugging Face からダウンロードされ(macOS:stable-audio-3-optimized、Windows:stable-audio-3-medium と小型モデル)、本プロジェクトでは配布していません。
  • ブランド: KanaWorks_AI の名称、ロゴ、Kana のキャラクターの権利は東京AI映像合同会社に帰属し、MIT ライセンスの対象外です。詳しくは docs/brand を参照してください。
  • フォント: Web UI には IBM Plex Sans(© IBM Corp.、SIL Open Font License 1.1)を同梱しています(OFL.txt)。Web UI の Kana の画像(static/brand)には上記「ブランド」の項が適用されます。
  • 使用している技術: Stable Audio 3、MLX、PyTorch、Model Context Protocol

本プロジェクトは独立したプロジェクトであり、Stability AI、Apple、NVIDIA、Anthropic とは関係がなく、その承認も受けていません。


手を振る KanaWorks_AI のマスコット Kana

KanaWorks_AI が ♥ を込めて制作

Audio Studio が役に立ったら ⭐ で応援してください。更新の励みになり、他の人にも見つけてもらいやすくなります。ほかのプロジェクト:github.com/kanaworksai-hue