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.
Audio Studio MCP は、Claude Code、Claude Desktop、Cursor など任意の MCP クライアントに、自分の Mac や Windows PC で動くサウンドスタジオを追加します。BGM や効果音を普通の言葉で頼むと、Stable Audio 3 がローカルで生成します。さらにループ化やラウドネス調整をして、ゲームエンジンや動画編集ソフト向けに書き出せます。クラウドサービスも API キーも不要で、生成にお金はかかりません。
実際のセッション(一部省略)。ループの長さを 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 では、同じシードなら公式の
sa3CLI とビット単位で同じ結果になります。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
インストーラーは次のことを行います:
- 必要なら
uvを導入します。 - 公式 Stable Audio 3 ランタイムを、動作確認済みのコミットで
vendor/に clone します。 .venv/を作成します。- 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 や効果音の生成、候補の聴き比べ、編集(バリエーション、一部の差し替え、延長)、ゲームや動画向けの書き出し、これまで作った音を一覧できるライブラリまで、ブラウザで操作できます。
.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〜2 文、約 45 語まで。 vocals、singer、lyrics など歌に関する語は避けます。
- 音楽: ジャンル+形容詞 → メイン楽器 → 補助的なレイヤー → ドラム/リズム → ムード。テンポは
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.
- 効果音: 音源、動作、素材、空間の 4 項目を埋めます。
source: glass bottle / action: shattering on impact, fragments scattering / material: thick green glass, sharp bright transient / space: concrete floor, close-up, dry
- 長さは内容に合わせる: 衝撃音 1〜3 秒、動作 3〜6 秒、環境音 6〜15 秒以上、ループ 6〜20 秒、フル楽曲 120〜300 秒(最大 380 秒)。
- 秒単位の構成指示(「15 秒でクライマックス」など)は確実には守られません。まず生成してから
inpaintやcontinueで調整します。 - 既定の
steps=8、cfg=1.0が公式設定です。プロンプトへの忠実度を上げたい場合やnegative_promptを効かせたい場合は、cfgを 3〜7 にします(約 2 倍遅くなります)。 - シードによって結果が大きく変わります。
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 が ♥ を込めて制作
Audio Studio が役に立ったら ⭐ で応援してください。更新の励みになり、他の人にも見つけてもらいやすくなります。ほかのプロジェクト:github.com/kanaworksai-hue
