add-tts-engine

TTS エンジンを追加する

目標

新しいテキスト読み上げエンジンを Voicebox にエンドツーエンドで統合します。依存関係の調査、バックエンドプロトコルの実装、フロントエンド UI の接続、PyInstaller によるバンドル、およびフリーズビルドの検証が含まれます。ユーザーは最終ビルドをローカルでテストするだけで済むようにします。

参照ドキュメント

段階的な完全ガイドは docs/content/docs/developer/tts-engines.mdx にあります。作業を開始する前にこのファイルを全体にわたって読んでください。 このファイルには以下が含まれています。

• フェーズ 0: 依存関係の調査 (コードを書く前に必須)
• フェーズ 1: バックエンドの実装 (TTSBackend プロトコル)
• フェーズ 2: ルートとサービスの統合 (通常は変更ゼロ)
• フェーズ 3: フロントエンドの統合 (5 ファイル)
• フェーズ 4: 依存関係 (requirements.txt、justfile、CI、Docker)
• フェーズ 5: PyInstaller によるバンドル (build_binary.py + server.py)
• フェーズ 6: 一般的な上流のワークアラウンド
• 実装チェックリスト (フェーズ間のゲート)

ワークフロー

1. ガイドを読む

# Read the full TTS engines doc
cat docs/content/docs/developer/tts-engines.mdx

すべてのフェーズ、特にフェーズ 0 とフェーズ 5 をしっかり理解してください。v0.2.3 リリースでは、フェーズ 0 を省略したために 3 回のパッチリリースが必要になりました。

2. 依存関係の調査 (フェーズ 0)

モデルライブラリを一時ディレクトリにクローンして監査します。これを省略しないでください。

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

ガイドのフェーズ 0.2 にある grep 検索を、クローンしたソースとその推移的依存関係に対して実行します。以下を網羅した依存関係監査を文書として作成します。

1. PyPI パッケージと非 PyPI パッケージ
2. 必要な PyInstaller ディレクティブ (--collect-all、--copy-metadata、--hidden-import)
3. バンドルする必要がある実行時データファイル
4. フリーズビルドで環境変数の上書きが必要なネイティブライブラリのパス
5. 必要なモンキーパッチ (torch.load、float64、MPS、HF トークン)
6. サンプルレート
7. モデルのダウンロード方法 (from_pretrained と snapshot_download + from_local)

先に進む前に、使い捨ての venv で CPU 上でのモデルの読み込みと生成をテストしてください。

3. 実装 (フェーズ 1〜4)

ガイドのフェーズに従って順番に進めます。変更する主なファイルは次のとおりです。

バックエンド (フェーズ 1):

• backend/backends/<engine>_backend.py を作成
• backend/backends/__init__.py に登録 (ModelConfig + TTS_ENGINES + ファクトリ)
• backend/models.py の正規表現を更新

フロントエンド (フェーズ 3):

• app/src/lib/api/types.ts — エンジンのユニオン型
• 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 スキーマ、モデル名のマッピング
• app/src/components/ServerSettings/ModelManagement.tsx — MODEL_DESCRIPTIONS

依存関係 (フェーズ 4):

• backend/requirements.txt
• justfile (setup-python、setup-python-release ターゲット)
• .github/workflows/release.yml
• Dockerfile (該当する場合)

4. PyInstaller によるバンドル (フェーズ 5)

backend/build_binary.py にエンジンを登録します。

• バックエンドモジュールとモデルパッケージに対する --hidden-import
• inspect.getsource を使用するパッケージ、データファイルを同梱するパッケージ、またはネイティブライブラリに対する --collect-all
• importlib.metadata を使用するパッケージに対する --copy-metadata

エンジンにネイティブデータパスがある場合は、backend/server.py の if getattr(sys, 'frozen', False): ブロック内に os.environ.setdefault() を追加します。

5. 開発モードで検証する

just dev

モデルのダウンロード → 読み込み → 生成 → 音声クローニングという一連の流れ全体をテストします。

6. チェックリストを使用する

tts-engines.mdx の末尾にある実装チェックリストを確認しながら進めます。ビルドをユーザーに渡す前に、すべての項目がチェックされている必要があります。

主な教訓 (v0.2.3 より)

これらは最も一般的な失敗モードです。フェーズ 0 の調査ですべてを捕捉できます:

パターン	フリーズビルドでの症状	修正
@typechecked / inspect.getsource()	「could not get source code」	--collect-all <package>
パッケージが学習済みモデルファイルを同梱	.pth.tar、.yaml の FileNotFoundError	--collect-all <package>
システムパスがハードコードされた C ライブラリ	/usr/share/... の FileNotFoundError	--collect-all + server.py 内の環境変数
importlib.metadata.version()	「No package metadata found」	--copy-metadata <package>
map_location なしの torch.load	CPU ビルドで CUDA デバイスが利用不可	torch.load をモンキーパッチ
float64 データに対する torch.from_numpy	dtype 不一致の RuntimeError	.float() にキャスト
HF ダウンロード呼び出しでの token=True	保存された HF トークンがない場合の認証失敗	snapshot_download(token=None) + from_local() を使用

注意事項

• ルート層とサービス層には、エンジンごとのディスパッチポイントが一切ありません。main.py は変更不要です。
• backends/__init__.py のモデル設定レジストリが、すべてのディスパッチを自動的に処理します。
• backends/base.py の get_torch_device() と model_load_progress() を使用してください — デバイス検出や進捗トラッキングを再実装しないでください。
• 常にクリーンな HuggingFace キャッシュ (開発時に事前ダウンロードされたモデルがない状態) でテストしてください。
• プッシュやリリースの作成を行わないでください。ビルドはユーザーに渡してローカルでテストしてもらってください。