vox-tts
Un service TTS auto-hébergé à https://vox.delo.sh encapsulant VoxCPM2 avec un stockage de profils vocaux basé sur Postgres et la prise en charge de plusieurs moteurs. Déployé dans ~/code/voxxy (cœur : compose.yml, moteurs GPU : compose.engines.yml — les deux conteneurs de moteurs doivent être actifs, sinon les clones se dégradent silencieusement, voir ci-dessous).
Référence rapide
| Action | Comment |
|---|---|
| Synthèse ponctuelle (octets WAV en ligne) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| Synthèse pour livraison à Telegram / navigateur / HA / Discord | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| Outil MCP : octets en ligne (WAV en base64) | speak(text, voice?) |
| Outil MCP : URL de livraison (OGG/Opus, prêt pour Telegram) | speak_url(text, voice?) |
| Outil MCP : lister les voix | list_voices_tool() |
| Lister les voix (HTTP) | GET /voices |
| Ajouter une voix | POST /voices (multipart : name, display_name, audio) |
| Clonage vocal interactif (l'utilisateur dit « clone ma voix en tant que... ») | Voir Flux de clonage vocal interactif ci-dessous |
| Mettre à niveau un moteur (VoxCPM / VibeVoice) | Voir Flux de mise à niveau du moteur ci-dessous |
| Parler depuis un agent Hermes | tts.provider: vox natif (base de la flotte) ; la flotte NE charge PAS le MCP vox |
| Parler depuis un shell / tout agent avec un terminal | voxxy speak "texte" (voir voxxy speak --help) |
| S'enregistrer auprès d'un client MCP sans chemin vox natif | Serveur MCP à https://vox.delo.sh/mcp/ (barre oblique finale requise) |
| Node-RED | node-red-contrib-vox à ~/docker/stacks/utils/vox/node-red-contrib-vox/ |
| Santé + état du moteur | GET /healthz |
La barre oblique finale sur /mcp/ est obligatoire. Sans elle, FastAPI redirige avec un code 307 et HTTPX perd le corps de la requête POST.
speak vs speak_url : choisir le bon outil
| Si l'audio sera... | Utiliser | Pourquoi |
|---|---|---|
| Envoyé à Telegram / Discord / Slack | speak_url | Les API des canaux acceptent une URL ; leurs serveurs la récupèrent. Zéro gonflement d'octets sur le fil de l'agent. |
Redirigé vers une balise <audio> du navigateur | speak_url | Les navigateurs diffusent des URL ; pas d'aller-retour en base64. |
Transmis à media_player.play_media de Home Assistant | speak_url | HA veut une URL pour media_content_id. |
| Traité en ligne par l'agent (assemblage, analyse, boucle) | speak | Les octets sont déjà locaux ; une récupération d'URL ajouterait un saut. |
| Écrit dans un fichier local dans un script shell | les deux | speak_url + curl -o est plus facile que base64 + base64 -d. |
Par défaut, utilisez speak_url. Cela ne coûte rien à l'agent en tokens (la réponse est un petit JSON) et fonctionne sur toutes les surfaces de livraison, sauf le traitement brut d'octets en ligne.
Basculement du moteur
GET /healthz signale quels moteurs sont enregistrés et si chacun est disponible :
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
L'orchestrateur les essaie dans l'ordre. Chaque réponse speak_url / speak inclut engine: "voxcpm" ou engine: "elevenlabs" afin que vous puissiez détecter quand le basculement a eu lieu. ElevenLabs se désactive automatiquement lorsque ELEVENLABS_API_KEY n'est pas défini.
Le mappage par voix d'ElevenLabs se trouve dans la colonne voices.elevenlabs_voice_id. NULL revient à la valeur par défaut globale (ELEVENLABS_DEFAULT_VOICE, Adam par défaut).
Les voix clonées sont liées au moteur. Une voix clonée via POST /voices stocke sa référence dans vibevoice_ref_path et est servie en priorité par le moteur vibevoice (routage preferred par requête dans app/engines.py ; tout le reste suit l'ordre VOX_ENGINES, voxcpm en premier). Si vibevoice est hors service, voxcpm reçoit toujours le clip de référence — app/voices.py:46-48 revient à wav_path pour tout moteur sans remplacement spécifique — donc le clone se dégrade, il n'est pas effacé. Le symptôme est une lecture reconnaissable mais erronée, pas un inconnu. Correctif : docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, puis confirmez "name":"vibevoice","ready":true dans /healthz.
Celui qui remplace complètement la voix est le basculement ElevenLabs : si les deux moteurs GPU sont hors service et que ELEVENLABS_API_KEY est définie, vox répond 200 avec une voix étrangère, en enregistrant vox: voice clone BYPASSED, et la livre quand même. Vérifiez le champ engine sur chaque synthèse clonée — vibevoice ou voxcpm est le clone, elevenlabs n'est pas votre voix.
Le budget de référence est de 10 secondes, pas 30. Deux limitations différentes s'empilent, et seule la seconde compte. POST /voices limite l'ingestion à VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, appliquée à app/main.py:578-584, en gardant les premières 30s). Mais le conteneur vibevoice définit la même variable à 10 (compose.engines.yml:69), et engines/vibevoice/engine/synth.py:183,208 recharge la référence avec duration=10.0. Son /healthz le dit directement : "max_ref_seconds": 10.0. Ainsi, les secondes 10 à 30 de tout clip de référence sont stockées, sauvegardées, mais jamais vues par le modèle. Rédigez les passages de clonage pour 8 à 10 secondes propres et mettez le discours le meilleur et le plus neutre en premier — tout ce qui suit est du poids mort.
Procédures détaillées
Consultez flux de travail vocal et d'intégration pour l'implémentation ou le diagnostic correspondant. Le clonage vocal et la livraison externe nécessitent que l'utilisateur demande ces actions.
Aide-mémoire des valeurs par défaut
| Paramètre | Valeur par défaut | Remarques |
|---|---|---|
cfg | 2.0 | Guidage sans classifieur ; plus élevé = plus fidèle, moins de variation |
steps | 10 | Étapes de diffusion ; 4-6 pour la vitesse, 15-20 pour une qualité maximale |
normalize | false | Normalisation du texte (chiffres → mots, etc.) |
denoise | false | Champ mort. Déclaré à app/main.py:98, lu nulle part ; POST /voices n'a aucun paramètre denoise du tout. Nettoyez l'audio avant le téléchargement à la place. |
| TTL du cache (URL audio) | 3600s | Variable d'env VOX_AUDIO_TTL_SECONDS ; 1h est largement suffisant pour Telegram |
| Voix de repli (ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | Variable d'env ELEVENLABS_DEFAULT_VOICE |
La synthèse s'exécute à environ 21 caractères par seconde sur un RTX 3090 avec VOX_OPTIMIZE=1 — mesuré, pas estimé : une ligne de 60 caractères prend ~2s, une ligne de 1 665 caractères prend ~35s. Budget par longueur, pas par l'annonce de 2s. Le premier appel après un redémarrage du conteneur ajoute ~15s (compilation JIT). Le transcodage OGG/Opus ajoute <100ms via ffmpeg.
Ceci est important pour tout appelant avec un délai d'attente. Le plugin TTS vox d'Hermes code en dur un délai d'attente httpx de 60s (plugins/tts/vox/__init__.py:29,316) et ignore tts.vox.timeout, donc un seul bloc dépassant environ 2 500 caractères échoue complètement. Limitez-le avec tts.vox.max_text_length (lu à tools/tts_tool.py:436-441), qui divise en blocs au lieu d'échouer.
Flux de mise à niveau du moteur
La topologie à trois conteneurs découple l'orchestration centrale (voxxy-core, conteneur vox, uniquement CPU) des moteurs side-car liés au GPU (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Chaque conteneur de moteur maintient son propre pyproject.toml, uv.lock et Dockerfile sous engines/<name>/.
Procédure de mise à niveau étape par étape
1. Découverte de version et audit d'exécution
- Versions en amont : Vérifiez PyPI et les publications GitHub :
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - Version du conteneur en cours d'exécution : Vérifiez la version du paquet installé via
importlib.metadata:(N'utilisez jamaisdocker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__; le module ne le définit pas et lèveAttributeError). - Poids du modèle sur Hugging Face : Vérifiez si l'instantané des poids du modèle a été mis à jour :
Les mises à jour de paquets (code d'inférence, décodeurs VAE de diffusion, gestion des périphériques) sont distinctes des révisions des poids du modèle.cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. Mise à jour des dépendances et mise à jour du fichier de verrouillage
- Mettez à jour le verrouillage de version dans
engines/<name>/pyproject.toml(par exemplevoxcpm==2.0.3). - Re-verrouillez les dépendances avec uv :
cd engines/voxcpm && uv lock - Examinez le diff (
git diff engines/voxcpm/uv.lock) pour vous assurer que PyTorch et torchaudio restent épinglés à l'index explicitepytorch-cu124et ne dérivent pas vers les wheels CPU PyPI.
3. Reconstruire l'image du conteneur du moteur
Reconstruisez l'image du moteur via compose :
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# Ou via l'alias mise :
mise run build:voxcpm
Le Dockerfile provisionne Python 3.12 via uv et exécute uv sync --frozen --no-install-project dans /opt/venv.
4. Recréer le conteneur du moteur avec le profil compose
Les conteneurs de moteur sont définis avec des profils compose dans compose.engines.yml (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Vous devez passer --profile sinon compose ignorera le service :
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
Vérifiez que le conteneur a bien pris la nouvelle version :
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. Vérification et test de validation
- Démarrage du conteneur : Inspectez les logs pour un chargement réussi du modèle :
docker logs --tail 30 voxxy-engine-voxcpm # Recherchez : "Loaded VoxCPM2Model" et "Application startup complete." - Healthz du moteur :
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # Attend : {"engine":"voxcpm","ready":true,"model_loaded":true,...} - Test de synthèse directe : Envoyez une charge utile de synthèse brute directement depuis le conteneur central
voxvia le réseau Docker :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)}' - Vérification du clonage vocal : Testez avec un échantillon audio de référence (
/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"))) ' - Tests de contrat et CLI :
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. Livraison
Validez à la fois pyproject.toml et uv.lock dans le répertoire du moteur :
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main
Leçons apprises et pièges du moteur
- Inspection de version du paquet
voxcpm:voxcpmn'expose PAS__version__. Appelerpython -c "import voxcpm; print(voxcpm.__version__)"lèveAttributeError. Inspectez toujours les métadonnées installées avecimportlib.metadata.version('voxcpm'). - Exigence des profils Compose : Dans
compose.engines.yml, chaque moteur a un profil (profiles: ["voxcpm"]). Si vous exécutezdocker compose up voxxy-engine-voxcpmsans--profile voxcpm, Docker Compose ignorera silencieusement le service. - Les moteurs en veille sont directement testables : Les moteurs locaux sur une seule carte GPU s'excluent mutuellement (VoxCPM ~5 Go VRAM, VibeVoice ~7,5 Go VRAM). Même si un moteur est en
standbydansvoxxy daemon status/.voxxy.state.json, son conteneur reste en cours d'exécution et sain sur le réseau Docker interne (http://voxxy-engine-<name>:8000). Vous pouvez le tester directement via curl depuisvoxsans changer le moteur actif. - Emplacement de la suite de tests Pytest : Exécuter
pytestdepuis la racine du dépôt échoue carplugins/tts/vox/est un plugin Hermes s'attendant à unagent.tts_provider... [tronqué pour la traduction]