AI导哈

AI语音编码助手

VoiceSmith MCP是一款本地AI语音编码助手，通过文本转语音（TTS）和语音转文本（STT）功能，为AI提供真实的语音交互能力，完全离线运行，无需云API。

  • by shshalom
  • Python
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 shshalom/voicesmith-mcp

使用说明

VoiceSmith MCP

用于编码助手的本地AI语音。通过模型上下文协议（MCP）为您的AI提供真实的语音（文本到语音）和耳朵（语音到文本）。完全离线——没有云API，没有数据离开你的机器。

所得

  • 54种不同的声音 通过Kokoro ONNX（本地TTS，~30MB型号）
  • 语音输入 通过更快的耳语（本地STT，~150MB型号）
  • 话音活动检测 通过Silero VAD（本地，2MB）
  • 多会话支持 --运行多个Claude Code会话，每个会话都有自己的语音（Cursor/Code为单个会话）
  • 使用Claude Code、Cursor和Codex

快速开始

npx voicesmith-mcp install

安装程序将：

  1. 检查系统依赖关系（Python 3.11+，espeak ng，mpv）
  2. 使用所有包设置Python虚拟环境
  3. 下载TTS和STT型号
  4. 配置IDE的MCP设置
  5. 让你选择一个声音
  6. 注入语音行为规则，使AI知道如何说话

安装后重新启动IDE会话。人工智能会在第一个响应时用语音问候你。

用法

[！注意] 一切都是开箱即用的。 安装后，只需启动一个会话——AI会自动说话。无需配置。安装程序设置语音行为规则，教导AI何时以及如何使用其语音。

AI会自动做什么：

时刻 发生了什么
你给它一个任务 开始工作（只在阐明方法时说话）
它完成了工作 总结了所做的工作
它有一个问题 大声问，然后听你的声音回应
语音工具不可用 自动返回文本

中途变声

让AI随时切换声音：

“切换到Nova”

如果语音可用，AI会立即切换。如果它被另一个会话占用，AI会告诉你并显示可用的替代方案。

浏览所有54个声音：

“显示可用的声音”

或者在终端中预览它们： npx voicesmith-mcp voices

语音持久性

[！提示] 当您切换声音时，选择会自动保存。下次您开始或恢复会话时，AI会使用相同的语音，无需再次切换。

静音

在会议或共享空间？只要问：

“将声音静音”

AI继续正常工作，只是不播放音频。说 “取消静音” 当你准备好了。

菜单栏应用程序（macOS）

在macOS上，VoiceSmith包括一个用于免提控制的原生菜单栏应用程序：

  • 会话活动 --使用实时火花线图查看所有活动会话
  • 快速切换 --媒体回避，超时轻推
  • 语音切换器 --浏览和更改54种语音，按语言嵌套
  • Whisper型号 --使用内联下载进度在基本/小/中/大-v3之间切换
  • 音频设备 --选择音频输出和输入设备
  • 语音规则 --编辑或重置为默认值
  • 更新 --检查并安装新版本

菜单栏应用程序在登录时自动启动，并独立于IDE会话运行。

音频设备选择

从菜单栏应用程序或配置中选择特定的音频输出（扬声器/耳机）和输入（麦克风）设备：

{
  "tts": { "audio_output_device": "coreaudio/BuiltInSpeakerDevice" },
  "stt": { "audio_input_device": 1 }
}

更改立即生效，无需重新启动。如果配置的设备不可用，则恢复到系统默认值。

打断讲话

按 逃脱 而AI正在说话以立即停止音频。AI在句子中间停止并等待您的下一个输入。

替代安装

如果你没有Node.js或更喜欢shell脚本：

git clone https://github.com/shshalom/voicesmith-mcp.git
cd voicesmith-mcp
./install.sh

支持相同的标志： --claude, --cursor, --codex, --all, --uninstall.

MCP工具

安装后，您的AI助手可以访问这些工具：

工具 说明
speak 为命名代理合成和播放语音
listen 打开麦克风，录制语音，返回转录文本
speak_then_listen 说一个问题，然后立即听答案
set_voice 更改代理名称的声音
get_voice_registry 查看已分配和可用的语音
list_voices 浏览所有54个科科罗的声音
mute / unmute 静音或恢复语音输出
stop 停止播放或取消活动录制
status 服务器运行状况和会话信息
list_audio_devices 列出可用的音频输入和输出设备

运作原理

MCP服务器与IDE一起作为本地进程运行。它通过stdio（MCP协议）进行通信。所有处理都在您的机器上进行：

  • 文本转语音：Kokoro ONNX——快速神经TTS，54种声音，无需GPU
  • 语音转文字：更快的耳语——OpenAI whisper通过CTranslate2在本地运行
  • 语音活动检测：Silero VAD——用于干净录音的语音活动检测
  • 音频：mpv用于播放；CoreAudio通过macOS上的原生应用程序包（Linux上的声音设备回退）
  • 媒体回避：语音期间自动暂停Apple Music、Spotify和浏览器音频（macOS）

多会话

克劳德代码： 全面的多会话支持。多个Claude Code会话可以同时运行，每个会话都有自己的语音。会话身份通过Claude的 session_id --恢复会话会回收相同的语音，共享同一会话的多个终端共享相同的语音。孤立服务器会被自动检测和清理。

光标/代码： 仅限单次会议。Cursor每个配置运行一个MCP服务器（跨选项卡共享），Codex没有多会话挂钩。语音正常工作，只是没有多会话协调。

跨会话音频通过以下方式序列化 flock 以防止重叠播放。

配置

Config住在 ~/.local/share/voicesmith-mcp/config.json.按键设置：

{
  "main_agent": "Eric",
  "tts": {
    "default_voice": "am_eric",
    "audio_player": "mpv",
    "duck_media": true
  },
  "stt": {
    "model_size": "base",
    "language": "en",
    "vad_threshold": 0.3,
    "nudge_on_timeout": false
  }
}
设置 说明 默认值
tts.duck_media 语音时自动暂停音乐/浏览器音频（macOS） true
stt.nudge_on_timeout 听完后说“我没听懂” false
stt.vad_threshold 语音检测灵敏度（较低=更灵敏） 0.3

重新运行 npx voicesmith-mcp install 更改您的语音或更新设置。保留现有配置，只添加新的默认值。

需求

  • Python 3.11+ （推荐3.11或3.12）
  • macOS （主平台）或Linux（部分支持）
  • 特定的 --Kokoro的音素后端
  • mpv --音频播放
  • 型号约500MB磁盘空间

[！警告] Windows尚不受支持。 服务器使用Unix特定的功能（文件锁定、音频命令、进程检测）。计划支持Windows--请参阅 待办事项 了解详情。

支持的IDE

IDE 配置位置 规则位置 多会话
克劳德代码 ~/.claude.json ~/.claude/CLAUDE.md 是（通过session_id）
光标 ~/.cursor/mcp.json ~/.cursor/rules/voicesmith.mdc 否（单服务器）
食品法典委员会 ~/.codex/mcp.json ~/.codex/AGENTS.md 否（单次会议）

故障排除

AI听不见我（listen返回空或超时）

检查麦克风权限。 在macOS上，VoiceSmith使用本机应用程序包(VoiceSmithMCP.app)用于麦克风访问。首次录制时，macOS应显示应用程序的权限对话框。如果没有：

  1. 打开 系统设置>隐私和安全>麦克风
  2. 寻找 VoiceSmithMCP 并确保它已启用
  3. 如果未列出，则LaunchAgent可能未运行——请尝试重新安装： npx voicesmith-mcp install

[！重要] 如果服务器检测到无声音频（约320ms为全零），它将返回一个错误，指向麦克风权限设置。这通常意味着macOS TCC拒绝麦克风访问。

检查您的音频输入设备。 如果选择了外部麦克风但未连接，服务器会打开它但会静音：

  • 打开 系统设置>声音>输入 并验证是否选择了正确的麦克风
  • 或者问AI： “服务器状态如何？” --检查一下 stt.loaded 和 vad.loaded 两者都 true

另一个应用程序正在使用麦克风。 Zoom、Teams或FaceTime等应用程序可以拥有独家麦克风访问权限。请关闭它们，然后重试。

声音对VAD来说太安静了。 语音活动检测器可能无法检测到软语音。您可以在中降低灵敏度阈值 ~/.local/share/voicesmith-mcp/config.json:

{
  "stt": {
    "vad_threshold": 0.2
  }
}

值越低=越敏感。默认值为 0.3。更改后重新启动会话。

AI不会说话

  • 检查一下 特定的 和 mpv 已安装： which espeak-ng mpv
  • 检查AI的状态：询问 “你的声音状态如何？”
  • 如果静音，请说 “取消静音”

AI用错误的声音说话

当另一个会话使用您的首选语音名称时，可能会发生这种情况。问AI： “切换到Eric” --它要么会切换，要么会告诉你有什么可用的。

卸载

npx voicesmith-mcp uninstall
# or if installed via git clone:
./install.sh --uninstall

彻底删除所有文件、模型、MCP配置条目、语音规则、LaunchAgent和挂钩。

许可证

Apache 2.0

相关 MCP