hmisaki/voicebox

Añadir Motor TTS

Objetivo

Integrar un nuevo motor de texto a voz en Voicebox de extremo a extremo: investigación de dependencias, implementación del protocolo backend, conexión de la interfaz de usuario frontend, empaquetado con PyInstaller y verificación de la compilación congelada. El usuario solo debe probar la compilación final localmente.

Documento de referencia

La guía completa por fases se encuentra en docs/content/docs/developer/tts-engines.mdx. Lee este archivo en su totalidad antes de empezar. Contiene:

• Fase 0: Investigación de dependencias (obligatoria antes de escribir código)
• Fase 1: Implementación del backend (protocolo TTSBackend)
• Fase 2: Integración de rutas y servicios (normalmente sin cambios)
• Fase 3: Integración del frontend (5 archivos)
• Fase 4: Dependencias (requirements.txt, justfile, CI, Docker)
• Fase 5: Empaquetado con PyInstaller (build_binary.py + server.py)
• Fase 6: Soluciones comunes para problemas ascendentes
• Lista de verificación de implementación (puerta entre fases)

Flujo de trabajo

1. Leer la guía

# Lee el documento completo sobre motores TTS
cat docs/content/docs/developer/tts-engines.mdx

Internaliza todas las fases, especialmente la Fase 0 y la Fase 5. El lanzamiento v0.2.3 tuvo tres parches porque se omitió la Fase 0.

2. Investigación de dependencias (Fase 0)

Clona la biblioteca del modelo en un directorio temporal y audítala. NO la omitas.

mkdir /tmp/engine-research && cd /tmp/engine-research
git clone <model-library-url>

Ejecuta las búsquedas grep de la Fase 0.2 de la guía contra el código clonado y sus dependencias transitivas. Genera una auditoría de dependencias por escrito que cubra:

1. Paquetes de PyPI vs no PyPI
2. Directivas de PyInstaller necesarias (--collect-all, --copy-metadata, --hidden-import)
3. Archivos de datos en tiempo de ejecución que deben incluirse
4. Rutas de bibliotecas nativas que necesitan anulaciones de variables de entorno en compilaciones congeladas
5. Parches necesarios (torch.load, float64, MPS, token HF)
6. Frecuencia de muestreo
7. Método de descarga del modelo (from_pretrained vs snapshot_download + from_local)

Prueba la carga y generación del modelo en CPU en el entorno virtual temporal antes de continuar.

3. Implementar (Fases 1–4)

Sigue las fases de la guía en orden. Archivos clave a modificar:

Backend (Fase 1):

• Crear backend/backends/<engine>_backend.py
• Registrar en backend/backends/__init__.py (ModelConfig + TTS_ENGINES + fábrica)
• Actualizar la expresión regular en backend/models.py

Frontend (Fase 3):

• app/src/lib/api/types.ts — tipo unión del motor
• app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
• app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS, ENGINE_DESCRIPTIONS
• app/src/lib/hooks/useGenerationForm.ts — esquema Zod, mapeo de nombres de modelo
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

Dependencias (Fase 4):

• backend/requirements.txt
• justfile (objetivos setup-python, setup-python-release)
• .github/workflows/release.yml
• Dockerfile (si aplica)

4. Empaquetado con PyInstaller (Fase 5)

Registra el motor en backend/build_binary.py:

• --hidden-import para el módulo del backend y el paquete del modelo
• --collect-all para paquetes que usan inspect.getsource, envían archivos de datos o bibliotecas nativas
• --copy-metadata para paquetes que usan importlib.metadata

Si el motor tiene rutas de datos nativas, añade os.environ.setdefault() en backend/server.py dentro del bloque if getattr(sys, 'frozen', False):.

5. Verificar en modo desarrollo

just dev

Prueba la cadena completa: descarga del modelo → carga → generación → clonación de voz.

6. Usar la lista de verificación

Recorre la Lista de Verificación de Implementación al final de tts-engines.mdx. Cada elemento debe estar marcado antes de entregar la compilación al usuario.

Lecciones clave (de v0.2.3)

Estos son los modos de fallo más comunes. La investigación de la Fase 0 los detecta todos:

Patrón	Síntoma en compilación congelada	Solución
@typechecked / inspect.getsource()	"could not get source code"	--collect-all <paquete>
El paquete incluye archivos de modelo preentrenados	FileNotFoundError para .pth.tar, .yaml	--collect-all <paquete>
Biblioteca C con rutas de sistema fijas	FileNotFoundError para /usr/share/...	--collect-all + variable de entorno en server.py
importlib.metadata.version()	"No package metadata found"	--copy-metadata <paquete>
torch.load sin map_location	Dispositivo CUDA no disponible en compilación CPU	Parchear torch.load
torch.from_numpy en datos float64	RuntimeError por tipo de dato incorrecto	Convertir a .float()
token=True en llamadas de descarga HF	Fallo de autenticación sin token HF almacenado	Usar snapshot_download(token=None) + from_local()

Notas

• Las capas de ruta y servicio no tienen puntos de envío por motor. main.py no requiere cambios.
• El registro de configuración de modelos en backends/__init__.py maneja todo el envío automáticamente.
• Usa get_torch_device() y model_load_progress() de backends/base.py — no reimplementes la detección de dispositivos ni el seguimiento de progreso.
• Siempre prueba con una caché de HuggingFace limpia (sin modelos descargados previamente del desarrollo).
• NO hagas push ni crees un lanzamiento. Entrega la compilación al usuario para pruebas locales.