{
  "markdown": "# Voice Bridge\n\n<!-- mcp-name: io.github.dwarmerdam/voice-bridge -->\n\n[![PyPI](https://img.shields.io/pypi/v/ai-voice-bridge)](https://pypi.org/project/ai-voice-bridge/)\n[![CI](https://github.com/Tomorrow-You/voice-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/Tomorrow-You/voice-bridge/actions)\n\nMulti-engine text-to-speech for AI coding assistants. Speaks responses aloud from Claude Code, Cursor, or VS Code via a Claude Code plugin, MCP server, or CLI pipe.\n\n```bash\npip install ai-voice-bridge[edge]   # Install with free edge-tts engine\nvoice-bridge test                   # Verify audio output\nvoice-bridge on                     # Enable always-on mode (optional)\n```\n\n## Features\n\n- **Free by default** -- edge-tts uses Microsoft Neural voices, no API key needed\n- **5 engines** -- edge-tts, ElevenLabs, Kokoro (local ONNX), macOS say, espeak-ng\n- **Text safety filter** -- strips code blocks, secrets, file paths, URLs, and markdown before speaking\n- **Claude Code plugin** -- Stop hook speaks responses automatically, MCP server for tool-based control\n- **Voice discovery** -- browse, filter by gender/locale, and preview voices interactively\n\n## Prerequisites\n\nVoice Bridge is a **Python package** that plays audio on your **local machine**. It requires:\n\n| Requirement | Details |\n|---|---|\n| **Python 3.10+** | `python3 --version` to check |\n| **pip** | Usually bundled with Python. On some Linux distros: `sudo apt install python3-pip` |\n| **Audio output** | Speakers or headphones — audio plays locally, not over a network |\n| **Audio player** (Linux/Windows) | **macOS**: built-in (`afplay`). **Linux**: `mpv` (preferred) or `ffplay`. **Windows**: `ffplay` (preferred) or `mpv` |\n\nAudio player fallback order: macOS uses `afplay` (always available). Linux tries `mpv` then `ffplay`. Windows tries `ffplay` then `mpv`.\n\n> **Not supported**: headless servers, Docker containers, SSH sessions, and CI runners typically lack audio output. Voice Bridge will install and run the MCP server, but `speak` commands will fail silently without an audio player and sound hardware.\n\n## Quick Start\n\n### Install\n\n```bash\n# Recommended: edge-tts (free, 400+ voices)\npip install ai-voice-bridge[edge]\n\n# Or with all engines\npip install ai-voice-bridge[all]\n\n# Or minimal (macOS say / Linux espeak only)\npip install ai-voice-bridge\n```\n\n### Test\n\n```bash\nvoice-bridge test          # Speak a test phrase\nvoice-bridge engines       # List available engines\nvoice-bridge setup         # Interactive setup wizard\n```\n\nThe setup wizard walks you through: detecting installed engines, testing audio output, optionally entering an ElevenLabs API key (if the SDK is installed), writing default state, and showing Claude Code integration options.\n\n### Use\n\n```bash\n# Pipe text to speech\necho \"Hello world\" | vb-speak\n\n# Choose an engine\necho \"Hello\" | vb-speak --engine edge-tts\necho \"Hello\" | vb-speak --engine say\n\n# Modes\nvoice-bridge on            # Always-on: every AI response spoken\nvoice-bridge off           # Off: use \"speak\" keyword for single responses\nvoice-bridge status        # Show current mode and engine\n```\n\n## Claude Code Integration\n\n### Option 1: Install as a Plugin (Recommended)\n\n```bash\nclaude plugin marketplace add Tomorrow-You/voice-bridge\nclaude plugin install voice-bridge@voice-bridge\n```\n\nThis installs the plugin with a Stop hook (auto-speaks responses), the `/speak` skill, and the MCP server. Auto-installs `ai-voice-bridge[edge,mcp]` on first session.\n\n### Option 2: Manual Hook Setup\n\nAdd to your `.claude/settings.json`:\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"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\\\"'\",\n            \"timeout\": 5\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\nThen add to your `CLAUDE.md`:\n\n```markdown\n## Voice Bridge (TTS)\n- **NEVER** use `<speak>` tags unless the user's message starts with \"speak\"\n- When user starts with \"speak\", wrap your ENTIRE response in `<speak>...</speak>` tags\n- Strip the \"speak\" keyword before processing\n- Inside tags, write naturally -- no markdown, code blocks, or file paths\n```\n\n### Option 2: Always-On Mode\n\nSkip the `<speak>` tag convention entirely:\n\n```bash\nvoice-bridge on\n```\n\nNow every Claude response is spoken automatically. Toggle off with `voice-bridge off`.\n\n### Hook Details\n\nThe Stop hook runs in the background so it doesn't block Claude Code. It:\n\n- Extracts text from `<speak>` tags (single-turn mode) or the full response (always-on mode)\n- Truncates to 2,000 characters before speaking\n- Uses a fallback chain: configured engine > espeak > say\n- Logs to `~/.voice-bridge/voice-bridge.log` (auto-rotated at 1MB, keeps 2 backups)\n- Runs `vb-speak --stream` for sentence-by-sentence playback\n\n## Engines\n\n| Engine | Cost | Quality | Setup | Platform | Default voice |\n|--------|------|---------|-------|----------|---------------|\n| **edge-tts** | Free | High (neural) | `pip install ai-voice-bridge[edge]` | All | `en-US-GuyNeural` |\n| **ElevenLabs** | Paid | Highest | `pip install ai-voice-bridge[elevenlabs]` + API key | All | George (`JBFqnCBsd6RMkjVDRZzb`), model `eleven_flash_v2_5` |\n| **Kokoro** | Free | Good | `pip install ai-voice-bridge[kokoro]` + model download | All (English only) | `bm_lewis` |\n| **say** | Free | Basic | Built-in | macOS | `Samantha` |\n| **espeak** | Free | Basic | `apt install espeak-ng` | Linux | `en` |\n\nWhen engine is set to `auto` (default), Voice Bridge picks the first available in this order: edge-tts > say > espeak > kokoro > elevenlabs. ElevenLabs is only considered \"available\" if the SDK is installed AND a valid API key is configured -- it will never be auto-selected without credentials.\n\n### Discovering Voices\n\n```bash\nvoice-bridge voices              # List voices for current engine\nvoice-bridge voices edge-tts     # List voices for a specific engine\n\n# Filter by gender and/or locale\nvoice-bridge voices edge-tts --gender Female --locale en-US\n\n# Preview a specific voice\nvoice-bridge voices edge-tts --preview en-US-AriaNeural\n\n# Interactively audition voices (next/select/quit after each)\nvoice-bridge voices edge-tts --gender Female --locale en-US --preview\n\n# Random sample of 3 voices\nvoice-bridge voices edge-tts --sample 3 --preview\n```\n\nFiltering options: `--gender` (Male/Female) works with edge-tts and kokoro. `--locale` (e.g. en-US, en-GB) works with edge-tts and say. `--sample N` picks N random voices. All combine with `--preview` for interactive audition.\n\nElevenLabs preview uses free pre-recorded samples when available (no API credits consumed).\n\n### Switching Engines\n\n```bash\nvoice-bridge engine edge-tts     # Free neural voices\nvoice-bridge engine elevenlabs   # Premium cloud\nvoice-bridge engine kokoro       # Local offline\nvoice-bridge engine say          # macOS built-in\nvoice-bridge engine espeak       # Linux built-in\nvoice-bridge engine auto         # Best available (default)\n```\n\n### ElevenLabs Setup\n\n```bash\npip install ai-voice-bridge[elevenlabs]\nvoice-bridge setup  # Prompts for your ElevenLabs API key\n# Or manually: create ~/.voice-bridge/.env with ELEVENLABS_API_KEY=your-key\nvoice-bridge engine elevenlabs\nvoice-bridge test\n```\n\n### Kokoro Setup (Offline)\n\n```bash\npip install ai-voice-bridge[kokoro]\n# Download model files (~200MB) from:\n# https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0\n# Place in: ~/.voice-bridge/models/ (or $VOICE_BRIDGE_HOME/models/)\nvoice-bridge engine kokoro\nvoice-bridge test\n```\n\n## Configuration\n\nVoice Bridge stores configuration in `~/.voice-bridge/` (macOS), `~/.local/share/voice-bridge/` (Linux, respects `XDG_DATA_HOME`), or `%APPDATA%\\voice-bridge\\` (Windows).\n\nOverride with the `VOICE_BRIDGE_HOME` environment variable.\n\n| File | Purpose |\n|------|---------|\n| `.env` | API keys (ElevenLabs) |\n| `.state` | Runtime state (mode, engine, speed, voice) |\n| `models/` | Kokoro ONNX model files |\n| `voice-bridge.log` | Hook execution logs (auto-rotated at 1MB, 2 backups) |\n\n### State Variables\n\nThe `.state` file is a shell-sourceable key-value file. All values are optional — defaults apply if unset.\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `VOICE_BRIDGE_MODE` | `off` | Mode: `off` (single-turn) or `always` (always-on) |\n| `VOICE_BRIDGE_ENGINE` | `auto` | Engine name or `auto` |\n| `VOICE_BRIDGE_EDGE_VOICE` | `en-US-GuyNeural` | edge-tts voice |\n| `VOICE_BRIDGE_EDGE_RATE` | `+0%` | edge-tts rate (e.g. `+30%`, `-10%`) |\n| `VOICE_BRIDGE_ELEVENLABS_SPEED` | `1.0` | ElevenLabs speed (0.7–1.2) |\n| `VOICE_BRIDGE_KOKORO_VOICE` | `bm_lewis` | Kokoro voice name |\n| `VOICE_BRIDGE_KOKORO_SPEED` | `1.4` | Kokoro speed multiplier |\n| `VOICE_BRIDGE_SAY_RATE` | `200` | macOS say words per minute |\n| `VOICE_BRIDGE_ESPEAK_RATE` | `175` | espeak words per minute |\n\n## Text Safety Filter\n\nBefore any text reaches the TTS engine, Voice Bridge strips:\n\n- **Code blocks** (fenced ` ``` ` and inline `` ` ``)\n- **Secrets**: OpenAI/Anthropic keys (`sk-...`), GitHub tokens (`ghp_`, `gho_`), AWS keys (`AKIA...`), PEM private keys, 64+ char hex strings\n- **File paths**: Unix (`/Users/...`, `/home/...`) and Windows (`C:\\Users\\...`)\n- **URLs**: `http://` and `https://`\n- **Markdown**: headers, bold/italic markers, list bullets, table rows\n\nText is truncated to 4,000 characters at the nearest sentence boundary (`. `). The Claude hook applies a separate 2,000 character limit before passing text to `vb-speak`.\n\n## CLI Reference\n\n```bash\n# Control\nvoice-bridge on              # Always-on mode\nvoice-bridge off             # Single-turn mode (default)\nvoice-bridge status          # Show mode, engine, config\nvoice-bridge test            # Test audio output\nvoice-bridge engines         # List all engines with install status\nvoice-bridge setup           # Interactive setup wizard\n\n# Engine config\nvoice-bridge engine [name]   # Get/set engine\nvoice-bridge voice [id]      # Set voice for current engine\nvoice-bridge voices [engine] # List available voices\nvoice-bridge speed [val]     # Set engine speed (see below)\n\n# Voice discovery\nvoice-bridge voices edge-tts --gender Female --locale en-US  # Filter\nvoice-bridge voices edge-tts --preview en-US-AriaNeural      # Preview one\nvoice-bridge voices edge-tts --gender Female --preview       # Interactive\nvoice-bridge voices edge-tts --sample 3 --preview            # Random sample\n\n# Pipe to speech\necho \"text\" | vb-speak                    # Default engine\necho \"text\" | vb-speak --engine edge-tts  # Specific engine\necho \"text\" | vb-speak --voice Aria       # Override voice for this call\necho \"text\" | vb-speak --stream           # Stream sentence-by-sentence\necho \"text\" | vb-speak --dry-run          # Print filtered text only\n```\n\n**Streaming mode** (`--stream`): reads stdin, splits text at sentence boundaries (`. `, `! `, `? `), and speaks each sentence as it completes. For edge-tts, sentences are queued so the next one generates while the current one plays.\n\n### Speed Control\n\nEach engine accepts a different speed format:\n\n| Engine | Format | Default | Example |\n|--------|--------|---------|---------|\n| **edge-tts** | Percentage string | `+0%` | `voice-bridge speed +30%` |\n| **elevenlabs** | Float (0.7–1.2) | `1.0` | `voice-bridge speed 1.1` |\n| **kokoro** | Positive float | `1.4` | `voice-bridge speed 1.8` |\n| **say** | Words per minute | `200` | `voice-bridge speed 250` |\n| **espeak** | Words per minute | `175` | `voice-bridge speed 220` |\n\nSpeed applies to whichever engine is currently active. Check with `voice-bridge speed` (no value).\n\n## MCP Server\n\nVoice Bridge includes an MCP (Model Context Protocol) server so any MCP-compatible tool can speak text aloud.\n\n> **npm shim (`npx ai-voice-bridge`)**: The npm package is a thin wrapper that auto-installs the Python package. It requires Python 3.10+ and pip on your `PATH`. On startup it checks for audio players and warns if none are found. See [Prerequisites](#prerequisites) for full requirements.\n\n### Setup with Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"voice-bridge\": {\n      \"command\": \"python3\",\n      \"args\": [\"-m\", \"voice_bridge.mcp.server\"]\n    }\n  }\n}\n```\n\nOr after npm publish, use the npm shim:\n\n```json\n{\n  \"mcpServers\": {\n    \"voice-bridge\": {\n      \"command\": \"npx\",\n      \"args\": [\"ai-voice-bridge\"]\n    }\n  }\n}\n```\n\n### Setup with Cursor / VS Code\n\nAdd the same MCP server config in your editor's MCP settings. The config format is the same as Claude Desktop.\n\n### Setup with Claude Code\n\n```bash\nclaude mcp add voice-bridge -- python3 -m voice_bridge.mcp.server\n```\n\n### MCP Tools\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `speak` | `text` (required), `engine` (optional) | Speak text aloud. Optionally override engine for this call. |\n| `set_engine` | `name` (required) | Switch the default TTS engine (`auto`, `edge-tts`, `elevenlabs`, `kokoro`, `say`, `espeak`) |\n| `get_status` | _(none)_ | Show current mode, engine, and available engines |\n| `list_voices` | `engine` (optional) | List available voices. Defaults to current engine if omitted. |\n\n### Install with MCP support\n\n```bash\npip install ai-voice-bridge[mcp]\n```\n\nThis installs the `voice-bridge-mcp` command as an alternative to `python3 -m voice_bridge.mcp.server`.\n\n## Development\n\n```bash\ngit clone https://github.com/Tomorrow-You/voice-bridge.git\ncd voice-bridge\npython3 -m venv .venv && source .venv/bin/activate\npip install -e \".[all,dev]\"\npytest\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n\nThe `edge-tts` optional dependency is licensed under GPL-3.0. It is not included in the base install.\n",
  "bytes": 13893,
  "sha": "a121937605a2dc09f1207275b93f8bb1267e3a1caf1e546c351c1e52a7147757",
  "repo_slug": "tomorrow-you/voice-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tomorrow_you_voice_bridge_voice_bridge_3630e0f3/readme"
}