Communitygithub.com

vox-tts

セルフホスト型TTSサービスvoxxyを利用して音声を合成します。ユーザーが「話す」「発音する」「ナレーション」「音声合成」「声のクローン作成」「音声の登録」「TTSパイプ」「声質の指定(例:『元気な若い女性の声』)」などを要求した場合に使用します。HTTP API、音声プロファイル管理、説明ベースの音声デザイン、クローン作成、MCP登録、新しいプラットフォーム向けの統合パターンをサポートします。

vox-tts とは?

このスキルは、<https://vox.delo.sh>でホストされているセルフホスト型TTSサービス「voxxy」を活用し、高度な音声合成機能をAIエージェントに提供します。PostgreSQLでバックアップされた音声プロファイルストアを持ち、複数のエンジン(VoxCPM, VibeVoice, ElevenLabs)をサポートし、音声のクローン作成、説明ベースの音声デザイン、さまざまな配信チャネル(Telegram、Discord、Slack、ブラウザ、Home Assistantなど)への音声出力を可能にします。主な機能として、インラインWAVバイトを返す`speak`と配信URLを返す`speak_url`の2つのMCPツールがあり、後者はエージェントのワイヤー上のデータ量を抑え、ほとんどの配信シナリオで推奨されます。また、音声の一覧表示、音声の追加、インタラクティブな音声クローン作成ワークフロー、エンジンのアップグレード手順なども提供します。このスキルはClaude Code、Cursor、Codexなどのプラットフォームで使用でき、Hermesエージェントからのネイティブ統合や、シェルからの`voxxy speak`コマンドによる利用もサポートします。エンジンのフォールバック機能により、GPUエンジンがダウンしてもElevenLabsが代替として動作しますが、クローン音声は元の声ではなくなることに注意が必要です。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/delorenj/skills/tree/HEAD/vox-tts

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

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_urlHAは 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秒のクリーンな秒数 で書き、最も良く、最もニュートラルな音声を最初に配置してください — それ以降はすべて無駄なデータです。

詳細手順

実装または診断については、音声と統合ワークフロー を参照してください。音声クローン作成と外部配信には、ユーザーがそれらのアクションを要求する必要があります。

デフォルト値チートシート

パラメータデフォルト値備考
cfg2.0分類器なしガイダンス; 高いほど忠実度が高く、バリエーションが少ない
steps10拡散ステップ数; 速度重視は4-6、最高品質は15-20
normalizefalseテキスト正規化(数字→単語など)
denoisefalse無効なフィールド。 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上のモデル重み: モデル重みスナップショットが更新されたかどうかを確認します:
    cat ~/.cache/huggingface/hub/models--openbmb--VoxCPM2/refs/main
    curl -s https://huggingface.co/api/models/openbmb/VoxCPM2 | jq -r '.sha'
    
    パッケージの更新(推論コード、ストリーミングVAEデコーダー、デバイス処理)は、モデル重みのリビジョンとは異なります。

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

学んだ教訓とエンジンの注意点

  1. voxcpm パッケージバージョン検査: voxcpm は __version__ を公開していません。python -c "import voxcpm; print(voxcpm.__version__)" を呼び出すと AttributeError がスローされます。常に importlib.metadata.version('voxcpm') でインストールされたメタデータを検査してください。
  2. Composeプロファイルの要件: compose.engines.yml では、各エンジンにプロファイルがあります(profiles: ["voxcpm"])。--profile voxcpm なしで docker compose up voxxy-engine-voxcpm を実行すると、Docker Composeはサイレントにサービスをスキップします。
  3. スタンバイエンジンは直接テスト可能: 単一の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を介して直接テストできます。
  4. 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 を設定します。

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

delorenj/skills

Plan and generate terminal ASCII animations/screensaver-style output (FPS, refresh rules, loop policy, low-flicker guidance), with a static poster frame and an optional local demo script.

delorenj/skills

ASCII video: convert video/audio to colored ASCII MP4/GIF.

delorenj/skills

Plan, build and quality-check a premium short commercial for a real business (roofing, property, ecommerce, B2B software) using AI-generated footage, code-built motion (HTML/GSAP), selective Three.js and an independent-critic "Gauntlet" loop. Use when asked to make a launch-style / SaaS-style video, business ad, explainer, sample reel or pitch video, or to review and improve one. Encodes motion principles distilled from 28 professional launch films, a quality bar, audio rules and a business-offer playbook.

delorenj/skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

delorenj/skills

Generate professional voiceovers using ElevenLabs AI. Use when the user needs to create voiceovers for videos, audio narration, or text-to-speech content. Supports multiple voices with character presets (narrator, salesperson, expert) for natural delivery. Includes single scene regeneration for fine-tuning.

delorenj/skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

delorenj/skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

delorenj/skills

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

delorenj/skills

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

delorenj/skills

Manim CE animations: 3Blue1Brown math/algo videos.

delorenj/skills

Join a Google Meet or Zoom call as a video meeting agent via PikaStreaming. Trigger: user drops a Google Meet or Zoom link, or asks to join a meeting.

delorenj/skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

delorenj/skills

Capture a website and create a HyperFrames video from it. Use when: (1) a user provides a URL and wants a video, (2) someone says "capture this site", "turn this into a video", "make a promo from my site", (3) the user wants a social ad, product tour, or any video based on an existing website, (4) the user shares a link and asks for any kind of video content. Even if the user just pastes a URL — this is the skill to use.

delorenj/skills

YouTube transcripts to summaries, threads, blogs.

関連スキル