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. ガイドを読む
# TTSエンジンのドキュメント全文を読む
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 検索を、クローン元のソースとその推移的依存関係に対して実行します。以下の項目をカバーする依存関係監査レポートを作成します。
- PyPI パッケージと非 PyPI パッケージ
- 必要な PyInstaller ディレクティブ（
--collect-all、--copy-metadata、--hidden-import） - バンドルが必要なランタイムデータファイル
- 凍結ビルドで環境変数のオーバーライドが必要なネイティブライブラリのパス
- 必要なモンキーパッチ（
torch.load、float64、MPS、HF トークン） - サンプルレート
- モデルのダウンロード方法（
from_pretrainedとsnapshot_download+from_local）
使い捨ての仮想環境で、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_LANGUAGESapp/src/components/Generation/EngineModelSelector.tsx— ENGINE_OPTIONS、ENGINE_DESCRIPTIONSapp/src/lib/hooks/useGenerationForm.ts— Zod スキーマ、モデル名マッピングapp/src/components/ServerSettings/ModelManagement.tsx— MODEL_DESCRIPTIONS
依存関係（フェーズ4）:
backend/requirements.txtjustfile（setup-python、setup-python-release ターゲット）.github/workflows/release.ymlDockerfile（該当する場合）
4. PyInstaller によるバンドル（フェーズ5）
backend/build_binary.py にエンジンを登録します。
--hidden-import：バックエンドモジュールとモデルパッケージ用--collect-all：inspect.getsourceを使用するパッケージ、データファイルを出荷するパッケージ、またはネイティブライブラリ用--copy-metadata：importlib.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() | 「ソースコードを取得できません」 | --collect-all <package> |
| パッケージが学習済みモデルファイルを同梱 | .pth.tar、.yaml で FileNotFoundError | --collect-all <package> |
| システムパスがハードコードされたCライブラリ | /usr/share/... で FileNotFoundError | --collect-all + server.py の環境変数 |
importlib.metadata.version() | 「パッケージのメタデータが見つかりません」 | --copy-metadata <package> |
map_location なしの torch.load | CPUビルドでCUDAデバイスが利用不可 | torch.load をモンキーパッチ |
float64データに対する torch.from_numpy | データ型不一致 RuntimeError | .float() にキャスト |
HFダウンロード呼び出しでの token=True | HFトークンが保存されていない場合に認証失敗 | snapshot_download(token=None) + from_local() を使用 |
注意事項
- ルートとサービスのレイヤーにはエンジンごとのディスパッチポイントはありません。
main.pyへの変更は不要です。 backends/__init__.pyのモデル設定レジストリがすべてのディスパッチを自動的に処理します。backend/base.pyのget_torch_device()とmodel_load_progress()を使用してください。デバイス検出や進行状況追跡を再実装しないでください。- 必ずクリーンなHuggingFaceキャッシュ（開発で事前にダウンロードしたモデルがない状態）でテストしてください。
- プッシュやリリースは作成しないでください。ビルドをユーザーに引き渡し、ローカルでテストしてもらってください。