vox-tts
Un servicio TTS autogestionado en https://vox.delo.sh que envuelve VoxCPM2 con un almacén de perfiles de voz respaldado por PostgreSQL y soporte para múltiples motores. Desplegado en ~/code/voxxy (núcleo: compose.yml, motores GPU: compose.engines.yml — ambos contenedores de motores deben estar activos o los clones se degradan silenciosamente, ver más abajo).
Referencia rápida
| Acción | Cómo |
|---|---|
| Síntesis única (bytes WAV en línea) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| Síntesis para entrega a Telegram / navegador / HA / Discord | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| Herramienta MCP: bytes en línea (WAV base64) | speak(text, voice?) |
| Herramienta MCP: URL de entrega (OGG/Opus, listo para Telegram) | speak_url(text, voice?) |
| Herramienta MCP: listar voces | list_voices_tool() |
| Listar voces (HTTP) | GET /voices |
| Añadir una voz | POST /voices (multipart: name, display_name, audio) |
| Clonación interactiva de voz (el usuario dice "clona mi voz como…") | Ver Flujo de trabajo de clonación interactiva de voz más abajo |
| Actualizar un motor (VoxCPM / VibeVoice) | Ver Flujo de trabajo de actualización de motor más abajo |
| Hablar desde un agente Hermes | tts.provider: vox nativo (base de la flota); la flota NO carga el MCP de vox |
| Hablar desde un shell / cualquier agente con terminal | voxxy speak "texto" (ver voxxy speak --help) |
| Registrar con un cliente MCP que no tiene ruta nativa a vox | Servidor MCP en https://vox.delo.sh/mcp/ (la barra inclinada final es obligatoria) |
| Node-RED | node-red-contrib-vox en ~/docker/stacks/utils/vox/node-red-contrib-vox/ |
| Estado de salud + motores | GET /healthz |
La barra inclinada final en /mcp/ es obligatoria. Sin ella, FastAPI redirige con 307 y HTTPX pierde el cuerpo POST.
speak vs speak_url: elige el correcto
| Si el audio será... | Usa | Por qué |
|---|---|---|
| Enviado a Telegram / Discord / Slack | speak_url | Las APIs del canal aceptan una URL; sus servidores la obtienen. Cero hinchazón de bytes en el cable del agente. |
Canalizado a una etiqueta <audio> del navegador | speak_url | Los navegadores transmiten URLs; sin ida y vuelta base64. |
Entregado a Home Assistant media_player.play_media | speak_url | HA quiere una URL para media_content_id. |
| Procesado en línea por el agente (unir, analizar, repetir) | speak | Los bytes ya están locales; una obtención de URL añadiría un salto. |
| Escrito a un archivo local en un script de shell | cualquiera | speak_url + curl -o es más fácil que base64 + base64 -d. |
Por defecto, usa speak_url. No le cuesta tokens al agente (la respuesta es un JSON pequeño) y funciona en todas las superficies de entrega excepto el procesamiento bruto de bytes en línea.
Respuesta de motor
GET /healthz informa qué motores están registrados y si cada uno está disponible:
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
El orquestador los prueba en orden. Cada respuesta speak_url / speak incluye engine: "voxcpm" o engine: "elevenlabs" para que puedas detectar cuándo se activó la respuesta. ElevenLabs se desactiva automáticamente cuando ELEVENLABS_API_KEY no está configurada.
La asignación por voz de ElevenLabs reside en la columna voices.elevenlabs_voice_id. NULL usa el valor predeterminado global (ELEVENLABS_DEFAULT_VOICE, Adam por defecto).
Las voces clonadas están vinculadas al motor. Una voz clonada mediante POST /voices almacena su referencia en vibevoice_ref_path y es servida primero por el motor vibevoice (enrutamiento preferred por solicitud en app/engines.py; todo lo demás sigue el orden VOX_ENGINES, voxcpm primero). Si vibevoice está caído, voxcpm aún recibe el clip de referencia — app/voices.py:46-48 usa wav_path para cualquier motor sin una anulación específica — por lo que el clon se degrada, no se borra. El síntoma es una lectura reconocible pero extraña, no una voz desconocida. Solución: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice, luego confirma "name":"vibevoice","ready":true en /healthz.
El que reemplaza la voz por completo es la respuesta de ElevenLabs: si ambos motores GPU están caídos y ELEVENLABS_API_KEY está configurada, vox responde 200 con la voz de un desconocido, registrando vox: voice clone BYPASSED, y lo entrega de todos modos. Revisa el campo engine en cada síntesis clonada — vibevoice o voxcpm es el clon, elevenlabs no es tu voz.
El presupuesto de referencia es de 10 segundos, no 30. Dos límites diferentes se acumulan, y solo el segundo importa. POST /voices recorta la ingesta a VOX_REF_AUDIO_MAX_SECONDS = 30s (compose.yml:16, aplicado en app/main.py:578-584, manteniendo los primeros 30s). Pero el contenedor vibevoice establece la misma variable en 10 (compose.engines.yml:69), y engines/vibevoice/engine/synth.py:183,208 recarga la referencia con duration=10.0. Su /healthz lo dice directamente: "max_ref_seconds": 10.0. Por lo tanto, los segundos 10–30 de cualquier clip de referencia se almacenan, se respaldan y nunca los ve el modelo. Escribe pasajes de clonación para 8–10 segundos limpios y pon lo mejor, el discurso más neutral primero; todo lo demás después es peso muerto.
Procedimientos detallados
Lee flujos de trabajo de voz e integración para la implementación o diagnóstico relevante. La clonación de voz y la entrega externa requieren que el usuario solicite esas acciones.
Hoja de trucos de valores predeterminados
| Parámetro | Valor predeterminado | Notas |
|---|---|---|
cfg | 2.0 | Guía libre de clasificador; mayor = más fiel, menos variación |
steps | 10 | Pasos de difusión; 4-6 para velocidad, 15-20 para máxima calidad |
normalize | false | Normalización de texto (números → palabras, etc.) |
denoise | false | Campo muerto. Declarado en app/main.py:98, no se lee en ninguna parte; POST /voices no tiene ningún parámetro denoise. Limpia el audio antes de subirlo. |
| TTL de caché (URLs de audio) | 3600s | Variable de entorno VOX_AUDIO_TTL_SECONDS; 1h es suficiente para Telegram |
| Voz de respaldo (ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | Variable de entorno ELEVENLABS_DEFAULT_VOICE |
La síntesis se ejecuta a aproximadamente 21 caracteres por segundo en una RTX 3090 con VOX_OPTIMIZE=1 — medido, no estimado: una línea de 60 caracteres toma ~2s, una línea de 1.665 caracteres toma ~35s. Presupuesta por longitud, no por el titular de 2s. La primera llamada después de reiniciar un contenedor añade ~15s (compilación JIT). La transcodificación OGG/Opus añade <100ms a través de ffmpeg.
Esto importa para cualquier llamante con un tiempo de espera. El plugin TTS vox de Hermes codifica un tiempo de espera httpx de 60s (plugins/tts/vox/__init__.py:29,316) e ignora tts.vox.timeout, por lo que un solo fragmento de más de aproximadamente 2.500 caracteres falla directamente. Limítalo con tts.vox.max_text_length (leído en tools/tts_tool.py:436-441), que divide en fragmentos en lugar de fallar.
Flujo de trabajo de actualización de motor
La topología de tres contenedores desacopla la orquestación central (voxxy-core, contenedor vox, solo CPU) de los motores laterales GPU (voxxy-engine-voxcpm, voxxy-engine-vibevoice). Cada contenedor de motor mantiene sus propios pyproject.toml, uv.lock y Dockerfile en engines/<name>/.
Procedimiento de actualización paso a paso
1. Descubrimiento de versiones y auditoría de tiempo de ejecución
- Lanzamientos ascendentes: Revisa PyPI y los lanzamientos de GitHub:
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - Versión del contenedor en ejecución: Revisa la versión del paquete instalada a través de
importlib.metadata:(Nunca usesdocker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__; el módulo no lo define y lanzaAttributeError). - Pesos del modelo en Hugging Face: Comprueba si la instantánea de los pesos del modelo se ha actualizado:
Las actualizaciones de paquetes (código de inferencia, decodificadores VAE de transmisión, manejo de dispositivos) son distintas de las revisiones de los pesos del modelo.cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. Incremento de dependencias y actualización del archivo de bloqueo
- Incrementa el pin de versión en
engines/<name>/pyproject.toml(p. ej.,voxcpm==2.0.3). - Vuelve a bloquear las dependencias con uv:
cd engines/voxcpm && uv lock - Revisa el diff (
git diff engines/voxcpm/uv.lock) para asegurarte de que PyTorch y torchaudio permanezcan fijados al índice explícitopytorch-cu124y no se desvíen a las ruedas CPU de PyPI.
3. Reconstruir la imagen del contenedor del motor
Reconstruye la imagen del motor a través de compose:
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# O a través del alias mise:
mise run build:voxcpm
El Dockerfile aprovisiona Python 3.12 a través de uv y ejecuta uv sync --frozen --no-install-project en /opt/venv.
4. Recrear el contenedor del motor con el perfil de compose
Los contenedores de motores se definen con perfiles de compose en compose.engines.yml (profiles: ["voxcpm"] / profiles: ["vibevoice"]). Debes pasar --profile o compose ignorará el servicio:
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
Verifica que el contenedor haya recogido la nueva versión:
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. Verificación y pruebas de humo
- Inicio del contenedor: Inspecciona los registros para una carga exitosa del modelo:
docker logs --tail 30 voxxy-engine-voxcpm # Busca: "Loaded VoxCPM2Model" y "Application startup complete." - Healthz del motor:
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # Espera: {"engine":"voxcpm","ready":true,"model_loaded":true,...} - Prueba de síntesis directa: Envía un payload de síntesis sin procesar directamente desde el contenedor central
voxa través de la red Docker:docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \ -H 'content-type: application/json' \ -d '{"text":"Probando síntesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}' - Verificación de clonación de voz: Prueba con una muestra de audio de referencia (
/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": "Prueba de clon.", "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"))) ' - Pruebas de contrato y CLI:
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. Entrega
Confirma tanto pyproject.toml como uv.lock en el directorio del motor:
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): actualizar voxcpm a <versión>"
git push origin main
Lecciones aprendidas y peculiaridades del motor
- Inspección de la versión del paquete
voxcpm:voxcpmNO expone__version__. Llamar apython -c "import voxcpm; print(voxcpm.__version__)"lanzaAttributeError. Siempre inspecciona los metadatos instalados conimportlib.metadata.version('voxcpm'). - Requisito de perfiles de compose: En
compose.engines.yml, cada motor tiene un perfil (profiles: ["voxcpm"]). Si ejecutasdocker compose up voxxy-engine-voxcpmsin--profile voxcpm, Docker Compose omitirá silenciosamente el servicio. - Los motores en espera se pueden probar directamente: Los motores locales en una sola tarjeta GPU son mutuamente excluyentes (VoxCPM ~5 GB VRAM, VibeVoice ~7,5 GB VRAM). Incluso si un motor está en
standbyenvoxxy daemon status/.voxxy.state.json, su contenedor permanece en ejecución y saludable en la red Docker interna (http://voxxy-engine-<name>:8000). Puedes probarlo directamente a través de curl desdevoxsin cambiar el motor activo. - Ubicación del conjunto de pruebas de pytest: Ejecutar
pytestdesde la raíz del repositorio falla porqueplugins/tts/vox/es un complemento de Hermes que esperaagent.tts_provider...