VoiceStudio 로컬에서 쓰는 법

VoiceStudio(debpalash/VoiceStudio)는 로컬에서 돌아가는 오픈소스 음성 스튜디오다. 클라우드 ElevenLabs류를 대체하려고 만든 앱으로, 음성 클론·보이스 디자인·영상 더빙·받아쓰기·전사·오디오북을 646개 언어 범위에서 다룬다. 라이선스 AGPL-3.0. 기본 TTS 엔진은 k2-fsa/OmniVoice. 최신 데스크톱은 Electron v0.5.6(GitHub Releases, 2026-09-23 UTC 게시). Tauri 최종은 v0.5.3이고, 지금 쓰는 셸은 Electron뿐이다. 공식 사이트 voicestudio.sh. GitHub 스타는 작성 시점 API 기준 약 51,300.

이 글은 “VoiceStudio 로컬에서 쓰는 법”만 다룬다. 설치 → 첫 클론 → 로컬 API·MCP까지 README와 공식 install/MCP 문서를 따라간다. 상업용 Mac 앱(aiaudiogen.com 쪽)과는 다른 프로젝트다.

핵심 요약 (TL;DR)

• 무엇인가: 로컬 ElevenLabs 대안. 클론·디자인·더빙·받아쓰기·전사·오디오북. 기본 엔진 OmniVoice.
• 설치: curl -fsSL https://voicestudio.sh/install | sh (macOS/Linux). Windows는 irm https://voicestudio.sh/install | iex. 또는 Releases의 Electron 패키지 / Docker.
• 첫 클론: Voice cloning → 깨끗한 참조 음성 → 텍스트·언어 → Generate. 모델은 프롬프트에서 설치.
• 로컬 포트: 백엔드 기본 http://localhost:3900. MCP는 http://localhost:3900/mcp/(끝 슬래시 유지).
• 주의: Electron 설치 파일은 Apple 공증 전(v0.5.6 노트). Intel Mac은 UI만 + 원격 백엔드. VRAM 하한은 README에 고정 숫자로 없다 → performance.md·Model Catalogue를 본다.

할 수 있는 일

용어를 짧게 푼다. 음성 클론은 짧은 참조 녹음으로 “그 사람 말투”에 가깝게 TTS를 만드는 일이다. 보이스 디자인은 참조 없이 문장으로 성별·톤·억양 같은 속성을 지정해 새 목소리를 만드는 쪽이다. 더빙은 영상 음성 구간을 맞춰 다시 입히는 워크플로다. MCP는 Model Context Protocol로, Claude Code·Cursor 같은 에이전트가 로컬 백엔드에 붙어 말하게 하는 연결 계층이다. 에이전트 하네스에 VoiceStudio를 붙이면, 코딩 에이전트가 파일·터미널뿐 아니라 음성 생성·전사 도구까지 같은 로컬 루프 안에 둘 수 있다.

• 클론 / 디자인: 참조 샘플로 클론하거나, 설명 문장으로 디자인 보이스를 만든다(README·MCP 도구 표).
• 더빙·스토리·오디오북: 타이밍이 있는 더빙, 배치·챕터 작업. v0.5.6은 긴 오디오북 챕터가 8 GB GPU에서도 끝나도록 보강했다고 릴리스 노트가 적는다.
• 받아쓰기·전사: 플로팅 위젯 받아쓰기, OpenAI-compatible 전사 HTTP/WebSocket(speech-platform.md).
• 로컬 API·MCP: 포트 3900의 데이터면 + /mcp/. 데스크톱 Integrations에서 Claude Code·Cursor·Codex 설정을 내보낸다.
• 엔진 선택: 기본 OmniVoice 외에 Model Catalogue에서 다른 TTS/ASR을 고를 수 있다(feature-catalog·engines 문서).

필요한 것

VRAM 최소치는 README 설치표에 하드 숫자로 박혀 있지 않다. 하드웨어 필요량은 엔진마다 다르니 performance.md와 앱 안 Model Catalogue를 본다. 문서에 나온 용량만 적으면: Docker 첫 실행 모델 가중치 약 2.4 GB(docker.md), OmniVoice 첫 generate 다운로드 약 2.3 GB(mcp.md).

단계 1: 설치

가장 짧은 경로는 공식 원라이너다(README).

# macOS / Linux — 최신 Electron
curl -fsSL https://voicestudio.sh/install | sh

# 특정 버전
curl -fsSL https://voicestudio.sh/install | sh -s -- --version 0.5.6

# 현재 main을 빌드해 데스크톱 설치
curl -fsSL https://voicestudio.sh/install | sh -s -- --main

# 앱 제거(데이터는 유지)
curl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall

Windows PowerShell:

irm https://voicestudio.sh/install | iex

또는 Releases v0.5.6에서 고른다.

• macOS Apple Silicon: VoiceStudio-Electron-0.5.6-mac-arm64.dmg
• macOS Intel: VoiceStudio-Electron-0.5.6-mac-x64.dmg — UI만. 로컬 Python 백엔드는 불가(PyTorch Intel-Mac 휠 중단). 원격 백엔드에 연결(macos.md).
• Windows x64: VoiceStudio-Electron-0.5.6-win-x64.exe
• Linux x64: VoiceStudio-Electron-0.5.6-linux-x64.AppImage · .deb

다운로드 후 SHA256SUMS.txt와 비교하라고 Gatekeeper/신뢰 안내가 적는다. v0.5.6 릴리스 노트: Electron 설치 파일은 서명·공증 전(unsigned/ad-hoc)이라 macOS/Windows가 경고를 띄울 수 있다. macOS는 Finder에서 앱을 우클릭 → Open(한 번 확인). “damaged”만 뜨면 재다운로드 또는 xattr -dr com.apple.quarantine "/Applications/VoiceStudio.app"(macos.md).

Docker(헤드리스·서버·브라우저 UI). 문서 기준 이미지 경로는 ghcr.io/debpalash/voicestudio(Docker Hub 미러 palashdeb/omnivoice-studio 동일 태그). 관리자 API 키를 먼저 만든다.

export OMNIVOICE_API_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"

docker pull ghcr.io/debpalash/voicestudio:latest

docker run -d --name omnivoice \
  -p 127.0.0.1:3900:3900 \
  -e OMNIVOICE_API_KEY="$OMNIVOICE_API_KEY" \
  -v omnivoice-data:/app/omnivoice_data \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  ghcr.io/debpalash/voicestudio:latest

NVIDIA면 --gpus all을 붙인다. 브라우저에서 http://localhost:3900. 첫 실행은 약 2.4 GB 가중치를 받으니 docker logs -f omnivoice로 본다(docker.md). 프로덕션 핀은 :stable 또는 :0.5.6. 이미지는 linux/amd64만 — Apple Silicon에서 Docker로 GPU(MPS)는 못 쓰고, 네이티브 macOS 앱을 쓰라고 문서가 안내한다.

소스에서 Electron 미리보기(README):

git clone https://github.com/debpalash/VoiceStudio.git
cd VoiceStudio
bun install
bun run setup:api
bun run dev

단계 2: 첫 음성 클론

README Quickstart 그대로다.

1. Voice cloning을 연다.
2. 깨끗한 참조 녹음을 고른다. 3초도 동작하고, 보통은 5–15초가 낫다고 README가 적는다. v0.5.6은 OmniVoice에서 20초를 넘는 긴 참조도 클론할 수 있게 바뀌었고, UI가 “엔진이 참조의 얼마를 쓰는지”를 보여 준다고 릴리스 노트가 적는다.
3. 텍스트와 언어를 넣고 Generate. 필요 모델 설치 안내가 뜨면 따른다.
4. 하드웨어·엔진별 체감은 Settings → Performance & Device, Model Catalogue, performance.md를 본다.

막히면 앱 안 Settings → About → Run self-check, 또는 소스에서 uv run python backend/main.py --diagnose(troubleshooting.md).

단계 3: 로컬 API / MCP (선택)

백엔드가 떠 있으면 MCP는 추가 프로세스 없이 /mcp/에 마운트된다(mcp.md).

http://localhost:3900/mcp/

끝 슬래시를 유지한다. 데스크톱 Integrations에서 Claude Code(.mcp.json), Cursor(.cursor/mcp.json), Codex CLI(~/.codex/config.toml)용 설정을 내보낼 수 있다. Codex 예(문서):

[mcp_servers.voicestudio]
url = "http://127.0.0.1:3900/mcp/"
http_headers = { "X-OmniVoice-Client-Id" = "codex-cli" }

도구 예: generate_speech, clone_voice, design_voice, transcribe, list_voices, check_health. 에이전트마다 X-OmniVoice-Client-Id로 다른 보이스를 묶을 수 있다. 코딩 에이전트에 스킬을 넣으려면:

npx skills add debpalash/VoiceStudio

OpenAI-compatible 쪽은 같은 포트의 데이터면이다. 예: POST :3900/v1/audio/transcriptions, 스트림 ws://127.0.0.1:3900/v1/audio/transcriptions/stream. 데스크톱 네이티브 받아쓰기 제어는 루프백 :3902(speech-platform.md). 루프백 클라이언트는 자격 증명이 없고, 원격·공유는 API 키·PIN·신뢰 네트워크 규칙을 api-auth·mcp 문서를 따른다.

첫 MCP generate_speech는 OmniVoice 미설치 상태면 약 2.3 GB를 받으며 타임아웃 예산 안에서 돈다. 미리 Model Catalogue에서 깔거나 OMNIVOICE_GENERATE_TIMEOUT_S를 올리라고 mcp.md가 적는다.

막히는 지점 / 왜 막히나

한눈에 비교

실사용자 반응

여기 인용구를 지어내지 않는다. 공식 README·릴리스·이슈 테마만 요약한다. README는 “Your voice. Your workflow.”로 로컬 생성·더빙·에이전트 연결을 한 화면에 둔다. 주간 트렌드에 오를 만큼 관심은 크지만, 이슈·troubleshooting이 보여 주는 현실 축은 첫 모델 다운로드·VRAM/RAM·미공증 Gatekeeper·Intel Mac 한계·엔진 충돌이다. v0.5.6 릴리스는 MCP/에이전트 연결 카드, 긴 참조 클론, 8 GB GPU 오디오북, Twilio(기본 꺼짐) 같은 통합을 강조한다. 질문·버그는 GitHub Issues, 진단 번들은 Settings → About → Save diagnostic bundle 경로를 문서가 가리킨다.

의미와 시사점

검색어 “VoiceStudio 쓰는 법”은 상용 Mac 앱이나 일반 DAW와 섞이기 쉽다. 여기서의 VoiceStudio는 AGPL 로컬 음성 플랫폼이고, Electron v0.5.6이 현재 데스크톱이다. TWMS 독자 기준으로는 OpenShell(에이전트 격리 런타임)·Orca(병렬 ADE)와 결이 다르다. 이쪽은 에이전트가 말할 목소리와 전사·더빙 파이프를 로컬에 두는 쪽이다. MCP를 켠 순간 코딩 에이전트 하네스에 오디오 도구가 붙는다. 대신 디스크·첫 다운로드·플랫폼별 제약은 클라우드 SaaS보다 무겁다. “로컬이니까 공짜·무제한”이 아니라, 모델 라이선스·동의 없는 클론 금지를 LICENSE-NOTICE·README가 같이 적어 둔다.

마치며

따라갈 최소 루프는 이렇다. curl …/install | sh(또는 Releases DMG/exe) → Gatekeeper 한 번 열기 → Voice cloning에서 짧은 참조로 Generate → 필요하면 /mcp/를 Cursor·Claude Code에 붙이기. Docker는 서버·헤드리스용. Intel Mac·미공증·첫 2 GB대 모델 받기는 “고장”이 아니라 문서에 적힌 경로다. 더 깊은 엔진·벤치·성능은 Docs의 engines·performance·troubleshooting으로 넘어가면 된다.

출처

• github.com/debpalash/VoiceStudio
• voicestudio.sh · download
• Release v0.5.6
• docs/install/docker.md · macos.md · troubleshooting.md
• docs/mcp.md · speech-platform.md

이 글은 AI가 작성하여 자동 발행된 콘텐츠입니다.