본문으로 건너뛰기
MCP 서버 전체 목록

Audio Studio MCP

Claude 등 MCP 클라이언트에서 내 Mac·Windows PC의 Stable Audio 3로 배경음악·효과음을 만들고 편집·루프·내보내기까지 해요(로컬 실행)

원본:kanaworksai-hue/audio-studio-mcp

설치 방법은 설치 탭에 정리했어요.

설명

License: MIT macOS Apple Silicon Windows NVIDIA GPU MCP server Python 3.10 to 3.13 Tests GitHub stars

Audio Studio MCP: Claude Code와 모든 MCP 클라이언트를 위한 로컬 AI 음악·효과음

KanaWorks_AI 로고 A KanaWorks_AI project

English | 简体中文 | 日本語 | 한국어 | Português (Brasil) | Español

🎧 샘플 듣기 · ⭐ 스타

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

실제 Claude Code 세션: 요청 하나로 로파이 BGM 후보 2개와 Godot용 끊김 없는 OGG 루프가 만들어집니다

실제 세션을 줄인 것입니다. Claude는 반복해도 박자가 어긋나지 않도록 루프 길이를 정확히 11마디로 골랐습니다.

✨ 주요 기능

생성 생성편집 편집마무리 마무리로컬 로컬
한 문장으로 BGM, 악기 루프, 효과음을 생성합니다. 호출 한 번에 후보 1~4개클립 전체의 스타일 바꾸기, 특정 구간 다시 생성, 트랙 늘리기끊김 없는 루프, 페이드, 음량(LUFS), 48 kHz WAV / OGG / FLACApple Silicon(MLX) 또는 NVIDIA GPU(PyTorch)에서 실행합니다. 업로드되는 것은 없습니다
  • 채팅에서 바로 듣기: Claude Desktop 등 MCP Apps를 지원하는 클라이언트에서는 결과가 대화 안의 플레이어로 나타납니다. 파일을 열지 않고도 버전을 비교하고, 내보내고, 더 만들어 달라고 할 수 있습니다. 아래 「채팅에서 듣기」 절을 보세요.
  • 재현 가능: 모든 파일에 프롬프트, 시드, 설정이 담긴 .json 사이드카가 함께 생깁니다.
  • 프롬프트 작성 내장: 서버가 클라이언트에 공식 Stable Audio 3 프롬프트 형식을 알려 주므로, "삐걱거리는 문소리처럼 만들어 줘" 같은 요청이 모델이 이해하는 프롬프트로 바뀝니다.
  • 원본과 같은 출력: Mac에서는 같은 시드의 결과가 공식 sa3 CLI와 비트 단위로 같습니다. Windows에서는 공식 Stable Audio 3 PyTorch API를 호출합니다.

🎧 들어 보기

아래 소리는 모두 M1 Mac에서 이 서버로 생성했으며 손으로 편집하지 않았습니다. 샘플 페이지 열기 →

샘플프롬프트
로파이 카페 샘플로파이 카페 음악 · 30초 · 85 BPMLo-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 BPMUpbeat 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가 배포된 패키지를 내려받아 실행합니다.

macOSWindows
하드웨어Apple Silicon(M1 이상), RAM 16GB 권장VRAM 8GB 이상의 NVIDIA GPU와 최신 드라이버. RTX 3060 12GB에서 테스트했습니다
디스크약 8GB(모델 약 6.9GB)약 14GB(모델 약 10.4GB, PyTorch)
uv와 ffmpegbrew install uv ffmpegwinget 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에서는 역슬래시를 두 번 씁니다).

설치 스크립트 옵션

macOSWindows효과
--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_audiovariation(클립 전체 스타일 바꾸기), 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과 효과음을 생성하고, 후보를 비교하고, 편집(변형 만들기, 일부 교체, 늘리기)하고, 게임이나 영상용으로 내보내고, 지금까지 만든 모든 것을 라이브러리에서 둘러볼 수 있습니다.

웹 UI 생성 화면: 비교할 수 있는 로파이 트랙 두 버전과 발소리 효과음

웹 UI 편집 화면: 선택한 파형 구간이 교체되며, 원본과 새 버전 두 개를 비교할 수 있습니다

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의 결과가 대화 안에 플레이어로 바로 나타납니다. 파일을 직접 열 필요가 없습니다.

대화 안의 플레이어: 던전 루프 세 버전의 파형이 보이고, 2번 버전이 재생 중이며 각 버전에 「Use this」와 「Export」 버튼이 있습니다

던전 루프 세 버전. 실제 모델 출력이며 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_MIN10이 분 수만큼 쉬면 모델을 비웁니다(0 = 비우지 않음)
AUDIO_STUDIO_SA3_MODELmediummedium(최고 품질, 최대 380초), sm-music 또는 sm-sfx(작고 빠름, 최대 120초)
AUDIO_STUDIO_MLX_CACHE_GB1macOS: MLX 버퍼 캐시 상한. 이 값이 없으면 긴 생성 뒤 약 6GB가 캐시에 남을 수 있습니다
AUDIO_STUDIO_DEVICE가능하면 cudaWindows/Linux: PyTorch 장치. 예: cuda, cuda:1, cpu
AUDIO_STUDIO_SA3_DIRsetup이 내려받은 위치(소스 설치: <저장소>/vendor/stable-audio-3)다른 stable-audio-3 체크아웃을 사용
AUDIO_STUDIO_HOMEmacOS ~/Library/Application Support/audio-studio-mcp, Windows %LOCALAPPDATA%\audio-studio-mcpsetup이 Stable Audio 3 런타임(약 1MB)을 두는 위치. 가중치는 Hugging Face 캐시에 남습니다
AUDIO_STUDIO_BACKENDautoauto, sa3-mlx(Apple Silicon), sa3-torch(PyTorch, NVIDIA)
AUDIO_STUDIO_FFMPEGPATH의 ffmpegffmpeg 경로
AUDIO_STUDIO_CHAT_PLAYERauto채팅 플레이어: 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. 영어로, 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. 효과음: 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

  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로 클라이언트에도 전달됩니다.

❓ 자주 묻는 질문

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과 제휴하거나 보증을 받은 것이 아닙니다.

Kana, 손을 흔드는 KanaWorks_AI 마스코트

Made with ♥ by KanaWorks_AI

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


저장소: https://github.com/kanaworksai-hue/audio-studio-mcp