audio-studio-mcp 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. audio_studio_mcp-1.1.0/.gitignore +30 -0
  2. audio_studio_mcp-1.1.0/.python-version +1 -0
  3. audio_studio_mcp-1.1.0/LICENSE +21 -0
  4. audio_studio_mcp-1.1.0/PKG-INFO +539 -0
  5. audio_studio_mcp-1.1.0/README.ja.md +493 -0
  6. audio_studio_mcp-1.1.0/README.md +486 -0
  7. audio_studio_mcp-1.1.0/README.zh-CN.md +493 -0
  8. audio_studio_mcp-1.1.0/install.ps1 +240 -0
  9. audio_studio_mcp-1.1.0/install.sh +172 -0
  10. audio_studio_mcp-1.1.0/pyproject.toml +137 -0
  11. audio_studio_mcp-1.1.0/scripts/download_weights.py +44 -0
  12. audio_studio_mcp-1.1.0/scripts/smoke_test.py +107 -0
  13. audio_studio_mcp-1.1.0/server.json +59 -0
  14. audio_studio_mcp-1.1.0/src/audio_studio_mcp/__init__.py +3 -0
  15. audio_studio_mcp-1.1.0/src/audio_studio_mcp/__main__.py +3 -0
  16. audio_studio_mcp-1.1.0/src/audio_studio_mcp/backends/__init__.py +62 -0
  17. audio_studio_mcp-1.1.0/src/audio_studio_mcp/backends/base.py +122 -0
  18. audio_studio_mcp-1.1.0/src/audio_studio_mcp/backends/sa3_mlx.py +152 -0
  19. audio_studio_mcp-1.1.0/src/audio_studio_mcp/backends/sa3_torch.py +151 -0
  20. audio_studio_mcp-1.1.0/src/audio_studio_mcp/firstrun.py +191 -0
  21. audio_studio_mcp-1.1.0/src/audio_studio_mcp/post.py +208 -0
  22. audio_studio_mcp-1.1.0/src/audio_studio_mcp/prompts.py +92 -0
  23. audio_studio_mcp-1.1.0/src/audio_studio_mcp/runtime.py +219 -0
  24. audio_studio_mcp-1.1.0/src/audio_studio_mcp/server.py +523 -0
  25. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/app.css +501 -0
  26. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/app.js +902 -0
  27. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/brand/README.md +7 -0
  28. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/brand/favicon.png +0 -0
  29. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/brand/kana.png +0 -0
  30. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/editor.js +771 -0
  31. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/fonts/OFL.txt +93 -0
  32. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/fonts/ibm-plex-sans-latin-ext.woff2 +0 -0
  33. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/fonts/ibm-plex-sans-latin.woff2 +0 -0
  34. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/i18n.js +447 -0
  35. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/index.html +408 -0
  36. audio_studio_mcp-1.1.0/src/audio_studio_mcp/static/wave.js +199 -0
  37. audio_studio_mcp-1.1.0/src/audio_studio_mcp/web.py +657 -0
  38. audio_studio_mcp-1.1.0/src/audio_studio_mcp/weights.py +190 -0
  39. audio_studio_mcp-1.1.0/tests/conftest.py +66 -0
  40. audio_studio_mcp-1.1.0/tests/fake_web_server.py +32 -0
  41. audio_studio_mcp-1.1.0/tests/test_backends.py +85 -0
  42. audio_studio_mcp-1.1.0/tests/test_post.py +109 -0
  43. audio_studio_mcp-1.1.0/tests/test_prompts.py +44 -0
  44. audio_studio_mcp-1.1.0/tests/test_runtime.py +348 -0
  45. audio_studio_mcp-1.1.0/tests/test_sa3_mlx.py +95 -0
  46. audio_studio_mcp-1.1.0/tests/test_sa3_torch.py +152 -0
  47. audio_studio_mcp-1.1.0/tests/test_server.py +281 -0
  48. audio_studio_mcp-1.1.0/tests/test_stdio.py +43 -0
  49. audio_studio_mcp-1.1.0/tests/test_web.py +636 -0
  50. audio_studio_mcp-1.1.0/tests/test_webui_browser.py +621 -0
  51. audio_studio_mcp-1.1.0/uv.lock +2759 -0
@@ -0,0 +1,30 @@
1
+ # Python
2
+ __pycache__/
3
+ *.py[cod]
4
+ *.egg-info/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ .pytest_cache/
9
+ .ruff_cache/
10
+
11
+ # Upstream runtime and weights (fetched by install.sh)
12
+ vendor/
13
+
14
+ # Generated audio
15
+ outputs/
16
+ *.wav
17
+ *.ogg
18
+ *.flac
19
+ *.mp3
20
+
21
+ # Local config / tooling
22
+ .env
23
+ .env.*
24
+ .claude/
25
+ .idea/
26
+ .vscode/
27
+ .DS_Store
28
+
29
+ # Showcase samples for the GitHub Pages demo
30
+ !docs/samples/*.mp3
@@ -0,0 +1 @@
1
+ 3.11
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 東京AI映像合同会社
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,539 @@
1
+ Metadata-Version: 2.5
2
+ Name: audio-studio-mcp
3
+ Version: 1.1.0
4
+ Summary: Local AI BGM and sound-effect generation (Stable Audio 3) as an MCP server
5
+ Project-URL: Homepage, https://github.com/kanaworksai-hue/audio-studio-mcp
6
+ Project-URL: Issues, https://github.com/kanaworksai-hue/audio-studio-mcp/issues
7
+ Author: 東京AI映像合同会社
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ License-File: src/audio_studio_mcp/static/brand/README.md
11
+ License-File: src/audio_studio_mcp/static/fonts/OFL.txt
12
+ Keywords: audio-generation,bgm,cuda,mcp,mlx,sound-effects,stable-audio
13
+ Classifier: Operating System :: MacOS
14
+ Classifier: Operating System :: Microsoft :: Windows
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Topic :: Multimedia :: Sound/Audio
17
+ Requires-Python: >=3.10
18
+ Requires-Dist: cryptography<49; sys_platform == 'darwin' and platform_machine == 'x86_64'
19
+ Requires-Dist: editables>=0.5
20
+ Requires-Dist: einops-exts>=0.0.4; sys_platform == 'win32'
21
+ Requires-Dist: einops>=0.8.2; sys_platform == 'win32'
22
+ Requires-Dist: huggingface-hub>=0.20; sys_platform == 'darwin' and platform_machine == 'arm64'
23
+ Requires-Dist: huggingface-hub>=1.7.1; sys_platform == 'win32'
24
+ Requires-Dist: mcp<3,>=2.3
25
+ Requires-Dist: mlx>=0.30; sys_platform == 'darwin' and platform_machine == 'arm64'
26
+ Requires-Dist: numpy>=1.24
27
+ Requires-Dist: packaging>=24; sys_platform == 'win32'
28
+ Requires-Dist: pillow>=10.0; sys_platform == 'darwin' and platform_machine == 'arm64'
29
+ Requires-Dist: pydantic>=2
30
+ Requires-Dist: safetensors>=0.7.0; sys_platform == 'win32'
31
+ Requires-Dist: sentencepiece>=0.2; sys_platform == 'darwin' and platform_machine == 'arm64'
32
+ Requires-Dist: soundfile>=0.12
33
+ Requires-Dist: torch==2.7.1; sys_platform == 'win32'
34
+ Requires-Dist: torchaudio==2.7.1; sys_platform == 'win32'
35
+ Requires-Dist: tqdm>=4.67; sys_platform == 'win32'
36
+ Requires-Dist: transformers>=5.8.0; sys_platform == 'win32'
37
+ Provides-Extra: cuda
38
+ Requires-Dist: einops-exts>=0.0.4; (sys_platform != 'darwin') and extra == 'cuda'
39
+ Requires-Dist: einops>=0.8.2; (sys_platform != 'darwin') and extra == 'cuda'
40
+ Requires-Dist: huggingface-hub>=1.7.1; (sys_platform != 'darwin') and extra == 'cuda'
41
+ Requires-Dist: packaging>=24; (sys_platform != 'darwin') and extra == 'cuda'
42
+ Requires-Dist: safetensors>=0.7.0; (sys_platform != 'darwin') and extra == 'cuda'
43
+ Requires-Dist: torch==2.7.1; (sys_platform != 'darwin') and extra == 'cuda'
44
+ Requires-Dist: torchaudio==2.7.1; (sys_platform != 'darwin') and extra == 'cuda'
45
+ Requires-Dist: tqdm>=4.67; (sys_platform != 'darwin') and extra == 'cuda'
46
+ Requires-Dist: transformers>=5.8.0; (sys_platform != 'darwin') and extra == 'cuda'
47
+ Provides-Extra: mlx
48
+ Requires-Dist: huggingface-hub>=0.20; extra == 'mlx'
49
+ Requires-Dist: mlx>=0.30; (sys_platform == 'darwin' and platform_machine == 'arm64') and extra == 'mlx'
50
+ Requires-Dist: pillow>=10.0; extra == 'mlx'
51
+ Requires-Dist: sentencepiece>=0.2; extra == 'mlx'
52
+ Description-Content-Type: text/markdown
53
+
54
+ <div align="center">
55
+
56
+ <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/banner-en.jpg" alt="Audio Studio MCP: local AI music and sound effects for Claude Code and any MCP client" width="820">
57
+
58
+ <p>
59
+ <a href="https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-6b4dff?style=flat-square"></a>
60
+ <img alt="macOS Apple Silicon" src="https://img.shields.io/badge/macOS-Apple_Silicon-111?style=flat-square&logo=apple">
61
+ <img alt="Windows NVIDIA GPU" src="https://img.shields.io/badge/Windows-NVIDIA_GPU-76b900?style=flat-square&logo=nvidia&logoColor=white">
62
+ <a href="https://modelcontextprotocol.io"><img alt="MCP server" src="https://img.shields.io/badge/MCP-server-19b8d6?style=flat-square"></a>
63
+ <img alt="Python 3.10 to 3.13" src="https://img.shields.io/badge/python-3.10–3.13-3776ab?style=flat-square&logo=python&logoColor=white">
64
+ <a href="https://github.com/kanaworksai-hue/audio-studio-mcp/actions/workflows/tests.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/kanaworksai-hue/audio-studio-mcp/tests.yml?style=flat-square&label=tests"></a>
65
+ <a href="https://github.com/kanaworksai-hue/audio-studio-mcp/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/kanaworksai-hue/audio-studio-mcp?style=flat-square&logo=github&label=stars&color=f5c518"></a>
66
+ </p>
67
+
68
+ <p><a href="https://github.com/kanaworksai-hue"><img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/brand/kanaworks-mark.png" height="22" alt="" align="absmiddle"></a>&nbsp;<a href="https://github.com/kanaworksai-hue"><b>A KanaWorks_AI project</b></a></p>
69
+
70
+ **English** | [简体中文](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/README.zh-CN.md) | [日本語](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/README.ja.md)
71
+
72
+ <!-- mcp-name: io.github.kanaworksai-hue/audio-studio-mcp -->
73
+
74
+ [🎧 Listen to samples](https://kanaworksai-hue.github.io/audio-studio-mcp/) · [Quick start](#-quick-start) · [Tools](#-tools) · [Web UI](#-web-ui) · [FAQ](#-faq) · [⭐ Star](#-like-it-star-it)
75
+
76
+ </div>
77
+
78
+ **Audio Studio MCP** gives Claude Code, Claude Desktop, Cursor and any other [MCP](https://modelcontextprotocol.io) client a sound studio that runs on your own Mac or Windows PC. Ask for background music or a sound effect in plain language; the model generates it locally with [Stable Audio 3](https://github.com/Stability-AI/stable-audio-3). Then it can loop it, normalize the loudness and export it for your game engine or video editor. There is no cloud service and no API key, and generating doesn't cost anything.
79
+
80
+ <p align="center">
81
+ <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/demo-en.png" alt="A real Claude Code session: one request produces two lo-fi BGM candidates and a seamless OGG loop for Godot" width="820">
82
+ <br><sub>A real session, shortened. Claude picked a loop length of exactly 11 bars so the beat stays in time when it repeats.</sub>
83
+ </p>
84
+
85
+ ## ✨ Highlights
86
+
87
+ <table>
88
+ <tr>
89
+ <td align="center" width="25%"><img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/icon-generate.png" width="72" alt=""><br><b>Generate</b><br><sub>BGM, instrument loops and sound effects from one sentence, 1–4 candidates per call</sub></td>
90
+ <td align="center" width="25%"><img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/icon-edit.png" width="72" alt=""><br><b>Edit</b><br><sub>Re-style a whole clip, regenerate a time range, or extend a track</sub></td>
91
+ <td align="center" width="25%"><img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/icon-process.png" width="72" alt=""><br><b>Finish</b><br><sub>Seamless loops, fades, loudness (LUFS), 48 kHz WAV / OGG / FLAC</sub></td>
92
+ <td align="center" width="25%"><img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/icon-local.png" width="72" alt=""><br><b>Local</b><br><sub>Runs on Apple Silicon (MLX) or an NVIDIA GPU (PyTorch). Nothing is uploaded</sub></td>
93
+ </tr>
94
+ </table>
95
+
96
+ - **Reproducible:** every file gets a `.json` sidecar with its prompt, seed and settings.
97
+ - **Prompting built in:** the server teaches the client the official Stable Audio 3 prompt format, so a request like "make it sound like a creaky door" becomes a prompt the model understands.
98
+ - **Same output as upstream:** on a Mac, results for the same seed are bit-for-bit identical to the official `sa3` CLI. On Windows it calls the official Stable Audio 3 PyTorch API.
99
+
100
+ ## 🎧 Hear it
101
+
102
+ All of these were generated by this server on an M1 Mac and were not edited by hand. **[Open the sample page →](https://kanaworksai-hue.github.io/audio-studio-mcp/)**
103
+
104
+ | | Sample | Prompt |
105
+ |---|---|---|
106
+ | <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/samples/lofi_cafe.svg" width="200" alt=""> | [**Lo-fi cafe**](https://kanaworksai-hue.github.io/audio-studio-mcp/#lofi_cafe)<br><sub>music · 30 s · 85 BPM</sub> | Lo-fi hip-hop chill track with mellow electric piano, soft vinyl crackle, low-pass filtered drums… |
107
+ | <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/samples/epic_orchestral.svg" width="200" alt=""> | [**Epic orchestral**](https://kanaworksai-hue.github.io/audio-studio-mcp/#epic_orchestral)<br><sub>music · 30 s</sub> | Epic cinematic orchestral trailer music with thundering taiko drums, soaring French horns… |
108
+ | <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/samples/chiptune_adventure.svg" width="200" alt=""> | [**Chiptune adventure**](https://kanaworksai-hue.github.io/audio-studio-mcp/#chiptune_adventure)<br><sub>music · 20 s · 150 BPM</sub> | Upbeat 8-bit chiptune adventure theme with a bright square wave lead… |
109
+ | <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/samples/glass_shatter.svg" width="200" alt=""> | [**Glass shatter**](https://kanaworksai-hue.github.io/audio-studio-mcp/#glass_shatter)<br><sub>sfx · 3 s</sub> | source: glass bottle · action: shattering on impact · material: thick green glass · space: concrete floor |
110
+ | <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/samples/rain_thunder.svg" width="200" alt=""> | [**Rain & thunder**](https://kanaworksai-hue.github.io/audio-studio-mcp/#rain_thunder)<br><sub>sfx · 12 s</sub> | source: heavy rain and distant thunder · space: outdoor forest at night, wide stereo |
111
+ | <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/samples/synthwave_drive_extended.svg" width="200" alt=""> | [**Synthwave, extended**](https://kanaworksai-hue.github.io/audio-studio-mcp/#synthwave_drive_extended)<br><sub>edit · 20 s → 40 s</sub> | `edit_audio` continue: a 20-second track extended to 40 seconds |
112
+
113
+ MP3s are in [`docs/samples/`](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/docs/samples), with prompts and seeds in [`samples.json`](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/docs/samples/samples.json).
114
+
115
+ ## 🧭 How it works
116
+
117
+ ```mermaid
118
+ flowchart LR
119
+ U["You<br/>“make a cozy cafe BGM”"] --> C["Claude Code · Desktop<br/>Cursor · any MCP client"]
120
+ C -- "MCP" --> S["audio-studio-mcp<br/>generate · edit · process"]
121
+ S --> M["Stable Audio 3<br/>MLX on Apple Silicon<br/>PyTorch on NVIDIA GPUs"]
122
+ M --> F["WAV / OGG / FLAC + .json<br/>ready for game & video"]
123
+ ```
124
+
125
+ ## 🚀 Quick start
126
+
127
+ You need [uv](https://docs.astral.sh/uv/) 0.9.20 or newer and [ffmpeg](https://ffmpeg.org). There is nothing to clone: `uvx` downloads and runs the published package.
128
+
129
+ | | macOS | Windows |
130
+ |---|---|---|
131
+ | **Hardware** | Apple Silicon (M1 or later), 16 GB RAM recommended | NVIDIA GPU with 8 GB of VRAM or more and a current driver. Tested on an RTX 3060 12 GB |
132
+ | **Disk** | About 8 GB (model ~6.9 GB) | About 14 GB (model ~10.4 GB, PyTorch) |
133
+ | **uv and ffmpeg** | `brew install uv ffmpeg` | `winget install astral-sh.uv` and `winget install Gyan.FFmpeg` |
134
+ | **Model license** | Nothing to do | Needs a free [Hugging Face](https://huggingface.co) account: open [stabilityai/stable-audio-3-medium](https://huggingface.co/stabilityai/stable-audio-3-medium) and accept the license once |
135
+
136
+ **1. Set it up once, in a terminal.** This checks your computer, fetches the official Stable Audio 3 runtime at a tested commit, tells you how big the model download is and asks before downloading it. Running it again is safe; finished downloads are kept.
137
+
138
+ ```bash
139
+ # macOS
140
+ uvx --python 3.11 audio-studio-mcp setup
141
+ ```
142
+
143
+ ```powershell
144
+ # Windows
145
+ uvx --python 3.11 --torch-backend cu126 audio-studio-mcp setup
146
+ ```
147
+
148
+ `--torch-backend cu126` makes uv install the CUDA build of PyTorch (PyPI only has the CPU build for Windows), and `--python 3.11` keeps uv away from a Python that PyTorch doesn't support yet. If uvx answers `unexpected argument '--torch-backend'`, your uv is too old: update it with `winget upgrade astral-sh.uv` (or `uv self update`). On Windows, if you aren't logged in to Hugging Face yet, setup prints the steps: accept the license on the model page, then log in **in your own terminal** with `uvx --from huggingface_hub hf auth login` and run setup again.
149
+
150
+ **2. Register it with your MCP client.** Use the same command without `setup`:
151
+
152
+ ```bash
153
+ # Claude Code, macOS
154
+ claude mcp add --scope user audio-studio -- uvx --python 3.11 audio-studio-mcp
155
+ # Claude Code, Windows
156
+ claude mcp add --scope user audio-studio -- uvx --python 3.11 --torch-backend cu126 audio-studio-mcp
157
+ ```
158
+
159
+ <details>
160
+ <summary><b>Claude Desktop, Codex, VS Code, Cursor and other clients</b></summary>
161
+
162
+ On Windows, add `"--torch-backend", "cu126"` after `"3.11"` in each example below.
163
+
164
+ **Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`.cursor/mcp.json`) and most other clients:
165
+
166
+ ```json
167
+ {
168
+ "mcpServers": {
169
+ "audio-studio": {
170
+ "command": "uvx",
171
+ "args": ["--python", "3.11", "audio-studio-mcp"]
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ If the client says it can't find `uvx`, put its full path in `command` (`which uvx` on macOS, `where uvx` on Windows). Restart Claude Desktop after editing.
178
+
179
+ **Codex** (`~/.codex/config.toml`). Codex waits only 10 seconds for a server to start and 60 seconds for a tool call by default; long tracks need more:
180
+
181
+ ```toml
182
+ [mcp_servers.audio-studio]
183
+ command = "uvx"
184
+ args = ["--python", "3.11", "audio-studio-mcp"]
185
+ startup_timeout_sec = 60
186
+ tool_timeout_sec = 900
187
+ ```
188
+
189
+ **VS Code** (`.vscode/mcp.json`, or **MCP: Open User Configuration**):
190
+
191
+ ```json
192
+ {
193
+ "servers": {
194
+ "audio-studio": {
195
+ "type": "stdio",
196
+ "command": "uvx",
197
+ "args": ["--python", "3.11", "audio-studio-mcp"]
198
+ }
199
+ }
200
+ }
201
+ ```
202
+ </details>
203
+
204
+ Generated files go to `~/AudioStudio` (set `AUDIO_STUDIO_OUTPUT_DIR` to change it). uvx keeps the version it installed; to update, run `uv cache clean audio-studio-mcp` and then setup again.
205
+
206
+ > [!TIP]
207
+ > **Let your agent install it.** Paste this into Claude Code:
208
+ > *"Install the Audio Studio MCP server (https://github.com/kanaworksai-hue/audio-studio-mcp) by following its README, including the notes for AI agents."*
209
+ >
210
+ > **Notes for AI agents:**
211
+ > - Run the setup command for the user's OS yourself, with `-y` added, and give it a long timeout: it downloads 7–10 GB. If it is cut off, run it again; finished files are kept. Then register the server as shown above.
212
+ > - On Windows the model weights are gated and need the user's own Hugging Face login. If setup stops with the login steps, pass them on to the user and wait until they say they are done, then run setup again. Never ask the user to paste their token into the chat.
213
+ > - Before setup has finished, the server starts but every tool call answers with the setup command to run.
214
+
215
+ ### Alternative: install from source
216
+
217
+ The install scripts from earlier versions still work. They clone the repository, put the runtime in `vendor/` and the audio in `outputs/` inside it, and run from `.venv/`.
218
+
219
+ #### macOS (Apple Silicon)
220
+
221
+ **Requirements:**
222
+
223
+ - Apple Silicon Mac (M1 or later), 16 GB RAM recommended
224
+ - About 6 GB of disk for the model
225
+ - `git` and [`ffmpeg`](https://ffmpeg.org) (`brew install ffmpeg`)
226
+
227
+ ```bash
228
+ git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
229
+ cd audio-studio-mcp
230
+ ./install.sh
231
+ ```
232
+
233
+ The installer sets up [`uv`](https://docs.astral.sh/uv/) if needed, clones the official Stable Audio 3 runtime into `vendor/` at a tested commit, creates `.venv/`, and downloads the **medium** model (1.4B, ~5.9 GB) from [Hugging Face](https://huggingface.co/stabilityai/stable-audio-3-optimized). It finishes by printing the exact command to register the server:
234
+
235
+ ```bash
236
+ claude mcp add --scope user audio-studio -- /path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp
237
+ ```
238
+
239
+ #### Windows (NVIDIA GPU)
240
+
241
+ **Requirements:**
242
+
243
+ - 64-bit Windows 10 or 11 with an NVIDIA GPU (8 GB of VRAM or more) and a current driver. Tested on an RTX 3060 12 GB
244
+ - About 14 GB of disk for the model and PyTorch
245
+ - `git` (`winget install Git.Git`) and [`ffmpeg`](https://ffmpeg.org) (`winget install Gyan.FFmpeg`)
246
+ - A free [Hugging Face](https://huggingface.co) account. The PyTorch weights are gated: open [stabilityai/stable-audio-3-medium](https://huggingface.co/stabilityai/stable-audio-3-medium) and accept the license once
247
+
248
+ ```powershell
249
+ git clone https://github.com/kanaworksai-hue/audio-studio-mcp.git
250
+ cd audio-studio-mcp
251
+ powershell -ExecutionPolicy Bypass -File install.ps1
252
+ ```
253
+
254
+ The installer does the same steps as on macOS, but installs PyTorch with CUDA and downloads the official PyTorch checkpoint of the **medium** model (~10.4 GB). If you aren't logged in to Hugging Face yet, it asks for an access token with read permission ([create one here](https://huggingface.co/settings/tokens)). When it runs without a console (for example, started by an AI agent), it never asks: it prints the steps to log in and stops, and you re-run it after logging in. It finishes by printing the command to register the server:
255
+
256
+ ```powershell
257
+ claude mcp add --scope user audio-studio -- "C:\path\to\audio-studio-mcp\.venv\Scripts\audio-studio-mcp.exe"
258
+ ```
259
+
260
+ Flash Attention is not needed. Without it, the runtime falls back to PyTorch's built-in attention.
261
+
262
+ <details>
263
+ <summary><b>Claude Desktop, Cursor and other clients</b></summary>
264
+
265
+ Add this to `claude_desktop_config.json`, `.cursor/mcp.json` or your client's MCP config:
266
+
267
+ ```json
268
+ {
269
+ "mcpServers": {
270
+ "audio-studio": {
271
+ "command": "/path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp"
272
+ }
273
+ }
274
+ }
275
+ ```
276
+
277
+ On Windows the command is `C:\\path\\to\\audio-studio-mcp\\.venv\\Scripts\\audio-studio-mcp.exe` (backslashes doubled in JSON).
278
+ </details>
279
+
280
+ <details>
281
+ <summary><b>Installer options</b></summary>
282
+
283
+ | macOS | Windows | Effect |
284
+ |---|---|---|
285
+ | `--model all` | `-Model all` | Also download the small, fast `sm-music` and `sm-sfx` models (+2.6 GB on macOS, +7 GB on Windows) |
286
+ | `--skip-weights` | `-SkipWeights` | Don't download now; the first generation downloads them |
287
+ | `-y` | `-Yes` | Install `uv` without asking |
288
+
289
+ On macOS, downloads are anonymous; logging in with `hf auth login` raises Hugging Face's rate limit. On Windows, the PyTorch weights are gated: accept the license on each model page you download ([medium](https://huggingface.co/stabilityai/stable-audio-3-medium), [small-music](https://huggingface.co/stabilityai/stable-audio-3-small-music), [small-sfx](https://huggingface.co/stabilityai/stable-audio-3-small-sfx)) and log in.
290
+ </details>
291
+
292
+ Then just ask:
293
+
294
+ - "Make a 60-second lo-fi BGM loop at 85 BPM for a cafe scene, give me 3 candidates."
295
+ - "I need a heavy wooden door slamming in a stone hallway. Export it as OGG for Godot."
296
+ - "Extend this track to 90 seconds and normalize it to −16 LUFS."
297
+
298
+ ## 🧰 Tools
299
+
300
+ | Tool | What it does |
301
+ |---|---|
302
+ | `generate_audio` | Text to BGM, instrument loop/stem or sound effect. 1–4 candidates per call, `bpm`, structured SFX fields |
303
+ | `edit_audio` | `variation` (re-style the whole clip), `inpaint` (regenerate a time range), `continue` (extend). 1–4 candidates |
304
+ | `process_audio` | Trim → trim silence → mono → resample / loudness → seamless loop → fades → peak normalize or ceiling → WAV / OGG / FLAC. Never modifies the input |
305
+ | `unload_models` | Free the model memory right away |
306
+
307
+ <details>
308
+ <summary><b>Parameter notes</b></summary>
309
+
310
+ - **`audio_type`**: `music` / `instrument` / `sfx` / `raw`. The server adds the prefix the model was trained with (`TrackType: Music, VocalType: Instrumental,` …). Without the SFX prefix, sound effects often come out as music.
311
+ - **`variations`**: 1–4 candidates with seeds `seed, seed+1, …`. Use `seed: -1` or leave it out for a random seed.
312
+ - **`sound_source` / `sound_action` / `sound_material` / `sound_space`**: describe a sound effect by what makes it, how it evolves, its texture and the space it is in.
313
+ - **`peak_ceiling_db`** (default −1): a safety ceiling. Louder peaks are turned down and quieter audio is never boosted. Use `process_audio` to normalize.
314
+ - **`process_audio` normalization**: `peak` is common for SFX. `loudness` normalizes to a target LUFS: −14 for streaming/video, −16 for game BGM, −23 for broadcast.
315
+
316
+ Generated files are 44.1 kHz 24-bit stereo WAV, written to `outputs/` in this folder. Each one has a `<name>.json` next to it. Processed files keep the original generation info under `source`.
317
+ </details>
318
+
319
+ ## 🌐 Web UI
320
+
321
+ Prefer clicking to chatting? The same server comes with a local web page. Generate BGM and sound effects, compare the candidates, edit them (make a variation, replace a part, extend), export them for your game or video, and browse everything you've made in the library.
322
+
323
+ <p align="center">
324
+ <picture>
325
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/webui-generate-en-dark.png">
326
+ <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/webui-generate-en-light.png" alt="Web UI, Generate page: two versions of a lo-fi track to compare, and a footstep sound effect" width="820">
327
+ </picture>
328
+ <br><br>
329
+ <picture>
330
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/webui-edit-en-dark.png">
331
+ <img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/assets/webui-edit-en-light.png" alt="Web UI, Edit page: a selected part of the waveform will be replaced, with the original and two new versions to compare" width="820">
332
+ </picture>
333
+ </p>
334
+
335
+ ```bash
336
+ uvx --python 3.11 audio-studio-mcp --web 8765
337
+ ```
338
+
339
+ Your browser opens http://127.0.0.1:8765/. Add `--no-browser` to start without opening it, or `--preload` to load the model at startup. Press Ctrl+C to stop it. On Windows, add `--torch-backend cu126` after `3.11`. From a source install: `.venv/bin/audio-studio-mcp --web 8765` (Windows: `.venv\Scripts\audio-studio-mcp.exe --web 8765`).
340
+
341
+ The page and your MCP clients can share one process and one loaded model: the same port also serves MCP at `/mcp`. Register it once and use both at the same time. Requests from the page and from agents wait in one queue.
342
+
343
+ ```bash
344
+ claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp
345
+ ```
346
+
347
+ - Files are written to the output folder (`~/AudioStudio`, `outputs/` in a source install, or `AUDIO_STUDIO_OUTPUT_DIR`). The library shows that folder, and the editor works on the files in it.
348
+ - The page is in English, Japanese and Chinese and follows your browser's language. You can change it in the settings.
349
+
350
+ > [!WARNING]
351
+ > The web UI is for your own computer only. It listens on `127.0.0.1` only and has no login. Don't make it reachable from other machines (port forwarding, a reverse proxy or a tunnel): anyone who can open it can use your GPU and write files to your output folder.
352
+
353
+ ## ⚙️ Configuration
354
+
355
+ <details>
356
+ <summary><b>Environment variables</b></summary>
357
+
358
+ | Variable | Default | Meaning |
359
+ |---|---|---|
360
+ | `AUDIO_STUDIO_OUTPUT_DIR` | `~/AudioStudio` (source install: `<repo>/outputs`) | Where audio files are written |
361
+ | `AUDIO_STUDIO_IDLE_UNLOAD_MIN` | `10` | Free the models after this many idle minutes (`0` = never) |
362
+ | `AUDIO_STUDIO_SA3_MODEL` | `medium` | `medium` (best quality, up to 380 s), `sm-music` or `sm-sfx` (small and fast, up to 120 s) |
363
+ | `AUDIO_STUDIO_MLX_CACHE_GB` | `1` | macOS: cap on MLX's buffer cache. Without it, a long generation can leave ~6 GB cached |
364
+ | `AUDIO_STUDIO_DEVICE` | `cuda` if available | Windows/Linux: PyTorch device, e.g. `cuda`, `cuda:1` or `cpu` |
365
+ | `AUDIO_STUDIO_SA3_DIR` | downloaded by setup (source install: `<repo>/vendor/stable-audio-3`) | Use another stable-audio-3 checkout |
366
+ | `AUDIO_STUDIO_HOME` | macOS `~/Library/Application Support/audio-studio-mcp`, Windows `%LOCALAPPDATA%\\audio-studio-mcp` | Where setup keeps the Stable Audio 3 runtime (~1 MB). The weights stay in the Hugging Face cache |
367
+ | `AUDIO_STUDIO_BACKEND` | `auto` | `auto`, `sa3-mlx` (Apple Silicon) or `sa3-torch` (PyTorch, NVIDIA) |
368
+ | `AUDIO_STUDIO_FFMPEG` | `ffmpeg` on `PATH` | Path to ffmpeg |
369
+
370
+ Pass them with `claude mcp add ... -e NAME=value` or in the `env` block of your client config.
371
+ </details>
372
+
373
+ <details>
374
+ <summary><b>Share one server between sessions</b></summary>
375
+
376
+ Each client session normally starts its own server process. Models load on the first call and are freed after the idle timeout. To keep one warm process for every session, run it as a local HTTP server. It only listens on `127.0.0.1`.
377
+
378
+ ```bash
379
+ uvx --python 3.11 audio-studio-mcp --http 8765 --preload
380
+ claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp
381
+ ```
382
+
383
+ On Windows, add `--torch-backend cu126` after `3.11`. From a source install, start `.venv/bin/audio-studio-mcp` (Windows: `.venv\Scripts\audio-studio-mcp.exe`) with the same options.
384
+
385
+ `--web 8765` does the same and adds the [web UI](#-web-ui) on the same port.
386
+ </details>
387
+
388
+ ## ⚡ Performance
389
+
390
+ Medium model on an M1 Mac with 16 GB:
391
+
392
+ | Task | Time |
393
+ |---|---|
394
+ | Two 3 s sound effects, cold start | ~13 s |
395
+ | 20 s of music, warm | ~10 s (2× real time) |
396
+ | Continue to 35 s, incl. loading the encoder | ~27 s |
397
+ | 15 s of music with `sm-music`, warm | ~1 s |
398
+
399
+ Medium model on Windows with an RTX 3060 12 GB:
400
+
401
+ | Task | Time |
402
+ |---|---|
403
+ | Two 3 s sound effects, cold start (incl. ~20 s model load) | ~25 s |
404
+ | 20 s of music, warm | ~1.3 s |
405
+ | Continue to 30 s, warm | ~2.2 s |
406
+ | 380 s of music (the maximum), warm | ~15 s |
407
+ | 15 s of music with `sm-music`, warm | ~0.7 s |
408
+
409
+ On a Mac, loaded models use about 5–7 GB of memory. On the RTX 3060, the medium model peaked at about 5.3 GB of VRAM. Models are freed after the idle timeout or by `unload_models`.
410
+
411
+ ## 📝 Prompting tips
412
+
413
+ <details>
414
+ <summary><b>From the official Stable Audio 3 prompt guide</b></summary>
415
+
416
+ 1. **English, 1–2 sentences, up to ~45 words.** Avoid vocal words such as vocals, singer or lyrics.
417
+ 2. **Music:** genre + adjectives → lead instruments → supporting layers → drums/rhythm → mood. Put the tempo in `bpm`.
418
+ > 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.
419
+ 3. **Sound effects:** fill in source, action, material and space.
420
+ > source: glass bottle / action: shattering on impact, fragments scattering / material: thick green glass, sharp bright transient / space: concrete floor, close-up, dry
421
+ 4. **Match the length to the content:** impacts 1–3 s, actions 3–6 s, ambience 6–15 s+, loops 6–20 s, full tracks 120–300 s (max 380 s).
422
+ 5. **Timing instructions** like "climax at 15 s" are not followed reliably. Generate first, then use `inpaint` or `continue`.
423
+ 6. The defaults `steps=8` and `cfg=1.0` are the official settings. For stricter prompt adherence, or to use `negative_prompt`, try `cfg` 3–7 (about 2× slower).
424
+ 7. Results vary a lot by seed. Ask for 2–4 `variations` and pick the best.
425
+
426
+ The full guide is also sent to the client as the server's instructions.
427
+ </details>
428
+
429
+ ## ❓ FAQ
430
+
431
+ <details>
432
+ <summary><b>Does it run on Windows, Linux or Intel Macs?</b></summary>
433
+
434
+ **Windows:** yes, with an NVIDIA GPU. See [Quick start](#-quick-start).
435
+
436
+ **Linux:** with an NVIDIA GPU it uses the same PyTorch backend and should work, but it is untested. Use the `cuda` extra: `uvx --python 3.11 --torch-backend cu126 --from "audio-studio-mcp[cuda]" audio-studio-mcp setup`, and log in to Hugging Face as on Windows.
437
+
438
+ **Intel Macs and AMD GPUs** are not supported.
439
+ </details>
440
+
441
+ <details>
442
+ <summary><b>"Intel Macs are not supported" on an Apple Silicon Mac?</b></summary>
443
+
444
+ The environment was built with an x86_64 Python (for example an old Intel Homebrew under `/usr/local`) that runs under Rosetta, so MLX was skipped. With uvx, ask for uv's own arm64 Python, in setup and in your client's config: `uvx --python cpython-3.11-macos-aarch64 audio-studio-mcp`. With the install script, re-run `./install.sh`: it asks uv for an arm64 Python and recreates such a `.venv`. If you set `UV_PYTHON` yourself, point it at an arm64 build: `UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh`.
445
+ </details>
446
+
447
+ <details>
448
+ <summary><b>Can it make songs with vocals?</b></summary>
449
+
450
+ No. Stable Audio 3 generates instrumental music and sound effects. It cannot produce intelligible singing or lyrics.
451
+ </details>
452
+
453
+ <details>
454
+ <summary><b>Can I use the generated audio commercially?</b></summary>
455
+
456
+ The code here is MIT. The model weights are under the [Stability AI Community License](https://huggingface.co/stabilityai/stable-audio-3-optimized), which sets the terms for the model and what it generates. Read it before commercial use. At the time of writing it allows commercial use for individuals and organizations with less than US$1M in total annual revenue.
457
+ </details>
458
+
459
+ <details>
460
+ <summary><b>Will an 8 GB Mac work?</b></summary>
461
+
462
+ It hasn't been tested. The medium model needs about 5–7 GB while loaded, so 16 GB is recommended. The small `sm-music` / `sm-sfx` models are lighter.
463
+ </details>
464
+
465
+ <details>
466
+ <summary><b>My loop clicks at the seam.</b></summary>
467
+
468
+ Use WAV or OGG for loops. MP3 adds padding at the start and end, so it can't loop seamlessly. Also try a longer `loop_crossfade_ms`, or ask the model to cut on a bar line.
469
+ </details>
470
+
471
+ ## 🗺️ Roadmap
472
+
473
+ - [x] Apple Silicon backend (Stable Audio 3, MLX)
474
+ - [x] Windows backend for NVIDIA GPUs (Stable Audio 3, PyTorch)
475
+ - [x] Local web UI (`--web`)
476
+ - [x] One-command install with `uvx`
477
+ - [ ] LoRA support (the upstream runtime already has it)
478
+
479
+ Issues and pull requests are welcome.
480
+
481
+ ## ⭐ Like it? Star it
482
+
483
+ If Audio Studio made a sound you ended up using, please click **⭐ Star** at the top of the [repository page](https://github.com/kanaworksai-hue/audio-studio-mcp). It's free, takes one second, and helps more than it looks:
484
+
485
+ - **More people find it.** Stars make the project easier to discover on GitHub, so more game developers and video makers get to use it.
486
+ - **It keeps updates coming.** Every star tells me someone finds this useful. That's what keeps me working on the next update, like LoRA support.
487
+
488
+ Other ways to help: [open an issue](https://github.com/kanaworksai-hue/audio-studio-mcp/issues) for a bug or an idea, or share a sound you made on X and tag [@KanaWorks_AI](https://x.com/KanaWorks_AI).
489
+
490
+ ## 🛠️ Development
491
+
492
+ ```bash
493
+ uv run pytest # offline tests, no model needed
494
+ .venv/bin/python scripts/smoke_test.py # end-to-end with the real model (~30 s on an M1)
495
+ uv build && .venv/bin/python scripts/smoke_test.py --server "uvx --python 3.11 --from $(ls dist/*.whl) audio-studio-mcp"
496
+ # the same against the built wheel, as uvx runs it
497
+ ```
498
+
499
+ On Windows: `.venv\Scripts\python scripts\smoke_test.py` (~45 s on an RTX 3060, including model loading).
500
+
501
+ ```
502
+ src/audio_studio_mcp/
503
+ server.py MCP tools (backend-independent)
504
+ runtime.py where the runtime and outputs live; fetches the runtime for uvx installs
505
+ firstrun.py `audio-studio-mcp setup`
506
+ weights.py model weights: what is downloaded, downloading
507
+ prompts.py prompt building and the instructions sent to clients
508
+ post.py post-processing and export
509
+ backends/base.py backend interface
510
+ backends/sa3_mlx.py Stable Audio 3 on Apple Silicon (MLX)
511
+ backends/sa3_torch.py Stable Audio 3 on NVIDIA GPUs (PyTorch)
512
+ web.py web UI server (--web) and its JSON API
513
+ static/ web UI (HTML/JS/CSS, no build step)
514
+ ```
515
+
516
+ A new platform is added as another backend in `backends/`.
517
+
518
+ ## 📄 License and credits
519
+
520
+ - **This project:** [MIT](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/LICENSE).
521
+ - **Stable Audio 3 runtime:** downloaded by `setup` (or into `vendor/` by the install scripts) at a pinned commit. It is © Stability AI and MIT-licensed.
522
+ - **Model weights:** licensed under the [Stability AI Community License](https://huggingface.co/stabilityai/stable-audio-3-optimized). They are downloaded from Hugging Face (macOS: `stable-audio-3-optimized`; Windows: `stable-audio-3-medium` and the small models), not distributed here.
523
+ - **Brand:** the KanaWorks_AI name, logo and the Kana character are © 東京AI映像合同会社 (Tokyo AI Visuals LLC) and are **not** covered by the MIT license. See [docs/brand](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/docs/brand/README.md).
524
+ - **Fonts:** the web UI ships IBM Plex Sans, © IBM Corp., under the SIL Open Font License 1.1 ([`OFL.txt`](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/src/audio_studio_mcp/static/fonts/OFL.txt)). The Kana images in the web UI ([`static/brand`](https://github.com/kanaworksai-hue/audio-studio-mcp/blob/main/src/audio_studio_mcp/static/brand/README.md)) are covered by the Brand note above.
525
+ - **Built on:** [Stable Audio 3](https://github.com/Stability-AI/stable-audio-3), [MLX](https://github.com/ml-explore/mlx), [PyTorch](https://pytorch.org) and the [Model Context Protocol](https://modelcontextprotocol.io).
526
+
527
+ This is an independent project. It is not affiliated with or endorsed by Stability AI, Apple, NVIDIA or Anthropic.
528
+
529
+ <br>
530
+
531
+ <div align="center">
532
+
533
+ <a href="https://x.com/KanaWorks_AI"><img src="https://raw.githubusercontent.com/kanaworksai-hue/audio-studio-mcp/main/docs/brand/kana-wave.png" width="150" alt="Kana, the KanaWorks_AI mascot, waving"></a>
534
+
535
+ <p><b>Made with ♥ by <a href="https://x.com/KanaWorks_AI">KanaWorks_AI</a></b></p>
536
+
537
+ <p><sub>If Audio Studio saves you time, a ⭐ keeps the updates coming and helps others find it. More projects: <a href="https://github.com/kanaworksai-hue">github.com/kanaworksai-hue</a></sub></p>
538
+
539
+ </div>