hmisaki/voicebox - TTSエンジン追加スキル

TTSエンジンの追加

目標

新しいテキスト音声合成エンジンをVoiceboxにエンドツーエンドで統合する：依存関係調査、バックエンドプロトコル実装、フロントエンドUI配線、PyInstallerバンドル、 frozenビルド検証。ユーザーは最終ビルドをローカルでテストするだけで良い状態にします。

リファレンスドキュメント

完全なフェーズガイドは 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検索を、クローンしたソースとその推移的依存関係に対して実行します。以下の内容をカバーする文書化された依存関係監査を作成します：

1. PyPIパッケージと非PyPIパッケージ
2. 必要なPyInstallerディレクティブ（--collect-all、--copy-metadata、--hidden-import）
3. バンドルする必要があるランタイムデータファイル
4. frozenビルドで環境変数のオーバーライドが必要なネイティブライブラリパス
5. 必要なモンキーパッチ（torch.load、float64、MPS、HFトークン）
6. サンプルレート
7. モデルダウンロード方法（from_pretrained vs 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：バックエンドモジュールとモデルパッケージ用
• --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の調査ですべてを捕捉できます：

パターン	frozenビルドでの症状	修正方法
@typechecked / inspect.getsource()	"could not get source code"	--collect-all <package>
パッケージが事前学習済みモデルファイルを同梱	FileNotFoundError（.pth.tar、.yaml）	--collect-all <package>
ハードコードされたシステムパスを持つCライブラリ	FileNotFoundError（/usr/share/...）	--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	データ型不一致の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キャッシュ（開発中に事前ダウンロードしたモデルがない状態）でテストしてください。
• プッシュやリリース作成は行わないでください。ビルドをユーザーに渡してローカルテストを依頼してください。