vox-tts
Ein selbst gehosteter TTS-Dienst unter https://vox.delo.sh, der VoxCPM2 mit einem PostgreSQL-gestützten Stimmprofil-Speicher und Unterstützung für mehrere Engines kapselt. Bereitgestellt unter ~/code/voxxy (Kern: compose.yml, GPU-Engines: compose.engines.yml – beide Engine-Container müssen laufen, sonst verschlechtern sich Klone stillschweigend, siehe unten).
Kurzübersicht
| Aktion | Wie |
|---|---|
| One-off-Synthese (Inline-WAV-Bytes) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| Synthese zur Auslieferung an Telegram / Browser / HA / Discord | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| MCP-Tool: Inline-Bytes (Base64-WAV) | speak(text, voice?) |
| MCP-Tool: Liefer-URL (OGG/Opus, Telegram-bereit) | speak_url(text, voice?) |
| MCP-Tool: Stimmen auflisten | list_voices_tool() |
| Stimmen auflisten (HTTP) | GET /voices |
| Stimme hinzufügen | POST /voices (Multipart: name, display_name, audio) |
| Interaktives Stimmklonen (Nutzer sagt „Klon meine Stimme als…“) | Siehe Interaktiver Stimmklon-Workflow unten |
| Upgrade einer Engine (VoxCPM / VibeVoice) | Siehe Engine-Upgrade-Workflow unten |
| Sprache über einen Hermes-Agenten | Nativ via tts.provider: vox (Fleet-Basis); die Fleet lädt NICHT das vox MCP |
| Sprache von einer Shell / einem beliebigen Agenten mit Terminal | voxxy speak "text" (siehe voxxy speak --help) |
| Registrierung bei einem MCP-Client ohne nativen vox-Pfad | MCP-Server unter https://vox.delo.sh/mcp/ (nachgestellter Schrägstrich erforderlich) |
| Node-RED | node-red-contrib-vox unter ~/docker/stacks/utils/vox/node-red-contrib-vox/ |
| Health + Engine-Status | GET /healthz |
Der nachgestellte Schrägstrich bei /mcp/ ist zwingend erforderlich. Ohne ihn führt FastAPI eine 307-Weiterleitung durch und HTTPX verwirft den POST-Body.
speak vs speak_url: Die richtige Wahl treffen
| Wenn das Audio... | Verwende | Grund |
|---|---|---|
| An Telegram / Discord / Slack gesendet wird | speak_url | Kanal-APIs akzeptieren eine URL; ihre Server rufen sie ab. Null Byte-Bloat auf der Agenten-Leitung. |
In ein Browser <audio>-Tag eingebunden wird | speak_url | Browser streamen URLs; kein Base64-Roundtrip. |
An Home Assistant media_player.play_media übergeben wird | speak_url | HA benötigt eine URL für media_content_id. |
| Vom Agenten inline verarbeitet wird (Splice, Analyse, Schleife) | speak | Bytes sind bereits lokal; ein URL-Abruf würde einen zusätzlichen Hop bedeuten. |
| In einer Shell-Skript in eine lokale Datei geschrieben wird | Beides | speak_url + curl -o ist einfacher als Base64 + base64 -d. |
Standardmäßig speak_url verwenden. Es kostet den Agenten keine Tokens (die Antwort ist ein kleines JSON) und funktioniert auf allen Lieferoberflächen außer der rohen Inline-Byte-Verarbeitung.
Engine-Fallback
GET /healthz meldet, welche Engines registriert und ob jede verfügbar ist:
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
Der Orchestrator probiert sie der Reihe nach. Jede speak_url / speak-Antwort enthält engine: "voxcpm" oder engine: "elevenlabs", damit du erkennen kannst, wann der Fallback aktiviert wurde. ElevenLabs deaktiviert sich automatisch, wenn ELEVENLABS_API_KEY nicht gesetzt ist.
Die pro-stimme ElevenLabs-Zuordnung befindet sich in der Spalte voices.elevenlabs_voice_id. Bei NULL wird auf den globalen Standard zurückgegriffen (ELEVENLABS_DEFAULT_VOICE, standardmäßig Adam).
Geklonte Stimmen sind engine-gebunden. Eine über POST /voices geklonte Stimme speichert ihre Referenz in vibevoice_ref_path und wird zuerst von der vibevoice-Engine bedient (pro-Anfrage preferred-Routing in app/engines.py; alles andere folgt der VOX_ENGINES-Reihenfolge, voxcpm zuerst). Wenn vibevoice ausfällt, erhält voxcpm trotzdem das Referenz-Clip — app/voices.py:46-48 fällt auf wav_path für jede Engine ohne spezifische Überschreibung zurück — der Klon verschlechtert sich also, er wird nicht gelöscht. Das Symptom ist ein erkennbarer, aber abweichender Vortrag, kein Fremder. Behebung: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, dann bestätige "name":"vibevoice","ready":true in /healthz.
Derjenige, der die Stimme durch eine andere ersetzt, ist der ElevenLabs-Fallback: Wenn beide GPU-Engines ausfallen und ELEVENLABS_API_KEY gesetzt ist, antwortet vox mit 200 in einer fremden Stimme, protokolliert vox: voice clone BYPASSED, und liefert sie trotzdem aus. Überprüfe das engine-Feld bei jeder Klon-Synthese — vibevoice oder voxcpm ist der Klon, elevenlabs ist nicht deine Stimme.
Das Referenz-Budget beträgt 10 Sekunden, nicht 30. Zwei verschiedene Obergrenzen stapeln sich, und nur die zweite ist wichtig. POST /voices kürzt den Import auf VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, angewendet in app/main.py:578-584, wobei die ersten 30s behalten werden). Aber der vibevoice-Container setzt dieselbe Variable auf 10 (compose.engines.yml:69), und engines/vibevoice/engine/synth.py:183,208 lädt die Referenz mit duration=10.0 neu. Sein /healthz sagt es direkt: "max_ref_seconds": 10.0. Sekunden 10–30 eines Referenz-Clips werden also gespeichert, gesichert und vom Modell nie gesehen. Schreibe Klon-Passagen für 8–10 saubere Sekunden und platziere den besten, neutralsten Sprachvortrag zuerst – alles danach ist tote Last.
Detaillierte Verfahren
Lies Sprach- und Integrations-Workflows für die entsprechende Implementierung oder Diagnose. Stimmklonen und externe Zustellung erfordern, dass der Benutzer diese Aktionen anfordert.
Standardwerte Spickzettel
| Parameter | Standard | Hinweise |
|---|---|---|
cfg | 2.0 | Classifier-free guidance; höher = treuer, weniger Variation |
steps | 10 | Diffusionsschritte; 4-6 für Geschwindigkeit, 15-20 für maximale Qualität |
normalize | false | Textnormalisierung (Zahlen → Wörter usw.) |
denoise | false | Totes Feld. Deklariert in app/main.py:98, nirgends gelesen; POST /voices hat überhaupt keinen Denoise-Parameter. Bereinige das Audio stattdessen vor dem Hochladen. |
| Cache-TTL (Audio-URLs) | 3600s | VOX_AUDIO_TTL_SECONDS-Umgebungsvariable; 1h ist reichlich für Telegram |
| Fallback-Stimme (ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | ELEVENLABS_DEFAULT_VOICE-Umgebungsvariable |
Die Synthese läuft mit etwa 21 Zeichen pro Sekunde auf einer RTX 3090 mit VOX_OPTIMIZE=1 — gemessen, nicht geschätzt: Eine 60-Zeichen-Zeile dauert ~2s, eine 1.665-Zeichen-Zeile ~35s. Plane nach Länge, nicht nach der 2s-Schlagzeile. Der erste Aufruf nach einem Container-Neustart fügt ~15s hinzu (JIT-Kompilierung). OGG/Opus-Transcodierung fügt <100ms via ffmpeg hinzu.
Dies ist für jeden Aufrufer mit einem Timeout wichtig. Das Hermes vox TTS-Plugin hardcodiert einen 60s httpx-Timeout (plugins/tts/vox/__init__.py:29,316) und ignoriert tts.vox.timeout, sodass ein einzelner Chunk von mehr als etwa 2.500 Zeichen sofort fehlschlägt. Begrenze es mit tts.vox.max_text_length (gelesen in tools/tts_tool.py:436-441), das anstatt eines Fehlschlags chunked.
Engine-Upgrade-Workflow
Die Drei-Container-Topologie entkoppelt die Kernorchestrierung (voxxy-core, Container vox, nur CPU) von GPU-gebundenen Sidecar-Engines (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Jeder Engine-Container verwaltet sein eigenes pyproject.toml, uv.lock und Dockerfile unter engines/<name>/.
Schritt-für-Schritt-Upgrade-Verfahren
1. Version Discovery & Laufzeit-Audit
- Upstream-Releases: Überprüfe PyPI und GitHub-Releases:
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - Laufende Container-Version: Überprüfe die installierte Paketversion via
importlib.metadata:(Verwende niemalsdocker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__; das Modul definiert es nicht und wirftAttributeError). - Modellgewichte auf Hugging Face: Prüfe, ob sich der Snapshot der Modellgewichte aktualisiert hat:
Paketaktualisierungen (Inferenzcode, Streaming-VAE-Decoder, Geräteverwaltung) sind von den Revisionen der Modellgewichte zu unterscheiden.cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. Abhängigkeits-Updates & Lockfile aktualisieren
- Erhöhe den Version-Pin in
engines/<name>/pyproject.toml(z.B.voxcpm==2.0.3). - Sperre Abhängigkeiten mit uv neu:
cd engines/voxcpm && uv lock - Überprüfe den Diff (
git diff engines/voxcpm/uv.lock), um sicherzustellen, dass PyTorch und torchaudio auf dem explizitenpytorch-cu124-Index bleiben und nicht zu PyPI CPU-Rädern abwandern.
3. Erstelle das Engine-Container-Image neu
Erstelle das Engine-Image über compose neu:
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# Oder über mise-Alias:
mise run build:voxcpm
Das Dockerfile richtet Python 3.12 über uv ein und führt uv sync --frozen --no-install-project in /opt/venv aus.
4. Erstelle den Engine-Container mit Compose-Profil neu
Engine-Container sind mit Compose-Profilen in compose.engines.yml definiert (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Du musst --profile übergeben, sonst ignoriert Compose den Dienst:
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
Überprüfe, ob der Container die neue Version übernommen hat:
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. Verifikation & Smoke-Tests
- Container-Start: Überprüfe die Logs auf erfolgreiches Laden des Modells:
docker logs --tail 30 voxxy-engine-voxcpm # Suche nach: "Loaded VoxCPM2Model" und "Application startup complete." - Engine-Healthz:
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # Erwartet: {"engine":"voxcpm","ready":true,"model_loaded":true,...} - Direkter Synthese-Test: Sende eine rohe Synthese-Payload direkt vom
vox-Kerncontainer über das Docker-Netzwerk: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)}' - Verifikation des Stimmklons: Teste mit einer Referenz-Audio-Datei (
/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"))) ' - Vertrags- und CLI-Tests:
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. Auslieferung
Comitte sowohl pyproject.toml als auch uv.lock im Engine-Verzeichnis:
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main
Lessons Learned & Engine-Fallen
voxcpmPaketversionsabfrage:voxcpmgibt KEIN__version__aus. Der Aufruf vonpython -c "import voxcpm; print(voxcpm.__version__)"wirftAttributeError. Überprüfe immer die installierten Metadaten mitimportlib.metadata.version('voxcpm').- Compose-Profile-Anforderung: In
compose.engines.ymlhat jede Engine ein Profil (profiles: ["voxcpm"]). Wenn dudocker compose up voxxy-engine-voxcpmohne--profile voxcpmausführst, überspringt Docker Compose den Dienst stillschweigend. - Standby-Engines sind direkt testbar: Lokale Engines auf einer einzelnen GPU-Karte schließen sich gegenseitig aus (VoxCPM ~5 GB VRAM, VibeVoice ~7,5 GB VRAM). Selbst wenn eine Engine im
standby-Modus ist (invoxxy daemon status/.voxxy.state.json), läuft ihr Container weiter und bleibt auf dem internen Docker-Netzwerk gesund (http://voxxy-engine-<name>:8000). Du kannst sie direkt über curl vomvox-Container aus testen, ohne die aktive Engine umschalten zu müssen. - Pytest-Testsuite-Speicherort: Das Ausführen von
pytestvom Repository-Stammverzeichnis schlägt fehl, daplugins/tts/vox/ein Hermes-Plugin ist, das einenagent.tts_providererwartet. Führe Tests stattdessen immer im Engine-Verzeichnis aus:cd engines/voxcpm && uv run pytest. - Kein automatischer Container-Neustart nach dem Build: Der Build-Schritt (
docker compose build) aktualisiert das Image, ersetzt aber NICHT den laufenden Container. Verwendeup -d --no-build, um den neuen Container aus dem zwischengespeicherten Image zu erstellen, und vermeide das Flag--build, das einen weiteren Build durchführen würde.
Interaktiver Stimmklon-Workflow
Wenn der Benutzer eine Stimmklon-Aktion anfordert (z.B. „Klon meine Stimme als Rick“), muss der Agent die folgenden Schritte ausführen:
- Eine Datei oder Aufnahme vom Benutzer anfordern (mindestens 8, maximal 30 Sekunden, aber das Modell sieht nur die ersten 10).
- Die Audiodatei hochladen via
POST /voicesmit den Feldernname(z.B. „rick“) unddisplay_name(z.B. „Rick“). Das Audio wird verarbeitet und in der Datenbank gespeichert. - Bestätigen, dass die Stimme registriert wurde (
GET /voices). - Die neue Stimme testen mit
speak_url("Hallo, ich bin Rick.", voice="rick"). - Dem Benutzer die URL zur Verfügung stellen oder das Audio über den entsprechenden Kanal abspielen.
Fehlerbehebung
- Synthese schlägt fehl oder hängt: Überprüfe
/healthzauf Engine-Verfügbarkeit. Wenn eine Engine nicht bereit ist, starte ihren Container neu. - Geklonte Stimme klingt falsch: Überprüfe, ob die vibevoice-Engine läuft. Falls nicht, wird der Klon mit reduzierter Qualität von voxcpm bedient.
- Stimme ist nicht die geklonte: Überprüfe das
engine-Feld in der Antwort. Wenn eselevenlabsist, ist der Klon umgangen worden. - Timeout-Fehler: Kürze den Text mit
tts.vox.max_text_lengthoder verwendespeak_urlmit kleineren Blöcken. - Stimmklon-Referenz zu lang: Stelle sicher, dass das Audio nicht länger als 10 Sekunden ist (das Modell ignoriert alles darüber hinaus).