jamiepine/voicebox

TTS-Engine hinzufügen

Ziel

Eine neue Text-to-Speech-Engine Ende-zu-Ende in Voicebox integrieren: Abhängigkeitsrecherche, Backend-Protokollimplementierung, Frontend-UI-Verkabelung, PyInstaller-Bündelung und Überprüfung des eingefrorenen Builds. Der Benutzer sollte nur den finalen Build lokal testen müssen.

Referenzdokument

Die vollständige phasengestützte Anleitung befindet sich unter docs/content/docs/developer/tts-engines.mdx. Lesen Sie diese Datei vollständig, bevor Sie beginnen. Sie enthält:

• Phase 0: Abhängigkeitsrecherche (vor dem Schreiben von Code obligatorisch)
• Phase 1: Backend-Implementierung (TTSBackend-Protokoll)
• Phase 2: Routen- und Service-Integration (normalerweise keine Änderungen)
• Phase 3: Frontend-Integration (5 Dateien)
• Phase 4: Abhängigkeiten (requirements.txt, justfile, CI, Docker)
• Phase 5: PyInstaller-Bündelung (build_binary.py + server.py)
• Phase 6: Häufige Workarounds für Upstream-Probleme
• Implementierungs-Checkliste (Gate zwischen den Phasen)

Arbeitsablauf

1. Anleitung lesen

# Vollständiges TTS-Engine-Dokument lesen
cat docs/content/docs/developer/tts-engines.mdx

Verinnerlichen Sie alle Phasen, insbesondere Phase 0 und Phase 5. Das v0.2.3-Release umfasste drei Patch-Releases, weil Phase 0 übersprungen wurde.

2. Abhängigkeitsrecherche (Phase 0)

Klonen Sie die Modellbibliothek in ein temporäres Verzeichnis und prüfen Sie sie. Überspringen Sie diesen Schritt NICHT.

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

Führen Sie die grep-Suchen aus Phase 0.2 der Anleitung gegen den geklonten Quellcode und seine transitiven Abhängigkeiten aus. Erstellen Sie eine schriftliche Abhängigkeitsprüfung, die Folgendes abdeckt:

1. PyPI- vs. Nicht-PyPI-Pakete
2. Erforderliche PyInstaller-Direktiven (--collect-all, --copy-metadata, --hidden-import)
3. Laufzeit-Datendateien, die gebündelt werden müssen
4. Native Bibliothekspfade, die in eingefrorenen Builds Umgebungsvariablen-Überschreibungen benötigen
5. Erforderliche Monkey-Patches (torch.load, float64, MPS, HF-Token)
6. Abtastrate
7. Modell-Download-Methode (from_pretrained vs. snapshot_download + from_local)

Testen Sie das Laden und die Generierung des Modells auf der CPU in der Wegwerf-Virtualenv, bevor Sie fortfahren.

3. Implementieren (Phasen 1–4)

Folgen Sie den Phasen der Anleitung der Reihe nach. Wichtige zu ändernde Dateien:

Backend (Phase 1):

• Erstellen Sie backend/backends/<engine>_backend.py
• Registrieren Sie es in backend/backends/__init__.py (ModelConfig + TTS_ENGINES + Factory)
• Aktualisieren Sie den regulären Ausdruck in backend/models.py

Frontend (Phase 3):

• app/src/lib/api/types.ts — Engine-Union-Typ
• app/src/lib/constants/languages.ts — ENGINE_LANGUAGES
• app/src/components/Generation/EngineModelSelector.tsx — ENGINE_OPTIONS, ENGINE_DESCRIPTIONS
• app/src/lib/hooks/useGenerationForm.ts — Zod-Schema, Modellnamen-Zuordnung
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

Abhängigkeiten (Phase 4):

• backend/requirements.txt
• justfile (setup-python, setup-python-release-Targets)
• .github/workflows/release.yml
• Dockerfile (falls zutreffend)

4. PyInstaller-Bündelung (Phase 5)

Registrieren Sie die Engine in backend/build_binary.py:

• --hidden-import für das Backend-Modul und das Modellpaket
• --collect-all für Pakete, die inspect.getsource verwenden, Datendateien versenden oder native Bibliotheken enthalten
• --copy-metadata für Pakete, die importlib.metadata verwenden

Wenn die Engine native Datenpfade hat, fügen Sie os.environ.setdefault() in backend/server.py innerhalb des if getattr(sys, 'frozen', False):-Blocks hinzu.

5. Im Entwicklermodus überprüfen

just dev

Testen Sie die gesamte Kette: Modell-Download → Laden → Generieren → Sprachklonen.

6. Checkliste verwenden

Gehen Sie die Implementierungs-Checkliste am Ende von tts-engines.mdx durch. Jeder Punkt muss abgehakt sein, bevor der Build dem Benutzer übergeben wird.

Wichtige Erkenntnisse (aus v0.2.3)

Dies sind die häufigsten Fehlermodi. Die Phase-0-Recherche erfasst alle:

Muster	Symptom im eingefrorenen Build	Behebung
@typechecked / inspect.getsource()	"Quellcode konnte nicht abgerufen werden"	--collect-all <paket>
Paket versendet vortrainierte Modelldateien	FileNotFoundError für .pth.tar, .yaml	--collect-all <paket>
C-Bibliothek mit fest codierten Systempfaden	FileNotFoundError für /usr/share/...	--collect-all + Umgebungsvariable in server.py
importlib.metadata.version()	"Keine Paketmetadaten gefunden"	--copy-metadata <paket>
torch.load ohne map_location	CUDA-Gerät nicht verfügbar im CPU-Build	Monkey-Patch torch.load
torch.from_numpy auf float64-Daten	dtype-Konflikt RuntimeError	Mit .float() casten
token=True in HF-Download-Aufrufen	Authentifizierungsfehler ohne gespeicherten HF-Token	snapshot_download(token=None) + from_local() verwenden

Hinweise

• Die Routen- und Service-Schichten haben keine pro-Engine-Dispatch-Punkte. main.py benötigt keine Änderungen.
• Die Modellkonfigurationsregistrierung in backends/__init__.py erledigt das gesamte Dispatch automatisch.
• Verwenden Sie get_torch_device() und model_load_progress() aus backends/base.py — implementieren Sie Geräteerkennung oder Fortschrittsverfolgung nicht neu.
• Testen Sie immer mit einem sauberen HuggingFace-Cache (keine bereits heruntergeladenen Modelle aus der Entwicklung).
• Führen Sie KEINEN Push durch und erstellen Sie KEIN Release. Übergeben Sie den Build dem Benutzer zum lokalen Testen.