Voice Bridge

Voice Bridge

AI コーディングアシスタント向けの複数エンジン対応テキスト読み上げツールです。Claude Code プラグイン、MCP サーバー、または CLI パイプを介して、Claude Code、Cursor、VS Code の応答を音声で読み上げます。

pip install ai-voice-bridge[edge]   # Install with free edge-tts engine
voice-bridge test                   # Verify audio output
voice-bridge on                     # Enable always-on mode (optional)

機能

• デフォルトで無料 -- edge-tts は Microsoft Neural 音声を使用するため、API キーは不要です
• 5 つのエンジン -- edge-tts、ElevenLabs、Kokoro（ローカル ONNX）、macOS say、espeak-ng
• テキストの安全性フィルター -- 読み上げ前にコードブロック、シークレット、ファイルパス、URL、Markdown を除去します
• Claude Code プラグイン -- Stop フックで応答を自動読み上げし、MCP サーバーでツールによる操作が可能です
• 音声の検索 -- 音声を閲覧し、性別やロケールで絞り込み、対話形式で試聴できます

前提条件

Voice Bridge は、ローカルマシンで音声を再生するPython パッケージです。次の要件が必要です。

要件	詳細
Python 3.10+	python3 --version で確認できます
pip	通常は Python に同梱されています。一部の Linux ディストリビューションでは、sudo apt install python3-pip を実行してください
音声出力	スピーカーまたはヘッドホンが必要です。音声はローカルで再生され、ネットワーク経由ではありません
音声プレーヤー（Linux/Windows）	macOS：組み込み（afplay）。Linux：mpv（推奨）または ffplay。Windows：ffplay（推奨）または mpv

音声プレーヤーのフォールバック順：macOS では afplay を使用します（常に利用可能）。Linux では mpv、次に ffplay を試します。Windows では ffplay、次に mpv を試します。

サポート対象外：ヘッドレスサーバー、Docker コンテナー、SSH セッション、CI ランナーには、通常、音声出力がありません。Voice Bridge のインストールと MCP サーバーの実行はできますが、音声プレーヤーと音声出力ハードウェアがない場合、speak コマンドはエラーを表示せずに失敗します。

クイックスタート

インストール

# Recommended: edge-tts (free, 400+ voices)
pip install ai-voice-bridge[edge]

# Or with all engines
pip install ai-voice-bridge[all]

# Or minimal (macOS say / Linux espeak only)
pip install ai-voice-bridge

テスト

voice-bridge test          # Speak a test phrase
voice-bridge engines       # List available engines
voice-bridge setup         # Interactive setup wizard

セットアップウィザードでは、インストール済みエンジンの検出、音声出力のテスト、（SDK がインストールされている場合は）ElevenLabs API キーの入力（任意）、デフォルト状態の書き込み、Claude Code 連携オプションの表示を順に行います。

使用方法

# Pipe text to speech
echo "Hello world" | vb-speak

# Choose an engine
echo "Hello" | vb-speak --engine edge-tts
echo "Hello" | vb-speak --engine say

# Modes
voice-bridge on            # Always-on: every AI response spoken
voice-bridge off           # Off: use "speak" keyword for single responses
voice-bridge status        # Show current mode and engine

Claude Code との連携

オプション 1：プラグインとしてインストール（推奨）

claude plugin marketplace add Tomorrow-You/voice-bridge
claude plugin install voice-bridge@voice-bridge

Stop フック（応答を自動読み上げ）、/speak スキル、MCP サーバーを含むプラグインがインストールされます。初回セッション時に ai-voice-bridge[edge,mcp] が自動でインストールされます。

オプション 2：フックを手動で設定

.claude/settings.json に追加します。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'VB_HOOK=$(python3 -c \"import voice_bridge; import pathlib; print(pathlib.Path(voice_bridge.__file__).parent / \\\"integrations\\\" / \\\"claude_hook.sh\\\")\" 2>/dev/null) && [ -f \"$VB_HOOK\" ] && bash \"$VB_HOOK\"'",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

次に、CLAUDE.md に追加します。

## Voice Bridge (TTS)
- **NEVER** use `<speak>` tags unless the user's message starts with "speak"
- When user starts with "speak", wrap your ENTIRE response in `<speak>...</speak>` tags
- Strip the "speak" keyword before processing
- Inside tags, write naturally -- no markdown, code blocks, or file paths

オプション 2：常時オンモード

<speak> タグを使う方法を完全に省略します。

voice-bridge on

これで Claude のすべての応答が自動的に読み上げられます。voice-bridge off でオフにできます。

フックの詳細

Stop フックは Claude Code をブロックしないよう、バックグラウンドで実行されます。次の処理を行います。

• <speak> タグからテキストを抽出します（単一ターンモード）。常時オンモードでは応答全体を抽出します
• 読み上げ前に 2,000 文字で切り詰めます
• フォールバックチェーンを使用します：設定済みエンジン > espeak > say
• ~/.voice-bridge/voice-bridge.log にログを記録します（1MB で自動ローテーションし、バックアップを 2 つ保持します）
• vb-speak --stream を実行して、文ごとに再生します

エンジン

エンジン	料金	品質	セットアップ	プラットフォーム	デフォルトの音声
edge-tts	無料	高（ニューラル）	pip install ai-voice-bridge[edge]	すべて	en-US-GuyNeural
ElevenLabs	有料	最高	pip install ai-voice-bridge[elevenlabs] + API キー	すべて	George（JBFqnCBsd6RMkjVDRZzb）、モデル eleven_flash_v2_5
Kokoro	無料	良好	pip install ai-voice-bridge[kokoro] + モデルのダウンロード	すべて（英語のみ）	bm_lewis
say	無料	基本	組み込み	macOS	Samantha
espeak	無料	基本	apt install espeak-ng	Linux	en

エンジンが auto（デフォルト）に設定されている場合、Voice Bridge は次の順序で最初に利用可能なエンジンを選択します：edge-tts > say > espeak > kokoro > elevenlabs。ElevenLabs は、SDK がインストールされ、有効な API キーが設定されている場合にのみ「利用可能」と見なされます。認証情報がなければ、自動選択されることはありません。

音声の確認

voice-bridge voices              # List voices for current engine
voice-bridge voices edge-tts     # List voices for a specific engine

# Filter by gender and/or locale
voice-bridge voices edge-tts --gender Female --locale en-US

# Preview a specific voice
voice-bridge voices edge-tts --preview en-US-AriaNeural

# Interactively audition voices (next/select/quit after each)
voice-bridge voices edge-tts --gender Female --locale en-US --preview

# Random sample of 3 voices
voice-bridge voices edge-tts --sample 3 --preview

フィルタリングオプション：--gender（Male/Female）は edge-tts と kokoro で使用できます。--locale（例：en-US、en-GB）は edge-tts と say で使用できます。--sample N は N 個の音声をランダムに選択します。これらはすべて --preview と組み合わせて、対話形式で試聴できます。

ElevenLabs のプレビューでは、利用可能な場合、事前録音された無料サンプルを使用します（API クレジットは消費されません）。

エンジンの切り替え

voice-bridge engine edge-tts     # Free neural voices
voice-bridge engine elevenlabs   # Premium cloud
voice-bridge engine kokoro       # Local offline
voice-bridge engine say          # macOS built-in
voice-bridge engine espeak       # Linux built-in
voice-bridge engine auto         # Best available (default)

ElevenLabs のセットアップ

pip install ai-voice-bridge[elevenlabs]
voice-bridge setup  # Prompts for your ElevenLabs API key
# Or manually: create ~/.voice-bridge/.env with ELEVENLABS_API_KEY=your-key
voice-bridge engine elevenlabs
voice-bridge test

Kokoro のセットアップ（オフライン）

pip install ai-voice-bridge[kokoro]
# Download model files (~200MB) from:
# https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0
# Place in: ~/.voice-bridge/models/ (or $VOICE_BRIDGE_HOME/models/)
voice-bridge engine kokoro
voice-bridge test

設定

Voice Bridge は、設定を ~/.voice-bridge/（macOS）、~/.local/share/voice-bridge/（Linux。XDG_DATA_HOME に対応）、または %APPDATA%\voice-bridge\（Windows）に保存します。

VOICE_BRIDGE_HOME 環境変数で保存先を変更できます。

ファイル	用途
.env	API キー（ElevenLabs）
.state	実行時の状態（モード、エンジン、速度、音声）
models/	Kokoro の ONNX モデルファイル
voice-bridge.log	フックの実行ログ（1MB で自動ローテーション、バックアップ 2 件）

状態変数

.state ファイルは、シェルから読み込み可能なキーと値のファイルです。すべての値は省略可能です。未設定の場合はデフォルトが適用されます。

変数	デフォルト	説明
VOICE_BRIDGE_MODE	off	モード：off（1 回のターンのみ）または always（常時オン）
VOICE_BRIDGE_ENGINE	auto	エンジン名または auto
VOICE_BRIDGE_EDGE_VOICE	en-US-GuyNeural	edge-tts の音声
VOICE_BRIDGE_EDGE_RATE	+0%	edge-tts の速度（例：+30%、-10%）
VOICE_BRIDGE_ELEVENLABS_SPEED	1.0	ElevenLabs の速度（0.7～1.2）
VOICE_BRIDGE_KOKORO_VOICE	bm_lewis	Kokoro の音声名
VOICE_BRIDGE_KOKORO_SPEED	1.4	Kokoro の速度倍率
VOICE_BRIDGE_SAY_RATE	200	macOS say の 1 分あたりの単語数
VOICE_BRIDGE_ESPEAK_RATE	175	espeak の 1 分あたりの単語数

テキスト安全フィルター

テキストが TTS エンジンに渡される前に、Voice Bridge は次の内容を除去します。

• コードブロック（フェンス付きの ``` とインラインの `）
• シークレット：OpenAI/Anthropic のキー（sk-...）、GitHub トークン（ghp_、gho_）、AWS キー（AKIA...）、PEM 秘密鍵、64 文字以上の 16 進文字列
• ファイルパス：Unix（/Users/...、/home/...）および Windows（C:\Users\...）
• URL：http:// および https://
• Markdown：見出し、太字／斜体マーカー、リストの箇条書き、表の行

テキストは、最も近い文の区切り（. ）で 4,000 文字に切り詰められます。Claude フックでは、vb-speak に渡す前に別途 2,000 文字の制限が適用されます。

CLI リファレンス

# Control
voice-bridge on              # Always-on mode
voice-bridge off             # Single-turn mode (default)
voice-bridge status          # Show mode, engine, config
voice-bridge test            # Test audio output
voice-bridge engines         # List all engines with install status
voice-bridge setup           # Interactive setup wizard

# Engine config
voice-bridge engine [name]   # Get/set engine
voice-bridge voice [id]      # Set voice for current engine
voice-bridge voices [engine] # List available voices
voice-bridge speed [val]     # Set engine speed (see below)

# Voice discovery
voice-bridge voices edge-tts --gender Female --locale en-US  # Filter
voice-bridge voices edge-tts --preview en-US-AriaNeural      # Preview one
voice-bridge voices edge-tts --gender Female --preview       # Interactive
voice-bridge voices edge-tts --sample 3 --preview            # Random sample

# Pipe to speech
echo "text" | vb-speak                    # Default engine
echo "text" | vb-speak --engine edge-tts  # Specific engine
echo "text" | vb-speak --voice Aria       # Override voice for this call
echo "text" | vb-speak --stream           # Stream sentence-by-sentence
echo "text" | vb-speak --dry-run          # Print filtered text only

ストリーミングモード（--stream）：標準入力を読み込み、文の区切り（. 、! 、? ）でテキストを分割し、文が完成するたびに読み上げます。edge-tts の場合、次の文は現在の文の再生中に生成されるよう、キューに入れられます。

速度の制御

各エンジンで受け付ける速度の形式は異なります。

エンジン	形式	デフォルト	例
edge-tts	パーセント文字列	+0%	voice-bridge speed +30%
elevenlabs	浮動小数点数（0.7–1.2）	1.0	voice-bridge speed 1.1
kokoro	正の浮動小数点数	1.4	voice-bridge speed 1.8
say	1分あたりの単語数	200	voice-bridge speed 250
espeak	1分あたりの単語数	175	voice-bridge speed 220

速度は現在有効なエンジンに適用されます。voice-bridge speed（値なし）で確認できます。

MCP サーバー

Voice Bridge には、MCP 互換ツールであればどれでもテキストを読み上げられるようにする、MCP（Model Context Protocol）サーバーが含まれています。

npm shim（npx ai-voice-bridge）：npm パッケージは、Python パッケージを自動でインストールする薄いラッパーです。Python 3.10 以降と、PATH 上の pip が必要です。起動時にオーディオプレーヤーを確認し、見つからない場合は警告します。要件の詳細は前提条件をご覧ください。

Claude Desktop のセットアップ

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "voice-bridge": {
      "command": "python3",
      "args": ["-m", "voice_bridge.mcp.server"]
    }
  }
}

または、npm 公開後に npm shim を使用します。

{
  "mcpServers": {
    "voice-bridge": {
      "command": "npx",
      "args": ["ai-voice-bridge"]
    }
  }
}

Cursor／VS Code のセットアップ

エディターの MCP 設定に、同じ MCP サーバー設定を追加します。設定形式は Claude Desktop と同じです。

Claude Code のセットアップ

claude mcp add voice-bridge -- python3 -m voice_bridge.mcp.server

MCP ツール

ツール	パラメーター	説明
speak	text（必須）、engine（任意）	テキストを読み上げます。この呼び出しに限り、エンジンを上書きできます。
set_engine	name（必須）	デフォルトの TTS エンジン（auto、edge-tts、elevenlabs、kokoro、say、espeak）を切り替えます
get_status	(なし)	現在のモード、エンジン、利用可能なエンジンを表示します
list_voices	engine（任意）	利用可能な音声を一覧表示します。省略した場合は、現在のエンジンがデフォルトになります。

MCP サポート付きでインストールする

pip install ai-voice-bridge[mcp]

これにより、python3 -m voice_bridge.mcp.server の代替として voice-bridge-mcp コマンドがインストールされます。

開発

git clone https://github.com/Tomorrow-You/voice-bridge.git
cd voice-bridge
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[all,dev]"
pytest

ライセンス

MIT。詳細はLICENSEをご覧ください。

オプションの依存関係である edge-tts は GPL-3.0 ライセンスです。基本インストールには含まれていません。