Voice Bridge

Multi-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.

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)

Features

• Free by default -- edge-tts uses Microsoft Neural voices, no API key needed
• 5 engines -- edge-tts, ElevenLabs, Kokoro (local ONNX), macOS say, espeak-ng
• Text safety filter -- strips code blocks, secrets, file paths, URLs, and markdown before speaking
• Claude Code plugin -- Stop hook speaks responses automatically, MCP server for tool-based control
• Voice discovery -- browse, filter by gender/locale, and preview voices interactively

Prerequisites

Voice Bridge is a Python package that plays audio on your local machine. It requires:

| Requirement | Details | |---|---| | Python 3.10+ | python3 --version to check | | pip | Usually bundled with Python. On some Linux distros: sudo apt install python3-pip | | Audio output | Speakers or headphones — audio plays locally, not over a network | | Audio player (Linux/Windows) | macOS: built-in (afplay). Linux: mpv (preferred) or ffplay. Windows: ffplay (preferred) or mpv |

Audio player fallback order: macOS uses afplay (always available). Linux tries mpv then ffplay. Windows tries ffplay then mpv.

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.

Quick Start

Install

# 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

Test

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

The 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.

Use

# 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 Integration

Option 1: Install as a Plugin (Recommended)

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

This 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.

Option 2: Manual Hook Setup

Add to your .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
          }
        ]
      }
    ]
  }
}

... View full README on GitHub