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等
• 文本安全过滤器 --在说话前删除代码块、机密、文件路径、URL和标记
• Claude代码插件 --停止钩子自动发出响应，MCP服务器用于基于工具的控制
• 语音发现 --浏览、按性别/地区过滤和交互式预览声音

先决条件

语音桥是一个 Python包 在您的设备上播放音频 本地机器它要求：

音频播放器回退顺序：macOS使用 afplay （始终可用）。Linux尝试 mpv 然后 ffplayWindows尝试 ffplay 然后 mpv.

不支持：无头服务器、Docker容器、SSH会话和CI运行器通常缺少音频输出。语音桥将安装并运行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

设置向导将引导您完成：检测已安装的引擎、测试音频输出、可选地输入ElevenLabs API密钥（如果安装了SDK）、编写默认状态以及显示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代码集成

选项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 `` tags unless the user's message starts with "speak"
- When user starts with "speak", wrap your ENTIRE response in `...` tags
- Strip the "speak" keyword before processing
- Inside tags, write naturally -- no markdown, code blocks, or file paths

选项2：始终开启模式

跳过 `` 标签约定完全：

voice-bridge on

现在克劳德的每一个回答都是自动说出的。通过以下方式关闭 voice-bridge off.

挂钩细节

Stop钩子在后台运行，因此它不会阻塞Claude代码。它

• 从中提取文本 `` 标签（单圈模式）或全响应（始终开启模式）
• 说话前截断至2000个字符
• 使用回退链：配置引擎>espeak>say
• 日志到 ~/.voice-bridge/voice-bridge.log （以1MB自动旋转，保留2个备份）
• 跑 vb-speak --stream 用于逐句回放

发动机

当发动机设置为 auto （默认），语音桥按以下顺序选择第一个可用的：edge-tts>say>espeak>kokoro>elevenlabs。只有在安装了SDK并且配置了有效的API密钥的情况下，ElevenLabs才被视为“可用”——如果没有凭据，它将永远不会自动选择。

发现声音

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 （男/女）与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/ （macOS）， ~/.local/share/voice-bridge/ （Linux，尊重 XDG_DATA_HOME)，或 %APPDATA%\voice-bridge\ （Windows）。

用覆盖 VOICE_BRIDGE_HOME 环境变量。

状态变量

这 .state file是一个shell源键值文件。所有值都是可选的——如果未设置，则应用默认值。

文本安全过滤器

在任何文本到达TTS引擎之前，语音桥会删除：

• 代码块 （围栏 ``` ` `` 和内联 ``)
• 秘密：OpenAI/拟人键(sk-...)，GitHub代币(ghp_, gho_)，AWS密钥(AKIA...)，PEM私钥，64+字符十六进制字符串
• 文件路径：Unix(/Users/..., /home/...)和Windows(C:\Users\...)
• 网址: http:// 和 https://
• 标记语言：标题、粗体/斜体标记、列表项目符号、表格行

文本在最近的句子边界处被截断为4000个字符(. ).Claude钩子在将文本传递给 vb-speak.

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)：读取stdin，在句子边界分割文本(. , ! , ? )，并在完成每个句子时说出。对于边缘tts，句子会排队，以便在当前句子播放的同时生成下一个句子。

速度控制

每台发动机接受不同的速度格式：

速度适用于当前处于活动状态的任何发动机。与核对 voice-bridge speed （无值）。

MCP服务器

Voice Bridge包括一个MCP（模型上下文协议）服务器，因此任何兼容MCP的工具都可以大声朗读文本。

npm垫片(npx ai-voice-bridge)：npm包是一个自动安装Python包的瘦包装器。它需要Python 3.10+和pip PATH启动时，它会检查音频播放器，如果没有找到，则发出警告。看 先决条件 以满足全部要求。

使用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"]
    }
  }
}

使用游标/VS代码进行设置

在编辑器的MCP设置中添加相同的MCP服务器配置。配置格式与Claude Desktop相同。

使用Claude代码进行设置

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

MCP工具

使用MCP支架进行安装

pip install ai-voice-bridge[mcp]

这将安装 voice-bridge-mcp 命令作为替代 python3 -m voice_bridge.mcp.server.

发展

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。看 许可证 了解详情。

这 edge-tts 可选依赖关系在GPL-3.0下获得许可。它不包含在基础安装中。