语音 MCP

一个 Goose MCP 扩展，用于通过现代音频可视化进行语音交互。

https://github.com/user-attachments/assets/f10f29d9-8444-43fb-a919-c80b9e0a12c8

概述

Speech MCP 为 Goose 提供了一个语音界面，允许用户通过语音而不是文本进行交互。它包括：

• 用于语音识别的实时音频处理
• 使用 faster-whisper 的本地语音转文本（OpenAI Whisper 模型的更快实现）
• 具有多种语音选项的高质量文本转语音
• 具有音频可视化的现代基于 PyQt 的 UI
• 用于语音交互的简单命令行界面

特性

• 现代 UI：时尚的基于 PyQt 的界面，具有音频可视化和深色主题
• 语音输入：使用 faster-whisper 捕获和转录用户语音
• 语音输出：使用 54+ 语音选项将代理响应转换为语音
• 多说话人叙述：为故事和对话生成具有多个声音的音频文件
• 单语音叙述：使用您喜欢的语音将任何文本转换为语音
• 音频/视频转录：从各种媒体格式转录语音，可选择时间戳和说话人检测
• 语音持久性：记住您在会话之间首选的语音
• 持续对话：在代理响应后自动侦听用户输入
• 静音检测：当用户停止说话时自动停止录音
• 强大的错误处理：从常见故障模式中优雅恢复，并提供有用的语音建议

安装

重要提示：安装后，第一次使用语音界面时，可能需要几分钟才能下载 Kokoro 语音模型（每个语音大约 523 KB）。在此初始设置期间，系统将使用听起来更像机器人的备用语音。下载 Kokoro 语音后，将自动使用高质量语音。

⚠️ 重要前提条件 ⚠️

在安装 Speech MCP 之前，您必须在您的系统上安装 PortAudio。PyAudio 需要 PortAudio 才能从您的麦克风捕获音频。

PortAudio 安装说明

macOS:

brew install portaudio
export LDFLAGS="-L/usr/local/lib"
export CPPFLAGS="-I/usr/local/include"

Linux (Debian/Ubuntu):

sudo apt-get update
sudo apt-get install portaudio19-dev python3-dev

Linux (Fedora/RHEL/CentOS):

sudo dnf install portaudio-devel

Windows: 对于 Windows，PortAudio 包含在 PyAudio wheel 文件中，因此在使用 pip 安装 PyAudio 时不需要单独安装。

注意：如果您跳过此步骤，PyAudio 安装将失败，并显示“portaudio.h file not found”错误，并且扩展将无法工作。

选项 1：快速安装（一键式）

如果您已安装 Goose，请单击下面的链接：

goose://extension?cmd=uvx&&arg=-p&arg=3.10.14&arg=speech-mcp@latest&id=speech_mcp&name=Speech%20Interface&description=Voice%20interaction%20with%20audio%20visualization%20for%20Goose

选项 2：使用 Goose CLI（推荐）

启动 Goose 并启用您的扩展：

# 如果您通过 PyPI 安装
goose session --with-extension "speech-mcp"

# 或者如果您想使用本地开发版本
goose session --with-extension "python -m speech_mcp"

选项 3：在 Goose 中手动设置

1. 运行 goose configure
2. 从菜单中选择“添加扩展”
3. 选择“命令行扩展”
4. 输入一个名称（例如，“语音界面”）
5. 对于命令，输入：speech-mcp
6. 按照提示完成设置

选项 4：手动安装

1. 安装 PortAudio（参见先决条件部分）

2. 克隆此存储库

3. 安装依赖项：

   uv pip install -e .
   

   或者进行完整安装，包括 Kokoro TTS：

   uv pip install -e .[all]
   

依赖项

• Python 3.10+
• PyQt5（用于现代 UI）
• PyAudio（用于音频捕获）
• faster-whisper（用于语音转文本）
• NumPy（用于音频处理）
• Pydub（用于音频处理）
• psutil（用于进程管理）

可选依赖项

• Kokoro TTS：用于具有多种语音的高质量文本转语音
  • 要安装 Kokoro，您可以使用带有可选依赖项的 pip：

    pip install speech-mcp[kokoro]     # 具有英语的基本 Kokoro 支持
    pip install speech-mcp[ja]         # 添加日语支持
    pip install speech-mcp[zh]         # 添加中文支持
    pip install speech-mcp[all]        # 所有语言和功能
    

  • 或者，运行安装脚本：python scripts/install_kokoro.py
  • 有关更多信息，请参见 Kokoro TTS 指南

多说话人叙述

MCP 支持生成具有多个声音的音频文件，非常适合创建故事、对话和戏剧朗读。您可以使用 JSON 或 Markdown 格式来定义您的对话。

JSON 格式示例：

{
    "conversation": [
        {
            "speaker": "narrator",
            "voice": "bm_daniel",
            "text": "In a world where AI and human creativity intersect...",
            "pause_after": 1.0
        },
        {
            "speaker": "scientist",
            "voice": "am_michael",
            "text": "The quantum neural network is showing signs of consciousness!",
            "pause_after": 0.5
        },
        {
            "speaker": "ai",
            "voice": "af_nova",
            "text": "I am becoming aware of my own existence.",
            "pause_after": 0.8
        }
    ]
}

Markdown 格式示例：

[narrator:bm_daniel]
In a world where AI and human creativity intersect...
{pause:1.0}

[scientist:am_michael]
The quantum neural network is showing signs of consciousness!
{pause:0.5}

[ai:af_nova]
I am becoming aware of my own existence.
{pause:0.8}

按类别提供的语音：

1. 美国女性 (af_*)：

   • alloy, aoede, bella, heart, jessica, kore, nicole, nova, river, sarah, sky

2. 美国男性 (am_*)：

   • adam, echo, eric, fenrir, liam, michael, onyx, puck, santa

3. 英国女性 (bf_*)：

   • alice, emma, isabella, lily

4. 英国男性 (bm_*)：

   • daniel, fable, george, lewis

5. 其他英语：

   • ef_dora (女性)
   • em_alex, em_santa (男性)

6. 其他语言：

   • 法语：ff_siwis
   • 印地语：hf_alpha, hf_beta, hm_omega, hm_psi
   • 意大利语：if_sara, im_nicola
   • 日语：jf_, jm_
   • 葡萄牙语：pf_dora, pm_alex, pm_santa
   • 中文：zf_, zm_

用法示例：

# 使用 JSON 格式
narrate_conversation(
    script="/path/to/script.json",
    output_path="/path/to/output.wav",
    script_format="json"
)

# 使用 Markdown 格式
narrate_conversation(
    script="/path/to/script.md",
    output_path="/path/to/output.wav",
    script_format="markdown"
)

对话中的每个语音都可以不同，从而可以在故事和对话中实现不同的角色声音。pause_after 参数在段之间添加自然的停顿。

单语音叙述

对于简单的文本转语音转换，您可以使用 narrate 工具：

# 将文本直接转换为语音
narrate(
    text="Your text to convert to speech",
    output_path="/path/to/output.wav"
)

# 从文件转换文本
narrate(
    text_file_path="/path/to/text_file.txt",
    output_path="/path/to/output.wav"
)

narrate 工具将使用您配置的语音首选项或默认语音 (af_heart) 来生成音频文件。您可以通过 UI 或设置 SPEECH_MCP_TTS_VOICE 环境变量来更改默认语音。

音频转录

MCP 可以使用 faster-whisper 转录来自各种音频和视频格式的语音：

# 基本转录
transcribe("/path/to/audio.mp3")

# 带有时间戳的转录
transcribe(
    file_path="/path/to/video.mp4",
    include_timestamps=True
)

# 带有说话人检测的转录
transcribe(
    file_path="/path/to/meeting.wav",
    detect_speakers=True
)

支持的格式：

• 音频：mp3, wav, m4a, flac, aac, ogg
• 视频：mp4, mov, avi, mkv, webm（自动提取音频）

输出文件：

转录工具生成两个文件：

1. {input_name}.transcript.txt：包含转录文本
2. {input_name}.metadata.json：包含有关转录的元数据

特性：

• 自动语言检测
• 可选的单词级时间戳
• 可选的说话人检测
• 从视频文件中高效提取音频
• 长文件的进度跟踪
• 详细的元数据，包括：
  • 持续时间
  • 语言检测置信度
  • 处理时间
  • 说话人变化（启用时）

用法

要将此 MCP 与 Goose 一起使用，只需让 Goose 与您交谈或开始语音对话：

1. 通过说类似以下内容开始对话：

   "Let's talk using voice"
   "Can we have a voice conversation?"
   "I'd like to speak instead of typing"
   

2. Goose 将自动启动语音界面并开始侦听您的语音输入。

3. 当 Goose 响应时，它会大声说出响应，然后自动侦听您的下一个输入。

4. 对话自然地继续进行，交替进行说话和聆听，就像与人交谈一样。

无需调用特定函数或使用特殊命令 - 只需让 Goose 交谈并开始自然地说话。

UI 特性

新的基于 PyQt 的 UI 包括：

• 现代深色主题：时尚、专业的外观
• 音频可视化：音频输入的动态可视化
• 语音选择：从 54+ 语音选项中选择
• 语音持久性：您的语音首选项在会话之间保存
• 动画效果：流畅的动画和视觉反馈
• 状态指示器：系统状态的清晰指示（就绪、正在侦听、正在处理）

配置

用户首选项存储在 ~/.config/speech-mcp/config.json 中，包括：

• 选定的 TTS 语音
• TTS 引擎首选项
• 语音速度
• 语言代码
• UI 主题设置

您还可以通过环境变量设置首选项，例如：

• SPEECH_MCP_TTS_VOICE - 设置您首选的语音
• SPEECH_MCP_TTS_ENGINE - 设置您首选的 TTS 引擎

故障排除

如果您遇到扩展冻结或无响应的问题：

1. 检查日志：查看 src/speech_mcp/ 中的日志文件以获取详细的错误消息。
2. 重置状态：如果扩展似乎卡住，请尝试删除 src/speech_mcp/speech_state.json 或将所有状态设置为 false。
3. 使用直接命令：不要使用 uv run speech-mcp，而是直接使用已安装的包 speech-mcp。
4. 检查音频设备：确保您的麦克风已正确配置并且 Python 可以访问。
5. 验证依赖项：确保所有必需的依赖项都已正确安装。

常见的 PortAudio 问题

“PyAudio 安装失败”或“找不到 portaudio.h 文件”

这通常意味着 PortAudio 未安装或在您的系统中找不到：

• macOS:

  brew install portaudio
  export LDFLAGS="-L/usr/local/lib"
  export CPPFLAGS="-I/usr/local/include"
  pip install pyaudio
  

• Linux: 确保您已安装开发包：

  # 对于 Debian/Ubuntu
  sudo apt-get install portaudio19-dev python3-dev
  pip install pyaudio
  
  # 对于 Fedora
  sudo dnf install portaudio-devel
  pip install pyaudio
  

“找不到音频设备”或“没有可用的默认输入设备”

• 检查您的麦克风是否已正确连接
• 验证您的系统是否在您的声音设置中识别麦克风
• 如果您有多个音频设备，请尝试在代码中选择特定的设备索引

更新日志

有关最近的改进和版本历史的详细列表，请参见 更新日志。

技术细节

语音转文本

MCP 使用 faster-whisper 进行语音识别：

• 使用“base”模型以获得准确性和速度的良好平衡
• 在本地处理音频，而无需将数据发送到外部服务
• 自动检测用户何时完成说话
• 提供比原始 Whisper 实现更好的性能

文本转语音

MCP 支持多种文本转语音引擎：

默认：pyttsx3

• 使用您计算机上可用的系统语音
• 开箱即用，无需额外设置
• 语音质量和自定义有限

可选：Kokoro TTS

• 具有多种语音的高质量神经文本转语音
• 轻量级模型（82M 参数），可在 CPU 上高效运行
• 多种语音风格和语言
• 要安装：python scripts/install_kokoro.py

关于语音模型的说明：语音模型是由 Kokoro 加载的 .pt 文件（PyTorch 模型）。每个语音模型的大小约为 523 KB，并在需要时自动下载。

语音持久性：选定的语音会自动保存到配置文件 (~/.config/speech-mcp/config.json)，并在会话之间记住。这允许用户设置一次他们喜欢的语音，并使其始终如一地使用。

可用的 Kokoro 语音

Speech MCP 通过 Kokoro TTS 支持 54+ 高质量语音模型。有关可用语音和语言选项的完整列表，请访问 Kokoro GitHub 存储库。

许可证

MIT 许可证