vox-tts
https://vox.delo.sh 에서 셀프 호스팅되는 TTS 서비스입니다. VoxCPM2를 기반으로 하며, PostgreSQL 기반 음성 프로필 저장소와 여러 엔진을 지원합니다. ~/code/voxxy에 배포되어 있습니다 (핵심: compose.yml, GPU 엔진: compose.engines.yml — 두 엔진 컨테이너가 모두 실행 중이어야 합니다. 그렇지 않으면 복제 음성이 저하됩니다. 아래 참조).
빠른 참조
| 동작 | 방법 |
|---|---|
| 일회성 합성 (인라인 WAV 바이트) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| Telegram / 브라우저 / HA / Discord 전달을 위한 합성 | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| MCP 도구: 인라인 바이트 (base64 WAV) | speak(text, voice?) |
| MCP 도구: 전달 URL (OGG/Opus, Telegram 준비 완료) | speak_url(text, voice?) |
| MCP 도구: 음성 목록 조회 | list_voices_tool() |
| 음성 목록 조회 (HTTP) | GET /voices |
| 음성 추가 | POST /voices (멀티파트: name, display_name, audio) |
| 대화형 음성 복제 (사용자가 "내 목소리를 ~로 복제해줘"라고 말하는 경우) | 아래 대화형 음성 복제 워크플로우 참조 |
| 엔진 업그레이드 (VoxCPM / VibeVoice) | 아래 엔진 업그레이드 워크플로우 참조 |
| Hermes 에이전트에서 말하기 | 기본 tts.provider: vox (fleet base); fleet은 vox MCP를 로드하지 않음 |
| 셸 / 터미널이 있는 모든 에이전트에서 말하기 | voxxy speak "텍스트" (voxxy speak --help 참조) |
| 기본 vox 경로가 없는 MCP 클라이언트에 등록 | https://vox.delo.sh/mcp/ 의 MCP 서버 (후행 슬래시 필수) |
| Node-RED | ~/docker/stacks/utils/vox/node-red-contrib-vox/ 의 node-red-contrib-vox |
| 상태 + 엔진 상태 확인 | GET /healthz |
/mcp/ 의 후행 슬래시는 필수입니다. 없으면 FastAPI가 307 리디렉션을 반환하고 HTTPX가 POST 본문을 삭제합니다.
speak vs speak_url: 올바른 것 선택
| 오디오가 다음으로 전송될 경우... | 사용 | 이유 |
|---|---|---|
| Telegram / Discord / Slack | speak_url | 채널 API가 URL을 허용합니다. 서버에서 가져옵니다. 에이전트 와이어에 바이트 블로트가 없습니다. |
브라우저 <audio> 태그에 파이프 | speak_url | 브라우저가 URL을 스트리밍합니다. base64 왕복이 없습니다. |
Home Assistant media_player.play_media에 전달 | speak_url | HA는 media_content_id 에 URL을 필요로 합니다. |
| 에이전트에서 인라인으로 처리 (연결, 분석, 반복) | speak | 바이트가 이미 로컬에 있습니다. URL 가져오기는 홉을 추가합니다. |
| 셸 스크립트에서 로컬 파일로 작성 | 둘 다 가능 | speak_url + curl -o 가 base64 + base64 -d 보다 쉽습니다. |
기본값은 speak_url 입니다. 에이전트의 토큰 비용이 없으며 (응답이 작은 JSON임), 원시 인라인 바이트 처리를 제외한 모든 전달 표면에서 작동합니다.
엔진 폴백
GET /healthz 는 등록된 엔진과 각 엔진의 사용 가능 여부를 보고합니다:
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
오케스트레이터는 순서대로 시도합니다. 모든 speak_url / speak 응답은 engine: "voxcpm" 또는 engine: "elevenlabs" 를 포함하므로 폴백이 발생했는지 감지할 수 있습니다. ElevenLabs는 ELEVENLABS_API_KEY 가 설정되지 않으면 자동으로 비활성화됩니다.
음성별 ElevenLabs 매핑은 voices.elevenlabs_voice_id 열에 있습니다. NULL은 전역 기본값 (ELEVENLABS_DEFAULT_VOICE, 기본적으로 Adam)으로 폴백됩니다.
복제된 음성은 엔진에 바인딩됩니다. POST /voices 를 통해 복제된 음성은 참조를 vibevoice_ref_path 에 저장하고 vibevoice 엔진이 먼저 제공합니다 (요청당 preferred 라우팅은 app/engines.py 에서 처리, 나머지는 VOX_ENGINES 순서를 따르며 voxcpm이 먼저임). vibevoice가 다운되면 voxcpm이 여전히 참조 클립을 받습니다 — app/voices.py:46-48 은 특정 재정의가 없는 모든 엔진에 대해 wav_path 로 폴백합니다 — 따라서 복제는 저하되지만 지워지지는 않습니다. 증상은 낯선 사람이 아닌 인식 가능하지만 잘못된 읽기입니다. 해결 방법: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice 를 실행한 다음 /healthz 에서 "name":"vibevoice","ready":true 를 확인합니다.
음성을 완전히 대체하는 것은 ElevenLabs 폴백입니다: 두 GPU 엔진이 모두 다운되고 ELEVENLABS_API_KEY 가 설정된 경우, vox는 낯선 사람의 목소리로 200 을 응답하고 vox: voice clone BYPASSED 를 기록한 다음 어쨌든 전달합니다. 모든 복제 합성에서 engine 필드를 확인하십시오 — vibevoice 또는 voxcpm 은 복제된 음성이고, elevenlabs 는 당신의 음성이 아닙니다.
참조 예산은 30초가 아니라 10초입니다. 두 개의 다른 상한이 누적되며, 두 번째 상한만 중요합니다. POST /voices 는 수집을 VOX_REF_AUDIO_MAX_SECONDS = 30초로 자릅니다 (compose.yml:16, app/main.py:578-584 에서 적용, 처음 30초 유지). 그러나 vibevoice 컨테이너는 동일한 변수를 10으로 설정하고 (compose.engines.yml:69), engines/vibevoice/engine/synth.py:183,208 은 duration=10.0 으로 참조를 다시 로드합니다. /healthz 에서 직접 확인할 수 있습니다: "max_ref_seconds": 10.0. 따라서 모든 참조 클립의 10-30초는 저장되고 백업되지만 모델에서 사용되지 않습니다. 8-10초의 깨끗한 복제 구절을 작성하고 가장 좋고 중립적인 음성을 먼저 넣으십시오. 이후의 모든 것은 무게입니다.
상세 절차
관련 구현 또는 진단을 보려면 음성 및 통합 워크플로우를 읽으십시오. 음성 복제 및 외부 전달은 사용자가 해당 작업을 요청해야 합니다.
기본값 치트 시트
| 매개변수 | 기본값 | 참고 사항 |
|---|---|---|
cfg | 2.0 | 분류기 없는 안내; 높을수록 더 충실하고 변형이 적음 |
steps | 10 | 확산 단계; 속도를 위해 4-6, 최대 품질을 위해 15-20 |
normalize | false | 텍스트 정규화 (숫자 → 단어 등) |
denoise | false | 죽은 필드. app/main.py:98 에 선언되었지만 어디에서도 읽지 않음; POST /voices 에는 denoise 매개변수가 전혀 없습니다. 대신 업로드 전에 오디오를 정리하십시오. |
| 캐시 TTL (오디오 URL) | 3600s | VOX_AUDIO_TTL_SECONDS 환경 변수; Telegram에는 1시간이 충분함 |
| 폴백 음성 (ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | ELEVENLABS_DEFAULT_VOICE 환경 변수 |
합성은 RTX 3090에서 VOX_OPTIMIZE=1 로 초당 약 21자 속도로 실행됩니다 — 측정된 값이며 추정치가 아닙니다: 60자 라인은 약 2초, 1,665자 라인은 약 35초가 걸립니다. 2초 헤드라인이 아닌 길이로 예산을 세우십시오. 컨테이너 재시작 후 첫 번째 호출은 약 15초가 추가됩니다 (JIT 컴파일). OGG/Opus 트랜스코딩은 ffmpeg를 통해 100ms 미만이 추가됩니다.
이것은 시간 초과가 있는 모든 호출자에게 중요합니다. Hermes vox TTS 플러그인은 60초 httpx 시간 초과를 하드코딩하고 (plugins/tts/vox/__init__.py:29,316) tts.vox.timeout 을 무시하므로, 약 2,500자를 초과하는 단일 청크는 실패합니다. tts.vox.max_text_length 로 제한하십시오 (tools/tts_tool.py:436-441 에서 읽음). 이는 실패하는 대신 청크로 분할합니다.
엔진 업그레이드 워크플로우
세 컨테이너 토폴로지는 핵심 오케스트레이션 (voxxy-core, 컨테이너 vox, CPU 전용)을 GPU 바운드 사이드카 엔진 (voxxy-engine-voxcpm, voxxy-engine-vibevoice)에서 분리합니다. 각 엔진 컨테이너는 engines/<name>/ 아래에 자체 pyproject.toml, uv.lock, Dockerfile 을 유지 관리합니다.
단계별 업그레이드 절차
1. 버전 검색 및 런타임 감사
- 업스트림 릴리스: PyPI 및 GitHub 릴리스 확인:
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - 실행 중인 컨테이너 버전:
importlib.metadata를 통해 설치된 패키지 버전 확인:(절대docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__을 사용하지 마십시오. 모듈이 이를 정의하지 않으며AttributeError가 발생합니다). - Hugging Face의 모델 가중치: 모델 가중치 스냅샷이 업데이트되었는지 확인:
패키지 업데이트 (추론 코드, 스트리밍 VAE 디코더, 장치 처리)는 모델 가중치 개정판과 별개입니다.cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. 종속성 범프 및 잠금 파일 업데이트
engines/<name>/pyproject.toml에서 버전 핀 범프 (예:voxcpm==2.0.3).- uv로 종속성 재잠금:
cd engines/voxcpm && uv lock - diff 검토 (
git diff engines/voxcpm/uv.lock)하여 PyTorch 및 torchaudio가 명시적pytorch-cu124인덱스에 고정되어 있고 PyPI CPU 휠로 표류하지 않는지 확인.
3. 엔진 컨테이너 이미지 재빌드
compose를 통해 엔진 이미지 재빌드:
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# 또는 mise 별칭 사용:
mise run build:voxcpm
Dockerfile은 uv를 통해 Python 3.12를 프로비저닝하고 uv sync --frozen --no-install-project 를 /opt/venv 에 실행합니다.
4. compose 프로필로 엔진 컨테이너 재생성
엔진 컨테이너는 compose.engines.yml 에 compose 프로필로 정의됩니다 (profiles: ["voxcpm"] / profiles: ["vibevoice"]). --profile 을 전달해야 합니다. 그렇지 않으면 compose가 서비스를 무시합니다:
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
컨테이너가 새 버전을 선택했는지 확인:
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. 확인 및 스모크 테스트
- 컨테이너 시작: 성공적인 모델 로드에 대한 로그 검사:
docker logs --tail 30 voxxy-engine-voxcpm # 확인: "Loaded VoxCPM2Model" 및 "Application startup complete." - 엔진 healthz:
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # 예상: {"engine":"voxcpm","ready":true,"model_loaded":true,...} - 직접 합성 테스트: Docker 네트워크를 통해
vox코어 컨테이너에서 직접 원시 합성 페이로드 전송:docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \ -H 'content-type: application/json' \ -d '{"text":"Testing synthesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}' - 음성 복제 확인: 참조 오디오 샘플로 테스트 (
/data/voices/rick.wav):docker exec vox python3 -c ' import base64, urllib.request, json with open("/data/voices/rick.wav", "rb") as f: b64 = base64.b64encode(f.read()).decode("ascii") data = json.dumps({"text": "Test clone.", "reference_audio_b64": b64}).encode("utf-8") req = urllib.request.Request("http://voxxy-engine-voxcpm:8000/v1/synthesize", data=data, headers={"Content-Type": "application/json"}) print(json.loads(urllib.request.urlopen(req).read().decode("utf-8"))) ' - 계약 및 CLI 테스트:
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. 전달
엔진 디렉토리에 pyproject.toml 과 uv.lock 을 모두 커밋:
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main
얻은 교훈 및 엔진 주의사항
voxcpm패키지 버전 검사:voxcpm은__version__을 노출하지 않습니다.python -c "import voxcpm; print(voxcpm.__version__)"을 호출하면AttributeError가 발생합니다. 항상importlib.metadata.version('voxcpm')으로 설치된 메타데이터를 검사하십시오.- Compose 프로필 요구 사항:
compose.engines.yml에서 각 엔진에는 프로필이 있습니다 (profiles: ["voxcpm"]).--profile voxcpm없이docker compose up voxxy-engine-voxcpm을 실행하면 Docker Compose가 서비스를 자동으로 건너뜁니다. - 대기 엔진은 직접 테스트 가능: 단일 GPU 카드의 로컬 엔진은 상호 배타적입니다 (VoxCPM ~5GB VRAM, VibeVoice ~7.5GB VRAM). 엔진이
voxxy daemon status/.voxxy.state.json에서standby모드에 있더라도 해당 컨테이너는 내부 Docker 네트워크 (http://voxxy-engine-<name>:8000)에서 실행 중이고 정상 상태를 유지합니다. 활성 엔진을 전환하지 않고vox에서 curl을 통해 직접 테스트할 수 있습니다. - Pytest 테스트 스위트 위치: 저장소 루트에서
pytest를 실행하면 실패합니다.plugins/tts/vox/는 Hermes 플러그인으로,agent.tts_provider...
[번역을 위해 잘림]