vox-tts は何をしますか?
https://vox.delo.sh でホストされているセルフホスト型TTSサービスです。VoxCPM2をラップし、PostgreSQLでバックアップされた音声プロファイルストアと複数のエンジンをサポートします。~/code/voxxy にデプロイされています(コア: compose.yml、GPUエンジン: compose.engines.yml — 両方のエンジンコンテナが起動していないとクローンがサイレントに品質低下します。以下を参照)。
クイックリファレンス
| アクション | 方法 |
|---|---|
| 単発の音声合成(インラインWAVバイト) | POST /synthesize { text, voice?, cfg?, steps? } → audio/wav |
| Telegram / ブラウザ / HA / Discord へ配信するための音声合成 | POST /synthesize-url → {audio_url, engine, duration_s, bytes} |
| MCPツール: インラインバイト(base64 WAV) | speak(text, voice?) |
| MCPツール: 配信URL(OGG/Opus、Telegram対応) | speak_url(text, voice?) |
| MCPツール: 音声一覧表示 | list_voices_tool() |
| 音声一覧表示(HTTP) | GET /voices |
| 音声の追加 | POST /voices(multipart: name, display_name, audio) |
| インタラクティブな音声クローン作成(ユーザーが「私の声をクローンして…」と言った場合) | 以下のインタラクティブな音声クローン作成ワークフローを参照 |
| エンジンのアップグレード(VoxCPM / VibeVoice) | 以下のエンジンアップグレードワークフローを参照 |
| Hermesエージェントからの音声出力 | ネイティブ tts.provider: vox(fleet base); fleetはvox MCPをロードしません |
| シェル / ターミナルを持つ任意のエージェントからの音声出力 | voxxy speak "テキスト"(voxxy speak --help を参照) |
| ネイティブなvoxパスを持たないMCPクライアントへの登録 | https://vox.delo.sh/mcp/ のMCPサーバー(末尾スラッシュ必須) |
| Node-RED | ~/docker/stacks/utils/vox/node-red-contrib-vox/ の node-red-contrib-vox |
| ヘルス + エンジンステータス | GET /healthz |
/mcp/ の末尾スラッシュは必須です。 ない場合、FastAPIが307リダイレクトし、HTTPXがPOSTボディをドロップします。
speak と speak_url: 適切な方を選ぶ
| 音声が... | 使用するもの | 理由 |
|---|---|---|
| Telegram / Discord / Slack に送信される | speak_url | チャネルAPIはURLを受け付けます。そのサーバーがフェッチします。エージェントワイヤー上でのバイト増加がゼロです。 |
ブラウザの <audio> タグにパイプされる | speak_url | ブラウザはURLをストリーミングします。base64のラウンドトリップがありません。 |
Home Assistant の media_player.play_media に渡される | speak_url | HAは media_content_id にURLを必要とします。 |
| エージェントによってインライン処理される(結合、分析、ループ) | speak | バイトはすでにローカルにあります。URLフェッチはホップを追加します。 |
| シェルスクリプトでローカルファイルに書き込まれる | どちらでも | speak_url + curl -o は base64 + base64 -d より簡単です。 |
デフォルトで speak_url を使用してください。 エージェントのトークンコストはゼロ(応答は小さなJSON)であり、生のインラインバイト処理を除くすべての配信面で機能します。
エンジンフォールバック
GET /healthz は、どのエンジンが登録されていて、それぞれが利用可能かを報告します。
{
"status": "ok",
"model_loaded": true,
"engines": [
{ "name": "voxcpm", "available": true },
{ "name": "elevenlabs", "available": true }
]
}
オーケストレーターは順番に試行します。すべての speak_url / speak 応答には engine: "voxcpm" または engine: "elevenlabs" が含まれているため、フォールバックがいつ発生したかを検出できます。ElevenLabsは ELEVENLABS_API_KEY が設定されていない場合、自動的に無効になります。
音声ごとのElevenLabsマッピングは voices.elevenlabs_voice_id カラムにあります。NULLの場合はグローバルデフォルト(ELEVENLABS_DEFAULT_VOICE、デフォルトはAdam)にフォールバックします。
クローンされた音声はエンジンにバインドされています。 POST /voices でクローンされた音声はその参照を vibevoice_ref_path に保存し、最初に vibevoice エンジンによって処理されます(リクエストごとの preferred ルーティングは app/engines.py にあり、その他は VOX_ENGINES の順序に従い、最初にvoxcpm)。vibevoiceがダウンしている場合、voxcpmは依然として参照クリップを受け取ります — app/voices.py:46-48 は特定のオーバーライドがないエンジンに対して wav_path にフォールバックします — したがって、クローンは品質が低下しますが、消去されません。症状は、認識できるものの異なる読み上げであり、見知らぬ声ではありません。修正: docker compose -f ~/code/voxxy/compose.engines.yml up -d voxxy-engine-vibevoice を実行し、/healthz で "name":"vibevoice","ready":true を確認します。
音声を完全に置き換えるのは ElevenLabsフォールバック です。両方のGPUエンジンがダウンしていて ELEVENLABS_API_KEY が設定されている場合、voxは見知らぬ声で 200 を応答し、vox: voice clone BYPASSED をログに記録し、とにかく配信します。すべてのクローン合成の engine フィールドを確認してください — vibevoice または voxcpm がクローンであり、elevenlabs はあなたの声ではありません。
参照音声の予算は10秒であり、30秒ではありません。 2つの異なる上限が重なっており、重要なのは2つ目だけです。POST /voices は取り込みを VOX_REF_AUDIO_MAX_SECONDS = 30秒にトリミングします(compose.yml:16、app/main.py:578-584 で適用、最初の 30秒を保持)。しかし、vibevoiceコンテナは同じ変数を 10 に設定し(compose.engines.yml:69)、engines/vibevoice/engine/synth.py:183,208 は参照を duration=10.0 で再読み込みします。その /healthz は直接 "max_ref_seconds": 10.0 と述べています。したがって、参照クリップの10〜30秒は保存され、バックアップされますが、モデルによって参照されることは決してありません。クローンのパッセージは 8〜10秒のクリーンな秒数 で書き、最も良く、最もニュートラルな音声を最初に配置してください — それ以降はすべて無駄なデータです。
詳細手順
実装または診断については、音声と統合ワークフロー を参照してください。音声クローン作成と外部配信には、ユーザーがそれらのアクションを要求する必要があります。
デフォルト値チートシート
| パラメータ | デフォルト値 | 備考 |
|---|---|---|
cfg | 2.0 | 分類器なしガイダンス; 高いほど忠実度が高く、バリエーションが少ない |
steps | 10 | 拡散ステップ数; 速度重視は4-6、最高品質は15-20 |
normalize | false | テキスト正規化(数字→単語など) |
denoise | false | 無効なフィールド。 app/main.py:98 で宣言されているが、どこからも読み込まれていません。POST /voices にはdenoiseパラメータはまったくありません。代わりに、アップロード前に音声をクリーニングしてください。 |
| キャッシュTTL(音声URL) | 3600秒 | VOX_AUDIO_TTL_SECONDS 環境変数; Telegramには1時間で十分 |
| フォールバック音声(ElevenLabs) | Adam (pNInz6obpgDQGcFmaJgB) | ELEVENLABS_DEFAULT_VOICE 環境変数 |
音声合成は、VOX_OPTIMIZE=1 を設定したRTX 3090上で、おおよそ 1秒あたり21文字 で実行されます — 測定済みであり、推定ではありません: 60文字の行は約2秒、1665文字の行は約35秒かかります。2秒の見出しではなく、長さで予算を立ててください。コンテナ再起動後の最初の呼び出しには、約15秒追加されます(JITコンパイル)。OGG/Opusトランスコードはffmpegを介して100ms未満です。
これは、タイムアウトがある呼び出し元にとって重要です。Hermes vox TTSプラグインは60秒のhttpxタイムアウトをハードコードしており(plugins/tts/vox/__init__.py:29,316)、tts.vox.timeout を無視するため、約2500文字を超える単一チャンクは即座に失敗します。tts.vox.max_text_length(tools/tts_tool.py:436-441 で読み取り)で制限してください。これにより、失敗する代わりにチャンク化されます。
エンジンアップグレードワークフロー
3つのコンテナトポロジーは、コアオーケストレーション(voxxy-core、コンテナ vox、CPUのみ)をGPUバウンドのサイドカーエンジン(voxxy-engine-voxcpm、voxxy-engine-vibevoice)から切り離します。各エンジンコンテナは、engines/<name>/ の下に独自の pyproject.toml、uv.lock、および Dockerfile を維持します。
ステップバイステップのアップグレード手順
1. バージョン発見とランタイム監査
- アップストリームリリース: PyPIとGitHubリリースを確認します:
curl -s https://pypi.org/pypi/voxcpm/json | jq -r '.info.version' - 実行中のコンテナバージョン:
importlib.metadataを介してインストールされたパッケージバージョンを確認します:(docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \ "import importlib.metadata; print(importlib.metadata.version('voxcpm'))"voxcpm.__version__は絶対に使用しないでください。モジュールはそれを定義しておらず、AttributeErrorをスローします)。 - Hugging Face上のモデル重み: モデル重みスナップショットが更新されたかどうかを確認します:
パッケージの更新(推論コード、ストリーミングVAEデコーダー、デバイス処理)は、モデル重みのリビジョンとは異なります。cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
2. 依存関係のバンプとロックファイルの更新
engines/<name>/pyproject.toml内のバージョンピンをバンプします(例:voxcpm==2.0.3)。- uvで依存関係を再ロックします:
cd engines/voxcpm && uv lock - 差分(
git diff engines/voxcpm/uv.lock)をレビューして、PyTorchとtorchaudioが明示的なpytorch-cu124インデックスにピン留めされたままで、PyPI CPUホイールにドリフトしていないことを確認します。
3. エンジンコンテナイメージの再ビルド
composeを介してエンジンイメージを再ビルドします:
docker compose -f compose.yml -f compose.engines.yml build voxxy-engine-voxcpm
# またはmiseエイリアスを介して:
mise run build:voxcpm
Dockerfileはuvを介してPython 3.12をプロビジョニングし、uv sync --frozen --no-install-project を /opt/venv に実行します。
4. composeプロファイルを使用したエンジンコンテナの再作成
エンジンコンテナは、compose.engines.yml 内のcomposeプロファイル(profiles: ["voxcpm"] / profiles: ["vibevoice"])で定義されています。--profile を渡す必要があります。そうしないと、composeはサービスを無視します:
docker compose -f compose.yml -f compose.engines.yml --profile voxcpm up -d --no-build voxxy-engine-voxcpm
コンテナが新しいバージョンを取得したことを確認します:
docker exec voxxy-engine-voxcpm /opt/venv/bin/python -c \
"import importlib.metadata; print(importlib.metadata.version('voxcpm'))"
5. 検証とスモークテスト
- コンテナ起動: モデルロードの成功を示すログを検査します:
docker logs --tail 30 voxxy-engine-voxcpm # "Loaded VoxCPM2Model" と "Application startup complete." を探します。 - エンジンヘルスチェック:
docker exec vox curl -s http://voxxy-engine-voxcpm:8000/healthz # 期待: {"engine":"voxcpm","ready":true,"model_loaded":true,...} - 直接合成テスト: Dockerネットワークを介して
voxコアコンテナから直接生の合成ペイロードを送信します:docker exec vox curl -s -X POST http://voxxy-engine-voxcpm:8000/v1/synthesize \ -H 'content-type: application/json' \ -d '{"text":"Testing synthesis."}' | jq -r '{engine, sample_rate, duration_s, bytes, has_wav: (.wav_b64 != null)}' - 音声クローン作成の検証: 参照音声サンプル(
/data/voices/rick.wav)でテストします:docker exec vox python3 -c ' import base64, urllib.request, json with open("/data/voices/rick.wav", "rb") as f: b64 = base64.b64encode(f.read()).decode("ascii") data = json.dumps({"text": "Test clone.", "reference_audio_b64": b64}).encode("utf-8") req = urllib.request.Request("http://voxxy-engine-voxcpm:8000/v1/synthesize", data=data, headers={"Content-Type": "application/json"}) print(json.loads(urllib.request.urlopen(req).read().decode("utf-8"))) ' - 契約テストとCLIテスト:
bash scripts/verify-engine-contract.sh (cd cli && uv run pytest)
6. デリバリー
エンジンディレクトリ内の pyproject.toml と uv.lock の両方をコミットします:
git add engines/voxcpm/pyproject.toml engines/voxcpm/uv.lock
git commit -m "feat(voxcpm): upgrade voxcpm to <version>"
git push origin main
学んだ教訓とエンジンの注意点
voxcpmパッケージバージョン検査:voxcpmは__version__を公開していません。python -c "import voxcpm; print(voxcpm.__version__)"を呼び出すとAttributeErrorがスローされます。常にimportlib.metadata.version('voxcpm')でインストールされたメタデータを検査してください。- Composeプロファイルの要件:
compose.engines.ymlでは、各エンジンにプロファイルがあります(profiles: ["voxcpm"])。--profile voxcpmなしでdocker compose up voxxy-engine-voxcpmを実行すると、Docker Composeはサイレントにサービスをスキップします。 - スタンバイエンジンは直接テスト可能: 単一のGPUカード上のローカルエンジンは相互に排他的です(VoxCPM ~5 GB VRAM、VibeVoice ~7.5 GB VRAM)。エンジンが
voxxy daemon status/.voxxy.state.jsonでstandby状態であっても、そのコンテナは内部Dockerネットワーク(http://voxxy-engine-<name>:8000)上で実行され、健全です。アクティブなエンジンを切り替えることなく、voxからcurlを介して直接テストできます。 - Pytestテストスイートの場所: リポジトリルートから
pytestを実行すると、plugins/tts/vox/はHermesプラグインであり、agent.tts_providerを期待するため失敗します。app/ユニットテストを実行するには、app/またはdocker exec vox python -m pytest app/にcdしてください。engines/<name>/内のエンジン固有のテストは、そのディレクトリから直接実行できます。
エンジンアップグレードワークフローのトラブルシューティング
| 症状 | 考えられる原因 | 修正 |
|---|---|---|
docker compose build が ERROR: Service "voxxy-engine-voxcpm" uses an unknown profile で失敗する | compose.engines.yml の profiles: キーのタイプミス | スペルが正しいことと、YAMLリストであることを確認します(profiles: ["voxcpm"])。 |
再作成後、コンテナが ImportError でクラッシュする | ロックファイルがPyTorch CPUホイールにドリフトした | uv.lock の差分を確認します。必要に応じて、pyproject.toml で --index-url https://download.pytorch.org/whl/cu124 を明示的に設定して再ロックします。 |
GET /healthz が "ready": false を報告する | コンテナの起動が完了していない | docker logs voxxy-engine-voxcpm でエラーを確認します。コンテナがGPUにアクセスできることを確認します(docker compose logs voxxy-engine-voxcpm、nvidia-smi の出力を探します)。 |
スモークテストで curl: (56) Recv failure: Connection reset by peer が返される | エンジンコンテナがGPUメモリ不足でクラッシュした | docker logs でCUDA OOMエラーを確認します。compose.engines.yml でメモリ制限を減らすか、VOX_OPTIMIZE=1 を設定します。 |