hmisaki/voicebox

TTS-Engine hinzufügen

Ziel

Eine neue Text-to-Speech-Engine von Anfang bis Ende in Voicebox integrieren: Abhängigkeitsanalyse, Backend-Protokoll-Implementierung, Frontend-UI-Verkabelung, PyInstaller-Bündelung und Build-Überprüfung. Der Nutzer soll nur das finale Build lokal testen müssen.

Referenzdokument

Die vollständige Anleitung mit Phasen befindet sich unter docs/content/docs/developer/tts-engines.mdx. Lies diese Datei vollständig, bevor du beginnst. Sie enthält:

• Phase 0: Abhängigkeitsanalyse (zwingend vor dem Schreiben von Code)
• Phase 1: Backend-Implementierung (TTSBackend-Protokoll)
• Phase 2: Route- 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 Upstream-Workarounds
• Implementierungscheckliste (Übergang zwischen den Phasen)

Arbeitsablauf

1. Lies die Anleitung

# Die vollständige TTS-Engines-Dokumentation lesen
cat docs/content/docs/developer/tts-engines.mdx

Verinnerliche alle Phasen, besonders Phase 0 und Phase 5. Das v0.2.3-Release erforderte drei Patch-Releases, weil Phase 0 übersprungen wurde.

2. Abhängigkeitsanalyse (Phase 0)

Klone die Modellbibliothek in ein temporäres Verzeichnis und prüfe sie. Überspringe dies NICHT.

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

Führe die grep-Suchen aus Phase 0.2 der Anleitung gegen den geklonten Quellcode und seine transitiven Abhängigkeiten aus. Erstelle eine schriftliche Abhängigkeitsanalyse, die Folgendes abdeckt:

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

Teste das Laden und Generieren des Modells auf der CPU in der temporären virtuellen Umgebung, bevor du fortfährst.

3. Implementieren (Phasen 1–4)

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

Backend (Phase 1):

• Erstelle backend/backends/<engine>_backend.py
• Registriere in backend/backends/__init__.py (ModelConfig + TTS_ENGINES + Factory)
• Aktualisiere 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-Ziele)
• .github/workflows/release.yml
• Dockerfile (falls zutreffend)

4. PyInstaller-Bündelung (Phase 5)

Registriere 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üge os.environ.setdefault() in backend/server.py innerhalb des if getattr(sys, 'frozen', False):-Blocks hinzu.

5. Im Entwicklermodus überprüfen

just dev

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

6. Die Checkliste verwenden

Gehe die Implementierungs-Checkliste am Ende von tts-engines.mdx durch. Jeder Punkt muss abgehakt sein, bevor das Build dem Nutzer übergeben wird.

Wichtige Erkenntnisse (aus v0.2.3)

Dies sind die häufigsten Fehlermuster. Die Phase-0-Analyse fängt sie alle ab:

Muster	Symptom im gefrorenen Build	Lösung
@typechecked / inspect.getsource()	„Quellcode konnte nicht abgerufen werden“	--collect-all <paket>
Paket enthält 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 auf CPU-Build nicht verfügbar	torch.load monkey-patching
torch.from_numpy auf float64-Daten	dtype-Konflikt RuntimeError	Auf .float() casten
token=True in HF-Download-Aufrufen	Authentifizierungsfehler ohne gespeicherten HF-Token	snapshot_download(token=None) + from_local() verwenden

Hinweise

• Die Route- und Service-Ebene haben keine engine-spezifischen Dispatch-Punkte. main.py erfordert keine Änderungen.
• Die Modellkonfigurations-Registry in backends/__init__.py übernimmt den gesamten Dispatch automatisch.
• Verwende get_torch_device() und model_load_progress() aus backends/base.py – implementiere keine Geräteerkennung oder Fortschrittsverfolgung neu.
• Teste immer mit einem leeren HuggingFace-Cache (keine zuvor heruntergeladenen Modelle aus der Entwicklung).
• Führe KEINEN Push durch und erstelle KEIN Release. Übergib das Build dem Nutzer zum lokalen Testen.