Audio Studio MCP
- 추천0
- GitHub 별675
- 음성·오디오라이선스MIT
Claude 등 MCP 클라이언트에서 내 Mac·Windows PC의 Stable Audio 3로 배경음악·효과음을 만들고 편집·루프·내보내기까지 해요(로컬 실행)
설치 방법은 설치 탭에 정리했어요.
설명

English | 简体中文 | 日本語 | 한국어 | Português (Brasil) | Español
Audio Studio MCP는 Claude Code, Claude Desktop, Cursor 등 모든 MCP 클라이언트에 내 Mac 또는 Windows PC에서 돌아가는 사운드 스튜디오를 붙여 줍니다. 배경음악이나 효과음을 일상 언어로 부탁하면 Stable Audio 3로 로컬에서 생성합니다. 그런 다음 루프로 만들고, 음량을 정규화하고, 게임 엔진이나 영상 편집기용으로 내보낼 수 있습니다. 클라우드 서비스도 API 키도 필요 없고, 생성에 드는 비용도 없습니다.

실제 세션을 줄인 것입니다. Claude는 반복해도 박자가 어긋나지 않도록 루프 길이를 정확히 11마디로 골랐습니다.
✨ 주요 기능
| 한 문장으로 BGM, 악기 루프, 효과음을 생성합니다. 호출 한 번에 후보 1~4개 | 클립 전체의 스타일 바꾸기, 특정 구간 다시 생성, 트랙 늘리기 | 끊김 없는 루프, 페이드, 음량(LUFS), 48 kHz WAV / OGG / FLAC | Apple Silicon(MLX) 또는 NVIDIA GPU(PyTorch)에서 실행합니다. 업로드되는 것은 없습니다 |
- 채팅에서 바로 듣기: Claude Desktop 등 MCP Apps를 지원하는 클라이언트에서는 결과가 대화 안의 플레이어로 나타납니다. 파일을 열지 않고도 버전을 비교하고, 내보내고, 더 만들어 달라고 할 수 있습니다. 아래 「채팅에서 듣기」 절을 보세요.
- 재현 가능: 모든 파일에 프롬프트, 시드, 설정이 담긴
.json사이드카가 함께 생깁니다. - 프롬프트 작성 내장: 서버가 클라이언트에 공식 Stable Audio 3 프롬프트 형식을 알려 주므로, "삐걱거리는 문소리처럼 만들어 줘" 같은 요청이 모델이 이해하는 프롬프트로 바뀝니다.
- 원본과 같은 출력: Mac에서는 같은 시드의 결과가 공식
sa3CLI와 비트 단위로 같습니다. Windows에서는 공식 Stable Audio 3 PyTorch API를 호출합니다.
🎧 들어 보기
아래 소리는 모두 M1 Mac에서 이 서버로 생성했으며 손으로 편집하지 않았습니다. 샘플 페이지 열기 →
| 샘플 | 프롬프트 | |
|---|---|---|
| 로파이 카페 음악 · 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… | |
| 칩튠 모험 음악 · 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["You<br/>“make a cozy cafe BGM”"] --> C["Claude Code · Desktop<br/>Cursor · any MCP client"]
C -- "MCP" --> S["audio-studio-mcp<br/>generate · edit · process"]
S --> M["Stable Audio 3<br/>MLX on Apple Silicon<br/>PyTorch on NVIDIA GPUs"]
M --> F["WAV / OGG / FLAC + .json<br/>ready for game & video"]
🚀 빠른 시작
uv 0.9.20 이상과 ffmpeg가 필요합니다. 클론할 것은 없습니다. uvx가 배포된 패키지를 내려받아 실행합니다.
| macOS | Windows | |
|---|---|---|
| 하드웨어 | Apple Silicon(M1 이상), RAM 16GB 권장 | VRAM 8GB 이상의 NVIDIA GPU와 최신 드라이버. RTX 3060 12GB에서 테스트했습니다 |
| 디스크 | 약 8GB(모델 약 6.9GB) | 약 14GB(모델 약 10.4GB, PyTorch) |
| uv와 ffmpeg | brew install uv ffmpeg | winget install astral-sh.uv와 winget install Gyan.FFmpeg |
| 모델 라이선스 | 할 일 없음 | 무료 Hugging Face 계정이 필요합니다. stabilityai/stable-audio-3-medium을 열어 라이선스에 한 번 동의하세요 |
1. 터미널에서 처음 한 번 설정합니다. 컴퓨터를 점검하고, 검증된 커밋의 공식 Stable Audio 3 런타임을 가져오고, 모델 내려받기 용량을 알려 준 뒤 받기 전에 물어봅니다. 다시 실행해도 안전하며, 이미 끝난 다운로드는 유지됩니다.
# macOS
uvx --python 3.11 audio-studio-mcp setup
# Windows
uvx --python 3.11 --torch-backend cu126 audio-studio-mcp setup
--torch-backend cu126은 uv가 CUDA용 PyTorch를 설치하게 합니다(Windows용 PyPI에는 CPU 빌드만 있습니다). --python 3.11은 PyTorch가 아직 지원하지 않는 Python을 uv가 고르지 않게 합니다. uvx가 unexpected argument '--torch-backend'라고 답하면 uv 버전이 낮은 것이니 winget upgrade astral-sh.uv(또는 uv self update)로 업데이트하세요. Windows에서 아직 Hugging Face에 로그인하지 않았다면 setup이 순서를 알려 줍니다. 모델 페이지에서 라이선스에 동의한 다음, 직접 연 터미널에서 uvx --from huggingface_hub hf auth login으로 로그인하고 setup을 다시 실행하세요.
setup은 medium 모델을 내려받습니다. 작고 빠른 모델이 필요하면 --model sm-music, --model sm-sfx, --model all을 붙이고, 클라이언트 설정에 AUDIO_STUDIO_SA3_MODEL을 지정하세요(아래 「설정」 절 참고).
2. MCP 클라이언트에 등록합니다. setup만 뺀 같은 명령을 씁니다.
# Claude Code, macOS
claude mcp add --scope user audio-studio -- uvx --python 3.11 audio-studio-mcp
# Claude Code, Windows
claude mcp add --scope user audio-studio -- uvx --python 3.11 --torch-backend cu126 audio-studio-mcp
Claude Desktop, Codex, VS Code, Cursor 등 다른 클라이언트
Windows에서는 아래 예시마다 "3.11" 뒤에 "--torch-backend", "cu126"을 더하세요.
Claude Desktop(claude_desktop_config.json), Cursor(.cursor/mcp.json), 그리고 대부분의 다른 클라이언트:
{
"mcpServers": {
"audio-studio": {
"command": "uvx",
"args": ["--python", "3.11", "audio-studio-mcp"]
}
}
}
클라이언트가 uvx를 찾지 못한다고 하면 command에 전체 경로를 넣으세요(macOS는 which uvx, Windows는 where uvx). Claude Desktop은 설정을 고친 뒤 다시 시작하세요.
Codex(~/.codex/config.toml). Codex는 기본적으로 서버 시작을 10초, 도구 호출을 60초만 기다립니다. 긴 트랙에는 더 긴 시간이 필요합니다.
[mcp_servers.audio-studio]
command = "uvx"
args = ["--python", "3.11", "audio-studio-mcp"]
startup_timeout_sec = 60
tool_timeout_sec = 900
VS Code(.vscode/mcp.json, 또는 MCP: Open User Configuration):
{
"servers": {
"audio-studio": {
"type": "stdio",
"command": "uvx",
"args": ["--python", "3.11", "audio-studio-mcp"]
}
}
}
생성된 파일은 ~/AudioStudio에 저장됩니다(바꾸려면 AUDIO_STUDIO_OUTPUT_DIR을 지정하세요). uvx는 설치한 버전을 그대로 유지합니다. 업데이트하려면 uv cache clean audio-studio-mcp를 실행한 뒤 setup을 다시 실행하세요.
💡 에이전트에게 설치를 맡기세요. Claude Code에 이렇게 붙여 넣으세요. "Install the Audio Studio MCP server (https://github.com/kanaworksai-hue/audio-studio-mcp) by following its README, including the notes for AI agents."
AI 에이전트를 위한 안내:
- 사용자의 OS에 맞는 setup 명령에
-y를 붙여 직접 실행하고, 시간 제한을 길게 잡으세요. macOS는 약 7GB, Windows는 약 13GB(모델과 PyTorch)를 내려받습니다. 중간에 끊기면 다시 실행하세요. 끝난 파일은 유지됩니다. 그런 다음 위에 나온 대로 서버를 등록하세요.- Windows에서는 모델 가중치가 접근 제한(gated)되어 있어 사용자 본인의 Hugging Face 로그인이 필요합니다. setup이 로그인 순서를 안내하며 멈추면 그것을 사용자에게 전하고, 사용자가 끝났다고 할 때까지 기다린 뒤 setup을 다시 실행하세요. 사용자에게 토큰을 채팅에 붙여 넣게 하지 마세요.
- setup이 끝나기 전에는 서버가 시작은 되지만, 모든 도구 호출이 실행해야 할 setup 명령을 알려 주는 답만 돌려줍니다.
대안: 소스에서 설치
이전 버전의 설치 스크립트도 그대로 동작합니다. 저장소를 클론하고, 런타임은 그 안의 vendor/, 오디오는 outputs/에 두며, .venv/에서 실행합니다.
macOS (Apple Silicon)
요구 사항:
- Apple Silicon Mac(M1 이상), RAM 16GB 권장
- 디스크 약 8GB(모델 약 6.9GB)
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/에 클론하고, .venv/를 만들고, Hugging Face에서 medium 모델(1.4B, 약 6.9GB)을 내려받습니다. 마지막에 서버를 등록하는 정확한 명령을 출력합니다.
claude mcp add --scope user audio-studio -- /path/to/audio-studio-mcp/.venv/bin/audio-studio-mcp
Windows (NVIDIA GPU)
요구 사항:
- 64비트 Windows 10 또는 11, VRAM 8GB 이상의 NVIDIA GPU와 최신 드라이버. RTX 3060 12GB에서 테스트했습니다
- 모델과 PyTorch용 디스크 약 14GB
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.4GB)를 내려받습니다. 아직 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에서는 역슬래시를 두 번 씁니다).
설치 스크립트 옵션
| macOS | Windows | 효과 |
|---|---|---|
--model all | -Model all | 작고 빠른 sm-music, sm-sfx 모델도 함께 내려받습니다(macOS +2.6GB, Windows +7GB) |
--skip-weights | -SkipWeights | 지금은 내려받지 않습니다. 처음 생성할 때 내려받습니다 |
-y | -Yes | 묻지 않고 uv를 설치합니다 |
macOS에서는 익명으로 내려받으며, hf auth login으로 로그인하면 Hugging Face의 속도 제한이 올라갑니다. Windows에서는 PyTorch 가중치가 접근 제한되어 있으니, 받으려는 모델 페이지(medium, small-music, small-sfx)마다 라이선스에 동의하고 로그인하세요.
설치가 끝나면 이렇게 부탁해 보세요.
- "카페 장면에 쓸 85 BPM, 60초짜리 로파이 BGM 루프를 만들어 줘. 후보는 3개."
- "돌 복도에서 무거운 나무 문이 쾅 닫히는 소리가 필요해. Godot용 OGG로 내보내 줘."
- "이 트랙을 90초로 늘리고 −16 LUFS로 정규화해 줘."
🧰 도구
| 도구 | 하는 일 |
|---|---|
generate_audio | 텍스트로 BGM, 악기 루프/스템, 효과음을 만듭니다. 호출 한 번에 후보 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,…)를 붙여 줍니다. 효과음 접두어가 없으면 효과음이 음악으로 나오는 경우가 많습니다.variations: 시드seed, seed+1, …로 후보 1~4개를 만듭니다. 무작위 시드를 쓰려면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비트 스테레오 WAV이며 출력 폴더(~/AudioStudio, 소스 설치에서는 outputs/, AUDIO_STUDIO_OUTPUT_DIR 참고)에 저장됩니다. 파일마다 옆에 .json이 함께 생깁니다. 가공한 파일은 원래 생성 정보를 source 아래에 그대로 보관합니다.
🌐 웹 UI
대화보다 클릭이 편하신가요? 같은 서버에 로컬 웹 페이지가 함께 들어 있습니다. BGM과 효과음을 생성하고, 후보를 비교하고, 편집(변형 만들기, 일부 교체, 늘리기)하고, 게임이나 영상용으로 내보내고, 지금까지 만든 모든 것을 라이브러리에서 둘러볼 수 있습니다.


uvx --python 3.11 audio-studio-mcp --web 8765
브라우저가 http://127.0.0.1:8765/ 를 엽니다. 브라우저를 열지 않고 시작하려면 --no-browser, 시작할 때 모델을 미리 올리려면 --preload를 붙이세요. 중지는 Ctrl+C입니다. Windows에서는 3.11 뒤에 --torch-backend cu126을 붙이세요. 소스 설치에서는 .venv/bin/audio-studio-mcp --web 8765(Windows: .venv\Scripts\audio-studio-mcp.exe --web 8765)입니다.
웹 페이지와 MCP 클라이언트는 프로세스 하나와 올려 둔 모델 하나를 함께 쓸 수 있습니다. 같은 포트가 /mcp에서 MCP도 제공합니다. 한 번 등록해 두면 둘을 동시에 쓸 수 있고, 웹 페이지와 에이전트의 요청은 하나의 대기열에서 차례를 기다립니다.
claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp
- 파일은 출력 폴더(
~/AudioStudio, 소스 설치에서는outputs/, 또는AUDIO_STUDIO_OUTPUT_DIR)에 저장됩니다. 라이브러리는 그 폴더를 보여 주고, 편집기도 그 안의 파일로 작업합니다. - 페이지는 영어, 일본어, 중국어를 지원하며 브라우저 언어를 따릅니다. 설정에서 바꿀 수 있습니다.
⚠️ 웹 UI는 내 컴퓨터에서만 쓰세요.
127.0.0.1에서만 열리고 로그인이 없습니다. 다른 기기에서 접근할 수 있게 만들지 마세요(포트 포워딩, 리버스 프록시, 터널 등). 열 수 있는 사람은 누구든 내 GPU를 쓰고 출력 폴더에 파일을 쓸 수 있습니다.
💬 채팅에서 듣기
MCP Apps를 지원하는 클라이언트에서는 generate_audio, edit_audio, process_audio의 결과가 대화 안에 플레이어로 바로 나타납니다. 파일을 직접 열 필요가 없습니다.

던전 루프 세 버전. 실제 모델 출력이며 MCP Apps 레퍼런스 호스트에서 본 모습입니다.
- 듣고 비교하기: 파형, 재생, 일시정지, 탐색을 지원합니다. 한 버전을 재생하다가 다른 버전으로 바꾸면 같은 지점에서 이어서 재생됩니다.
1~9키로 버전을 고르고,0은 편집 전 오디오를 재생합니다. - 루프 확인: Loop를 켜고 Hear the seam을 누르면 끝이 처음으로 이어지는 부분을 들을 수 있습니다.
- 고르고, 내보내고, 더 만들기: Use this는 어느 버전을 골랐는지 어시스턴트에게 알려 줍니다. Export는 웹 UI와 같은 프리셋으로 게임이나 영상용으로 저장합니다. 2 more versions는 같은 프롬프트를 다음 시드로 다시 실행합니다.
- 플레이어는 클라이언트의 언어(영어, 일본어, 중국어)와 밝은/어두운 테마를 따릅니다. 내 컴퓨터 밖으로 나가는 것은 없습니다. 서버는 플레이어에 각 파일의 압축된 미리듣기만 보냅니다.
| 클라이언트 | 플레이어 |
|---|---|
| Claude Desktop | ✅ |
| VS Code (GitHub Copilot) | ✅ chat.mcp.apps.enabled를 켜세요(실험 기능) |
| Cursor, Goose 등 MCP Apps를 지원하는 클라이언트 | ✅ |
| Codex 앱(데스크톱) | ✅ |
| Claude Code, Codex CLI와 IDE 확장 프로그램, 그 외 클라이언트 | 이전과 같은 텍스트 결과 |
| claude.ai, ChatGPT | ❌ 원격 서버가 필요한데, 이 서버는 내 컴퓨터에서 실행됩니다 |
플레이어 없이 텍스트만 나오나요? MCP 설정을 바꾼 뒤에는 클라이언트를 다시 시작하세요. Claude Desktop의 일부 버전은 일반 채팅에서 로컬 서버의 앱을 보여 주지 않습니다(anthropics/claude-ai-mcp#1069). 시크릿 채팅에서는 보입니다. 플레이어를 끄려면 AUDIO_STUDIO_CHAT_PLAYER=off를 지정하세요.
⚙️ 설정
환경 변수
| 변수 | 기본값 | 뜻 |
|---|---|---|
AUDIO_STUDIO_OUTPUT_DIR | ~/AudioStudio(소스 설치: <저장소>/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 버퍼 캐시 상한. 이 값이 없으면 긴 생성 뒤 약 6GB가 캐시에 남을 수 있습니다 |
AUDIO_STUDIO_DEVICE | 가능하면 cuda | Windows/Linux: PyTorch 장치. 예: cuda, cuda:1, cpu |
AUDIO_STUDIO_SA3_DIR | setup이 내려받은 위치(소스 설치: <저장소>/vendor/stable-audio-3) | 다른 stable-audio-3 체크아웃을 사용 |
AUDIO_STUDIO_HOME | macOS ~/Library/Application Support/audio-studio-mcp, Windows %LOCALAPPDATA%\audio-studio-mcp | setup이 Stable Audio 3 런타임(약 1MB)을 두는 위치. 가중치는 Hugging Face 캐시에 남습니다 |
AUDIO_STUDIO_BACKEND | auto | auto, sa3-mlx(Apple Silicon), sa3-torch(PyTorch, NVIDIA) |
AUDIO_STUDIO_FFMPEG | PATH의 ffmpeg | ffmpeg 경로 |
AUDIO_STUDIO_CHAT_PLAYER | auto | 채팅 플레이어: auto는 MCP Apps 지원을 알리는 클라이언트에서만, off는 모든 곳에서 텍스트만, on은 지원을 알리지 않아도 MCP Apps를 보여 주는 클라이언트에도 켭니다(MCP Apps가 없는 클라이언트에는 보조 도구가 목록에 나타납니다) |
환경 변수는 claude mcp add ... -e NAME=value로 넘기거나 클라이언트 설정의 env 블록에 넣으세요.
세션끼리 서버 하나 공유하기
보통 클라이언트 세션마다 서버 프로세스를 따로 시작합니다. 모델은 첫 호출 때 올라가고 유휴 시간이 지나면 비워집니다. 모든 세션이 쓰는 프로세스 하나를 계속 켜 두려면 로컬 HTTP 서버로 실행하세요. 127.0.0.1에서만 열립니다.
uvx --python 3.11 audio-studio-mcp --http 8765 --preload
claude mcp add --scope user --transport http audio-studio http://127.0.0.1:8765/mcp
Windows에서는 3.11 뒤에 --torch-backend cu126을 붙이세요. 소스 설치에서는 같은 옵션으로 .venv/bin/audio-studio-mcp(Windows: .venv\Scripts\audio-studio-mcp.exe)를 시작하세요.
--web 8765는 같은 일을 하면서 같은 포트에 웹 UI를 더합니다.
⚡ 성능
16GB RAM의 M1 Mac에서 medium 모델:
| 작업 | 시간 |
|---|---|
| 3초 효과음 2개, 콜드 스타트 | 약 13초 |
| 음악 20초, 워밍업 후 | 약 10초(실시간의 2배) |
| 35초까지 이어 만들기(인코더 로딩 포함) | 약 27초 |
sm-music로 음악 15초, 워밍업 후 | 약 1초 |
Windows RTX 3060 12GB에서 medium 모델:
| 작업 | 시간 |
|---|---|
| 3초 효과음 2개, 콜드 스타트(모델 로딩 약 20초 포함) | 약 25초 |
| 음악 20초, 워밍업 후 | 약 1.3초 |
| 30초까지 이어 만들기, 워밍업 후 | 약 2.2초 |
| 음악 380초(최대), 워밍업 후 | 약 15초 |
sm-music로 음악 15초, 워밍업 후 | 약 0.7초 |
Mac에서는 모델을 올려 두면 메모리를 약 5~7GB 씁니다. RTX 3060에서 medium 모델은 VRAM을 최대 약 5.3GB 썼습니다. 모델은 유휴 시간이 지나거나 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.
- 효과음: source, action, material, space를 채우세요.
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로 클라이언트에도 전달됩니다.
❓ 자주 묻는 질문
Windows, Linux, Intel Mac에서도 되나요?
Windows: NVIDIA GPU가 있으면 됩니다. 위 「빠른 시작」을 보세요.
Linux: NVIDIA GPU가 있으면 같은 PyTorch 백엔드를 쓰므로 동작할 것으로 보이지만 테스트되지 않았습니다. cuda extra를 쓰세요: uvx --python 3.11 --torch-backend cu126 --from "audio-studio-mcp[cuda]" audio-studio-mcp setup, 그리고 Windows처럼 Hugging Face에 로그인하세요.
Intel Mac과 AMD GPU는 지원하지 않습니다.
Apple Silicon Mac인데 "Intel Macs are not supported"라고 나와요
x86_64 Python(예: /usr/local 아래의 오래된 Intel용 Homebrew)으로 환경이 만들어져 Rosetta에서 실행되기 때문에 MLX가 건너뛰어진 것입니다. uvx에서는 setup과 클라이언트 설정 모두에서 uv가 가진 arm64 Python을 지정하세요: uvx --python cpython-3.11-macos-aarch64 audio-studio-mcp. 설치 스크립트를 쓴다면 ./install.sh를 다시 실행하세요. arm64 Python을 요청해 그런 .venv를 다시 만듭니다. UV_PYTHON을 직접 지정했다면 arm64 빌드를 가리키게 하세요: UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh.
보컬이 있는 노래도 만들 수 있나요?
아니요. Stable Audio 3는 연주곡과 효과음을 생성합니다. 알아들을 수 있는 노래나 가사는 만들 수 없습니다.
생성한 오디오를 상업적으로 써도 되나요?
이 저장소의 코드는 MIT입니다. 모델 가중치는 Stability AI Community License를 따르며, 이 라이선스가 모델과 생성물의 조건을 정합니다. 상업적으로 쓰기 전에 꼭 읽어 보세요. 작성 시점에는 개인과 연간 총매출 100만 달러 미만의 조직에 상업적 사용을 허용합니다.
8GB Mac에서도 되나요?
테스트하지 않았습니다. medium 모델은 올려 두면 약 5~7GB가 필요해서 16GB를 권장합니다. 작은 sm-music / sm-sfx 모델은 더 가볍습니다.
루프의 이음매에서 딱 소리가 나요
루프에는 WAV나 OGG를 쓰세요. MP3는 앞뒤에 패딩이 붙어서 끊김 없이 이어지지 않습니다. loop_crossfade_ms를 더 길게 해 보거나, 모델에게 마디 경계에서 자르라고 부탁해 보세요.
🗺️ 로드맵
- Apple Silicon 백엔드(Stable Audio 3, MLX)
- NVIDIA GPU용 Windows 백엔드(Stable Audio 3, PyTorch)
- 로컬 웹 UI(
--web) -
uvx한 줄 설치 - 채팅에서 듣기(MCP Apps 플레이어)
- LoRA 지원(상위 런타임에는 이미 있습니다)
이슈와 풀 리퀘스트를 환영합니다.
⭐ 마음에 드셨나요? 스타를 눌러 주세요
Audio Studio가 만든 소리를 실제로 쓰게 되셨다면, 저장소 페이지 맨 위의 ⭐ Star를 눌러 주세요. 무료이고 1초면 되는데, 생각보다 큰 도움이 됩니다.
- 더 많은 사람이 찾게 됩니다. 스타가 많을수록 GitHub에서 발견되기 쉬워져서 더 많은 게임 개발자와 영상 제작자가 쓸 수 있습니다.
- 업데이트가 계속됩니다. 스타 하나하나가 누군가에게 쓸모가 있다는 신호이고, 그것이 LoRA 지원 같은 다음 업데이트를 계속하게 하는 힘입니다.
그 밖에 도울 수 있는 방법: 버그나 아이디어가 있으면 이슈를 열어 주세요. 직접 만든 소리를 X에 공유하며 @KanaWorks_AI를 태그해 주셔도 좋습니다.
🛠️ 개발
uv run pytest # 오프라인 테스트, 모델 불필요
.venv/bin/python scripts/smoke_test.py # 실제 모델로 처음부터 끝까지 테스트(M1에서 약 30초)
rm -rf dist && uv build && WHL=$(ls dist/*.whl) # uvx가 실행하는 것처럼, 빌드한 wheel로 같은 테스트:
uvx --python 3.11 --from "$WHL" audio-studio-mcp setup -y
.venv/bin/python scripts/smoke_test.py --server "uvx --python 3.11 --from $WHL audio-studio-mcp"
Windows에서는 .venv\Scripts\python scripts\smoke_test.py(모델 로딩 포함 RTX 3060에서 약 45초)를 쓰세요.
src/audio_studio_mcp/
server.py MCP tools (backend-independent)
runtime.py where the runtime and outputs live; fetches the runtime for uvx installs
firstrun.py `audio-studio-mcp setup`
weights.py model weights: what is downloaded, downloading
prompts.py prompt building and the instructions sent to clients
post.py post-processing and export
backends/base.py backend interface
backends/sa3_mlx.py Stable Audio 3 on Apple Silicon (MLX)
backends/sa3_torch.py Stable Audio 3 on NVIDIA GPUs (PyTorch)
web.py web UI server (--web) and its JSON API
static/ web UI (HTML/JS/CSS, no build step)
새 플랫폼은 backends/에 백엔드를 하나 더 추가하는 방식으로 지원합니다.
📄 라이선스와 크레딧
- 이 프로젝트: MIT.
- Stable Audio 3 런타임:
setup(또는 설치 스크립트의 경우vendor/)이 고정된 커밋으로 내려받습니다. © Stability AI, MIT 라이선스입니다. - 모델 가중치: Stability AI Community License를 따릅니다. Hugging Face에서 내려받으며(macOS:
stable-audio-3-optimized, Windows:stable-audio-3-medium과 작은 모델들) 이 저장소에서 배포하지 않습니다. - 브랜드: KanaWorks_AI 이름, 로고, Kana 캐릭터는 © 東京AI映像合同会社(Tokyo AI Visuals LLC)의 것이며 MIT 라이선스에 포함되지 않습니다. docs/brand를 보세요.
- 글꼴: 웹 UI에는 SIL Open Font License 1.1(
OFL.txt)에 따른 IBM Plex Sans(© IBM Corp.)가 들어 있습니다. 웹 UI의 Kana 이미지(static/brand)는 위의 브랜드 안내에 따릅니다. - 바탕이 된 것: Stable Audio 3, MLX, PyTorch, Model Context Protocol.
이 프로젝트는 독립 프로젝트입니다. Stability AI, Apple, NVIDIA, Anthropic과 제휴하거나 보증을 받은 것이 아닙니다.

Made with ♥ by KanaWorks_AI
Audio Studio가 시간을 아껴 주었다면 ⭐ 하나가 업데이트를 이어 가게 하고 다른 사람들이 이 프로젝트를 찾도록 돕습니다. 다른 프로젝트: github.com/kanaworksai-hue
