hmisaki/voicebox

Ajouter un moteur TTS

Objectif

Intégrer un nouveau moteur de synthèse vocale dans Voicebox de bout en bout : recherche de dépendances, implémentation du protocole backend, câblage de l'interface utilisateur frontend, regroupement PyInstaller et vérification de la construction figée. L'utilisateur doit seulement tester la version finale localement.

Document de référence

Le guide complet par phase se trouve à docs/content/docs/developer/tts-engines.mdx. Lisez ce fichier dans son intégralité avant de commencer. Il contient :

• Phase 0 : Recherche de dépendances (obligatoire avant d'écrire du code)
• Phase 1 : Implémentation backend (protocole TTSBackend)
• Phase 2 : Intégration des routes et services (généralement aucune modification)
• Phase 3 : Intégration frontend (5 fichiers)
• Phase 4 : Dépendances (requirements.txt, justfile, CI, Docker)
• Phase 5 : Regroupement PyInstaller (build_binary.py + server.py)
• Phase 6 : Contournements courants pour l'amont
• Checklist d'implémentation (barrière entre les phases)

Flux de travail

1. Lire le guide

# Lire le document complet des moteurs TTS
cat docs/content/docs/developer/tts-engines.mdx

Internalisez toutes les phases, en particulier la Phase 0 et la Phase 5. La version v0.2.3 a nécessité trois correctifs parce que la Phase 0 avait été ignorée.

2. Recherche de dépendances (Phase 0)

Clonez la bibliothèque du modèle dans un répertoire temporaire et auditez-la. Ne SAUTEZ PAS cette étape.

mkdir /tmp/engine-research && cd /tmp/engine-research
git clone <url-de-la-bibliothèque-du-modèle>

Exécutez les recherches grep de la Phase 0.2 dans le guide sur le code cloné et ses dépendances transitives. Produisez un audit écrit des dépendances couvrant :

1. Paquets PyPI vs non PyPI
2. Directives PyInstaller nécessaires (--collect-all, --copy-metadata, --hidden-import)
3. Fichiers de données d'exécution à regrouper
4. Chemins de bibliothèques natives nécessitant des surcharges de variables d'environnement dans les constructions figées
5. Monkey-patches nécessaires (torch.load, float64, MPS, jeton HF)
6. Taux d'échantillonnage
7. Méthode de téléchargement du modèle (from_pretrained vs snapshot_download + from_local)

Testez le chargement et la génération du modèle sur CPU dans un environnement virtuel temporaire avant de continuer.

3. Implémenter (Phases 1 à 4)

Suivez les phases du guide dans l'ordre. Fichiers clés à modifier :

Backend (Phase 1) :

• Créez backend/backends/<moteur>_backend.py
• Enregistrez dans backend/backends/__init__.py (ModelConfig + TTS_ENGINES + fabrique)
• Mettez à jour l'expression régulière dans backend/models.py

Frontend (Phase 3) :

• app/src/lib/api/types.ts — type union du moteur
• app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
• app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS, ENGINE_DESCRIPTIONS
• app/src/lib/hooks/useGenerationForm.ts — schéma Zod, correspondance nom-modèle
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

Dépendances (Phase 4) :

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

4. Regroupement PyInstaller (Phase 5)

Enregistrez le moteur dans backend/build_binary.py :

• --hidden-import pour le module backend et le paquet du modèle
• --collect-all pour les paquets utilisant inspect.getsource, transportant des fichiers de données ou des bibliothèques natives
• --copy-metadata pour les paquets utilisant importlib.metadata

Si le moteur a des chemins de données natives, ajoutez os.environ.setdefault() dans backend/server.py à l'intérieur du bloc if getattr(sys, 'frozen', False):.

5. Vérifier en mode développement

just dev

Testez la chaîne complète : téléchargement du modèle → chargement → génération → clonage vocal.

6. Utiliser la checklist

Parcourez la Checklist d'Implémentation en bas de tts-engines.mdx. Chaque élément doit être vérifié avant de remettre la construction à l'utilisateur.

Leçons clés (de v0.2.3)

Ce sont les modes de défaillance les plus courants. La recherche de Phase 0 les détecte tous :

Motif	Symptôme dans la construction figée	Correctif
@typechecked / inspect.getsource()	« could not get source code »	--collect-all <paquet>
Le paquet livre des fichiers de modèle pré-entraînés	FileNotFoundError pour .pth.tar, .yaml	--collect-all <paquet>
Bibliothèque C avec chemins système codés en dur	FileNotFoundError pour /usr/share/...	--collect-all + variable d'environnement dans server.py
importlib.metadata.version()	« No package metadata found »	--copy-metadata <paquet>
torch.load sans map_location	Périphérique CUDA indisponible sur construction CPU	Monkey-patch de torch.load
torch.from_numpy sur données float64	Erreur d'exécution de type incompatible	Convertir avec .float()
token=True dans les appels de téléchargement HF	Échec d'authentification sans jeton HF stocké	Utiliser snapshot_download(token=None) + from_local()

Remarques

• Les couches de routes et de services n'ont aucun point de répartition par moteur. main.py ne nécessite aucune modification.
• Le registre de configuration des modèles dans backends/__init__.py gère automatiquement toute la répartition.
• Utilisez get_torch_device() et model_load_progress() de backends/base.py — ne réimplémentez pas la détection de périphérique ni le suivi de progression.
• Testez toujours avec un cache HuggingFace propre (sans modèles pré-téléchargés depuis le développement).
• Ne Poussez pas et ne créez pas de release. Remettez la construction à l'utilisateur pour des tests locaux.