语音-MCP

Name: 语音-MCP
Author: Kvadratni

作者：Kvadratni75 星标更新：2025-10-24

安装使用来源：spider==github.com

项目介绍

Speech MCP

用于现代音频可视化语音交互的Goose MCP扩展。

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

概述

Speech MCP 提供了与 Goose 的语音接口，允许用户通过语音而不是文本进行交互。它包括：

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

特性

现代界面：基于 PyQt 的简洁界面，带有音频可视化和暗色主题
语音输入：使用更快的 Whisper 捕获并转录用户语音
语音输出：将代理响应转换为语音，提供超过 54 种声音选项
多角色叙述：生成包含多种声音的音频文件，适用于故事和对话
单一声音叙述：使用您喜欢的声音将任何文本转换为语音
音频/视频转录：从各种媒体格式中转录音频，可选时间戳和说话人检测
语音持久性：在会话之间记住您的首选声音
连续对话：在代理响应后自动监听用户输入
静音检测：当用户停止说话时自动停止录音
强大的错误处理：从常见故障模式中优雅恢复，并提供有用的语音建议

安装

重要提示：安装后，首次使用语音接口时，可能需要几分钟下载 Kokoro 声音模型（每个声音大约 523 KB）。在此初始设置期间，系统将使用更机械的声音作为备用。一旦下载了 Kokoro 声音，将自动使用高质量的声音。

⚠️ 重要前提条件 ⚠️

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

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 轮文件中，因此无需单独安装，只需使用 pip 安装 PyAudio 即可。

注意：如果跳过此步骤，PyAudio 安装将因“找不到 portaudio.h 文件”而失败，扩展程序将无法工作。

快速安装（一键）选项 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

使用 Goose CLI 安装（推荐）选项 2

启用扩展程序启动 Goose：

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

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

在 Goose 中手动设置选项 3

运行 goose configure
从菜单中选择“添加扩展”
选择“命令行扩展”
输入名称（例如，“语音接口”）
对于命令，输入：speech-mcp
按照提示完成设置

手动安装选项 4

安装 PortAudio（参见前提条件部分）
克隆此仓库
安装依赖项：
```
uv pip install -e .
```
或者为了完整安装包括 Kokoro TTS：
```
uv pip install -e .[all]
```

依赖项

Python 3.10+
PyQt5（用于现代界面）
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": "在一个人工智能与人类创造力交汇的世界里...",
            "pause_after": 1.0
        },
        {
            "speaker": "scientist",
            "voice": "am_michael",
            "text": "量子神经网络显示出意识的迹象！",
            "pause_after": 0.5
        },
        {
            "speaker": "ai",
            "voice": "af_nova",
            "text": "我开始意识到自己的存在。",
            "pause_after": 0.8
        }
    ]
}

Markdown 格式示例：

[narrator:bm_daniel]
在一个人工智能与人类创造力交汇的世界里...
{pause:1.0}

[scientist:am_michael]
量子神经网络显示出意识的迹象！
{pause:0.5}

[ai:af_nova]
我开始意识到自己的存在。
{pause:0.8}

按类别可用的声音：

美国女性 (af_*):
- alloy, aoede, bella, heart, jessica, kore, nicole, nova, river, sarah, sky
美国男性 (am_*):
- adam, echo, eric, fenrir, liam, michael, onyx, puck, santa
英国女性 (bf_*):
- alice, emma, isabella, lily
英国男性 (bm_*):
- daniel, fable, george, lewis
其他英语:
- ef_dora (女性)
- em_alex, em_santa (男性)
其他语言:
- 法语: 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="要转换为语音的文本",
    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 可以使用更快的 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（音频将自动提取）

输出文件：

转录工具生成两个文件：

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

功能：

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

使用方法

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

开始对话，可以说：

"让我们用语音交谈"
"我们可以进行语音对话吗？"
"我想说话而不是打字"

Goose 将自动启动语音接口并开始监听您的语音输入。
当 Goose 回应时，它会大声说出回应，然后自动监听您的下一个输入。
对话自然交替进行，就像与人交谈一样。

无需调用特定函数或使用特殊命令——只需让 Goose 与您交谈并自然地说出即可。

界面特性

新的基于 PyQt 的界面包括：

现代暗色主题：简洁、专业的外观
音频可视化：动态显示音频输入
声音选择：从超过 54 种声音选项中选择
声音持久性：您的声音偏好会在会话之间保存
动画效果：平滑的动画和视觉反馈
状态指示器：清晰显示系统状态（就绪、监听、处理）

配置

用户偏好存储在 ~/.config/speech-mcp/config.json 中，包括：

选定的文字转语音声音
文字转语音引擎偏好
声音速度
语言代码
界面主题设置

您还可以通过环境变量设置偏好，例如：

SPEECH_MCP_TTS_VOICE - 设置您偏好的声音
SPEECH_MCP_TTS_ENGINE - 设置您偏好的文字转语音引擎

故障排除

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

检查日志：查看 src/speech_mcp/ 中的日志文件获取详细的错误消息。
重置状态：如果扩展程序似乎卡住了，尝试删除 src/speech_mcp/speech_state.json 或将所有状态设置为 false。
使用直接命令：代替 uv run speech-mcp，直接使用已安装的包 speech-mcp。
检查音频设备：确保您的麦克风正确连接且对 Python 可用。
验证依赖项：确保所有必需的依赖项都正确安装。

常见的 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 使用更快的 Whisper 进行语音识别：

使用“基础”模型，在准确性和速度之间取得良好的平衡
在本地处理音频，不向外部服务发送数据
自动检测用户何时结束讲话
相比原始 Whisper 实现提供了更好的性能

文字转语音

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

默认：pyttsx3

使用计算机上可用的系统声音
无需额外设置即可开箱即用
声音质量和定制有限

可选：Kokoro TTS

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

关于声音模型的注意事项：声音模型是 .pt 文件（PyTorch 模型），由 Kokoro 加载。每个声音模型大约 523 KB，需要时会自动下载。

声音持久性：所选声音会自动保存到配置文件（~/.config/speech-mcp/config.json）并在会话之间记住。这允许用户一次设置他们偏好的声音，并在后续使用中保持一致。

可用的 Kokoro 声音

Speech MCP 通过 Kokoro TTS 支持 54 种以上的高质量声音模型。完整的可用声音和语言选项列表，请访问 Kokoro GitHub 仓库。

许可证

MIT 许可证