Voice Bridge

本地服务

github.com/Tomorrow-You媒体与设计026 周前更新

代码仓库

关于 Voice Bridge

Voice Bridge 是面向 AI 编码 Agent 的 Python 文本转语音包，可通过 5 种可选引擎在本地播放音频。它还提供文本安全过滤、语音查找、命令行控制、Claude Code 插件和 MCP 服务。

主要功能

01提供 5 种可选 TTS 引擎
02过滤代码、机密、路径、网址和 Markdown
03查找、筛选并试听语音
04命令行控制及按句流式播放
05通过 Claude Code 插件自动朗读

适用场景

01收听 Claude Code 对话回复
02将文本传入指定语音引擎
03按地区或性别查找并试听语音
04朗读前移除代码和敏感文本

MCP 相关

MCP 服务提供 `speak`、`set_engine` 和 `get_status` 工具，用于语音播放和引擎控制。音频在本机播放。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y ai-voice-bridge

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmai-voice-bridge0.1.5stdio

pypiai-voice-bridge0.1.5stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

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

设置向导将引导你完成以下步骤：检测已安装的引擎、测试音频输出、可选输入 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 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。只有在已安装 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（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`	Hook 执行日志（达到 1MB 时自动轮转，保留 2 个备份）

状态变量

.state 文件是可由 shell 加载的键值文件。所有值均为可选项——未设置时使用默认值。

变量	默认值	描述
`VOICE_BRIDGE_MODE`	`off`	模式：`off`（单轮）或 `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 每分钟词数
`VOICE_BRIDGE_ESPEAK_RATE`	`175`	espeak 每分钟词数

文本安全过滤器

在任何文本传给 TTS 引擎之前，Voice Bridge 都会移除：

代码块（围栏代码块 ``` 和行内代码 `）
密钥：OpenAI/Anthropic 密钥（sk-...）、GitHub 令牌（ghp_、gho_）、AWS 密钥（AKIA...）、PEM 私钥、长度为 64 个字符或以上的十六进制字符串
文件路径：Unix 路径（/Users/...、/home/...）和 Windows 路径（C:\Users\...）
URL：http:// 和 https://
Markdown：标题、粗体/斜体标记、列表项目符号、表格行

文本会在最近的句子边界（. ）处截断，最多保留 4,000 个字符。Claude Hook 会在将文本传给 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）：从 stdin 读取文本，在句子边界（. 、! 、? ）处分割，并在每个句子完成时播报。对于 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	每分钟字数	`200`	`voice-bridge speed 250`
espeak	每分钟字数	`175`	`voice-bridge speed 220`

速度设置应用于当前启用的引擎。运行 voice-bridge speed（不带参数）可查看当前速度。

MCP 服务

Voice Bridge 内置 MCP（Model Context Protocol）服务，因此任何兼容 MCP 的工具都可以朗读文本。

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]

这会安装 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。详情请参阅 LICENSE。

可选依赖 edge-tts 使用 GPL-3.0 许可证。它不包含在基础安装中。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

Voice Bridge

关于 Voice Bridge

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

Voice Bridge

功能

前置条件

快速开始

安装

测试

使用

Claude Code 集成

选项 1：安装为插件（推荐）

选项 2：手动设置钩子

选项 2：始终开启模式

钩子详情

引擎

探索语音

切换引擎

ElevenLabs 设置

Kokoro 设置（离线）

配置

状态变量

文本安全过滤器

CLI 参考

速度控制

MCP 服务

使用 Claude Desktop 进行设置

使用 Cursor / VS Code 进行设置

使用 Claude Code 进行设置

MCP 工具

安装 MCP 支持

开发

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？