OmniVoice
개요
OmniVoice Studio MCP 서버를 통해 오디오를 로컬에서 생성합니다. 도구: generate_speech, list_voices, list_personalities, list_languages, check_health. 리소스: voice://{id}, history://recent.
사전 조건 — 백엔드가 실행 중이어야 함
MCP 도구는 모두 $OMNIVOICE_API_URL (기본값 http://localhost:3900)을 호출합니다. 백엔드가 다운되면 모든 도구에서 연결 오류가 반환됩니다. 설치 및 실행:
git clone https://github.com/debpalash/OmniVoice-Studio.git "$OMNIVOICE_HOME"
cd "$OMNIVOICE_HOME"
uv sync
VIRTUAL_ENV="$(pwd)/.venv" uv pip install 'mcp[cli]'
그런 다음:
scripts/check-health.sh # 정상이면 종료 코드 0
scripts/start-backend.sh # 백그라운드에서 실행 (MPS/CUDA 자동 감지)
첫 번째 합성 호출 시 k2-fsa/OmniVoice 모델(~2.4GB)을 HuggingFace에서 지연 다운로드하며, 이후 부팅 시에는 캐시됩니다.
작업 인덱스 — 적절한 도구 선택
| 작업 | 도구 | 참고 사항 |
|---|---|---|
| 백엔드가 실행 중인지 확인 | check_health | `{"status":"ok","device":"mps |
| 저장된 음성으로 텍스트 → 오디오 | generate_speech(text, profile_id) | Base64 WAV 반환. profile_id="demo0001"은 번들 데모 음성 |
| 복제 없이 텍스트 → 오디오 (음성 디자인) | generate_speech(text, instruct="…") | profile_id 생략; "warm middle-aged female narrator, calm pace"와 같은 instruct 전달 |
| 다국어 내레이션 | generate_speech(text, language="es") | 모든 ISO 639 코드 또는 "Auto" |
| 기존 음성 목록 | list_voices | id, name, type, personality 반환 |
| 성격 프리셋 목록 | list_personalities | narrator / casual / news-anchor 등과 해당 instruct 문자열 반환 |
| 지원 언어 목록 | list_languages | 총 646개; 인기 언어 20개 + 전체 개수 반환 |
중요한 결정(어떤 엔진을 사용할지, 언제 kokoro / Edge TTS / ElevenLabs보다 OmniVoice를 선택할지)은 참조/engines-comparison.md를 참조하세요.
MCP 연결 세부 정보, 백엔드 수명 주기, 문제 해결 및 정리 방법은 참조/mcp-setup.md를 참조하세요.
일반적인 워크플로우
1. 데모 음성으로 원샷 내레이션
# MCP 클라이언트를 통해 호출 (에이전트가 자동으로 수행):
result = generate_speech(
text="Hello — this is OmniVoice generating speech locally.",
profile_id="demo0001",
language="English",
steps=16, # 8 = 빠름/초안 · 16 = 균형 · 32 = 품질
)
# result는 audio_id, generation_time_s, audio_duration_s, format, wav_base64가 포함된 JSON
벤치마크: Apple Silicon MPS에서 16 확산 단계로 약 4.2초 분량의 오디오를 서버 측에서 약 24초 만에 생성.
2. WAV를 디스크에 저장하고 재생
도구는 base64 PCM WAV(16비트, 모노, 24kHz)를 반환합니다. 디코딩 및 쓰기:
import base64, json
payload = json.loads(result_text) # 도구가 반환한 JSON 파싱
open("out.wav","wb").write(base64.b64decode(payload["wav_base64"]))
macOS: afplay out.wav. MP3 변환: ffmpeg -i out.wav -codec:a libmp3lame -b:a 128k out.mp3.
3. 음성 복제 — 종단간 레시피
복제를 위해서는 모델이 스피커 임베딩으로 사용할 3~10초 분량의 참조 클립이 필요합니다. MCP 서버는 프로필 생성을 노출하지 않으며, 기존 프로필만 읽습니다. 프로필을 만드는 두 가지 방법:
방법 A — 번들 헬퍼 (macOS, 새 복제에 권장):
scripts/record-reference.sh ~/Downloads/my-ref.wav 12 1
# 인수: 출력_경로 원본_길이_초 마이크_인덱스
# 기본 마이크_인덱스=1 (MacBook 내장); 장치 목록:
# ffmpeg -f avfoundation -list_devices true -i ""
이 스크립트는 macOS say + /System/Library/Sounds/Ping.aiff를 통해 청각적 카운트다운과 시작/중지 신호를 제공하여 사용자가 말할 시점을 알 수 있게 합니다 (터미널 stdout은 버퍼링되어 "speak now" 프롬프트가 너무 늦게 도착함). 더 긴 원시 윈도우를 녹음한 후 silenceremove + atrim으로 약 10초 분량의 음성으로 정리하고, 재생하여 확인한 후 다음 단계 curl 명령을 출력합니다.
방법 B — 수동:
# 1. 녹음 (모노, 24kHz 네이티브 — 모델의 내부 속도와 일치)
ffmpeg -f avfoundation -i ":1" -t 12 -ac 1 -ar 24000 raw.wav
# 2. 앞쪽 무음 자르고 처음 10초 음성 추출
ffmpeg -i raw.wav \
-af "silenceremove=start_periods=1:start_silence=0.05:start_threshold=-40dB,atrim=end=10" \
-ac 1 -ar 24000 ref.wav
# 3. 확인
ffmpeg -i ref.wav -af volumedetect -f null - 2>&1 | grep volume # 최대값이 -20dB보다 커야 함
afplay ref.wav
/profiles에 POST (multipart/form-data — 필수 필드: name, ref_audio):
curl -X POST http://127.0.0.1:3900/profiles \
-F "name=carlos-clone" \
-F "[email protected]" \
-F "ref_text=The exact text spoken in the clip" \
-F "language=English" \
| python3 -m json.tool
# 반환: { "id": "abc12345", "name": "carlos-clone" }
생성 후 profile_id를 generate_speech(MCP를 통해) 또는 직접 POST /generate를 통해 전달합니다. 프로필은 SQLite + 참조 오디오 파일(~/Library/Application Support/OmniVoice/voices/<id>.<ext>)에 유지됩니다 (백엔드는 업로드된 확장자를 유지 — WAV를 업로드하면 .wav, MP3면 .mp3 등). 상태는 백엔드 재시작 후에도 유지됩니다.
품질에 실질적으로 영향을 미치는 참조 클립 팁:
| 요소 | 중요한 이유 |
|---|---|
| 단일 화자 | 혼합 화자는 임베딩을 흐릿하게 만듦 |
| 깨끗한 음성, 음악/잡음 없음 | 모델이 잡음도 임베딩함 |
| 자연스러운 운율 (팡그램 지양) | 확산 샘플은 음색뿐만 아니라 운율도 재현함 |
| 3~10초가 최적 | < 3초는 정보 부족; > 10초는 품질 향상 없이 계산만 증가 |
ref_text를 실제 발화와 일치 | 정렬 향상, 특히 잡음이 많은 참조에서 효과적 |
language 정확 | 잘못된 언어 → 교차 언어 전송 아티팩트 |
| 음량 피크 ≥ -15dB | 조용한 참조도 작동하지만 정규화가 잘 안 됨 |
4. 음성 디자인 (참조 클립 없음)
profile_id를 생략하고 원하는 음성을 설명하는 instruct 문자열을 제공합니다:
generate_speech(
text="Welcome to the future of agentic systems.",
instruct="warm middle-aged female narrator, calm authoritative pace, documentary style",
)
list_personalities를 통해 미리 만들어진 instruct를 가져와서 요구 사항에 맞는 것 (narrator, casual, news-anchor 등)을 복사하여 사용할 수 있습니다.
5. 비디오 더빙 (웹 UI 전용)
MCP 서버는 더빙 엔드포인트를 노출하지 않습니다. 전체 트랜스크립트 → 번역 → 재음성 → 믹스 파이프라인은 데스크톱 UI ($OMNIVOICE_HOME에서 bun run desktop)와 /dub/* REST 경로 뒤에 있습니다. 사용자가 비디오 더빙을 요청하면 UI를 안내하고, 이 스킬은 위의 합성 기본 요소에만 사용합니다.
OmniVoice를 사용하지 말아야 할 경우
- 약한 하드웨어에서 빠른 영어 전용 내레이션 →
kokoro-tts는 크기가 약 10배 작고 CPU에서 실시간의 2배 속도 (자세한 내용은 참조/engines-comparison.md 참조) - 가장 간편한 일회성 TTS → Edge TTS는 설치나 백엔드가 필요 없음
- 비용에 관계없이 최고 품질 → ElevenLabs가 여전히 영어 내레이션 마감에서 우수; OmniVoice는 다국어 + 복제에서 동등하거나 우수
- 실시간 스트리밍 받아쓰기 → OmniVoice 데스크톱 위젯(
⌘+⇧+Space)을 사용하고 MCP 서버는 사용하지 마세요
리소스
- 참조/engines-comparison.md — OmniVoice / kokoro / Voicebox / Edge TTS / ElevenLabs / 클라우드 API 간 결정 트리
- 참조/mcp-setup.md — MCP 연결, 백엔드 수명 주기, 환경 변수, 문제 해결
- scripts/check-health.sh —
curl /health, 종료 코드 0/1 - scripts/start-backend.sh — uvicorn을 127.0.0.1:3900에서 상태 확인과 함께 시작
- scripts/stop-backend.sh — 바인딩된 PID에
kill -TERM을 통해 깔끔하게 종료 - scripts/record-reference.sh — macOS 전용: 복제용 참조 클립 녹음, 정리, 확인; 터미널 출력 버퍼링을 우회하는 청각적 신호(
say+ 시스템 비프음) 제공
백엔드 Swagger / OpenAPI: http://127.0.0.1:3900/docs (백엔드 실행 중일 때).
업스트림: github.com/debpalash/OmniVoice-Studio — FSL-1.1-ALv2 (개인/내부/비상업적 용도로 무료; 각 릴리스 후 2년이 지나면 자동으로 Apache-2.0으로 전환).