Voicemode

🚀 语音模式

语音模式为AI助手带来自然的语音对话体验。它通过模型上下文协议（MCP），为Claude、ChatGPT等大语言模型（LLMs）赋予类似人类的语音交互能力。

🚀 快速开始

📖 使用其他工具？ 查看我们针对Cursor、VS Code、Gemini CLI等工具的 集成指南！

npm install -g @anthropic-ai/claude-code
curl -LsSf https://astral.sh/uv/install.sh | sh
claude mcp add --scope user voice-mode uvx voice-mode
export OPENAI_API_KEY=your-openai-key
claude converse

✨ 主要特性

• 🎙️ 语音对话：与Claude进行语音交流，提问并听取回复。
• 🔄 多种传输方式：支持使用本地麦克风或基于LiveKit房间的通信方式。
• 🗣️ 兼容OpenAI：可与任何语音识别（STT）/文本转语音（TTS）服务（本地或云端）配合使用。
• ⚡ 实时交互：低延迟语音交互，自动选择传输方式。
• 🔧 MCP集成：与Claude Desktop等MCP客户端无缝集成。
• 🎯 静音检测：当你停止说话时自动停止录音（无需再等待！）

📦 安装指南

前提条件

• Python >= 3.10
• Astral UV：包管理器（使用 curl -LsSf https://astral.sh/uv/install.sh | sh 进行安装）
• OpenAI API密钥（或兼容服务）

系统依赖

sudo apt update
sudo apt install -y python3-dev libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev ffmpeg pulseaudio pulseaudio-utils

sudo dnf install python3-devel alsa-lib-devel portaudio-devel ffmpeg

# 如果尚未安装Homebrew，请先安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install portaudio ffmpeg

nix develop github:mbailey/voicemode

快速安装

# 使用Claude Code（推荐）
claude mcp add --scope user voice-mode uvx voice-mode

# 在NixOS上使用Claude Code
claude mcp add voice-mode nix run github:mbailey/voicemode

# 使用UV
uvx voice-mode

# 使用pip
pip install voice-mode

# 在NixOS上使用Nix
nix run github:mbailey/voicemode

AI编码助手的配置

📖 寻找详细的设置说明？ 查看我们全面的 集成指南，获取每个工具的分步说明！

以下是快速配置片段。完整的安装和设置说明，请参考上述集成指南。

claude mcp add voice-mode -- uvx voice-mode

claude mcp add voice-mode --env OPENAI_API_KEY=your-openai-key -- uvx voice-mode

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "cmd",
      "args": ["/c", "uvx", "voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": ["voice-mode"],
          "env": {
            "OPENAI_API_KEY": "your-openai-key"
          }
        }
      }
    ]
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

{
  "context_servers": {
    "voice-mode": {
      "command": {
        "path": "uvx",
        "args": ["voice-mode"],
        "env": {
          "OPENAI_API_KEY": "your-openai-key"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "voice-mode": {
      "command": "uvx",
      "args": ["voice-mode"],
      "env": {
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

其他安装选项

docker run -it --rm \
  -e OPENAI_API_KEY=your-openai-key \
  --device /dev/snd \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=$DISPLAY \
  ghcr.io/mbailey/voicemode:latest

pipx install voice-mode

git clone https://github.com/mbailey/voicemode.git
cd voicemode
pip install -e .

nix profile install github:mbailey/voicemode

# 在 /etc/nixos/configuration.nix 中
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

# 在home-manager配置中
home.packages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

nix run github:mbailey/voicemode

💻 使用示例

配置完成后，可尝试向Claude发送以下提示：

👨‍💻 编程与开发

• "让我们一起调试这个错误" - 口头解释问题，粘贴代码，并讨论解决方案。
• "帮我讲解这段代码" - 让Claude解释复杂代码，同时你可以提问。
• "让我们一起构思架构" - 通过自然对话设计系统。
• "帮我为这个函数编写测试" - 描述需求并进行口头迭代。

💡 通用生产力

• "让我们进行每日站会" - 练习演讲或整理思路。
• "就[主题]对我进行面试" - 通过问答为面试做准备。
• "做我的橡皮鸭调试伙伴" - 口头解释问题以找到解决方案。

🎯 语音控制功能

• "朗读这条错误信息"（Claude朗读后等待你的回复）
• "给我一个快速总结"（Claude直接朗读，无需等待）
• 使用 converse("message", wait_for_response=False) 进行单向播报。

converse 函数使语音交互自然流畅，默认情况下会自动等待你的回复，营造真实的对话流程。

📚 详细文档

支持的工具

语音模式可与你喜爱的AI编码助手配合使用：

• 🤖 Claude Code - Anthropic官方CLI工具
• 🖥️ Claude Desktop - 桌面应用程序
• 🌟 Gemini CLI - 谷歌的CLI工具
• ⚡ Cursor - 以AI为核心的代码编辑器
• 💻 VS Code - 支持MCP预览
• 🦘 Roo Code - VS Code中的AI开发团队
• 🔧 Cline - 自主编码代理
• ⚡ Zed - 高性能编辑器
• 🏄 Windsurf - Codeium的智能IDE
• 🔄 Continue - 开源AI助手

工具说明

注意：converse 工具是语音交互的主要接口，它将说话和倾听自然地结合在一起。

新增：install_whisper_cpp 和 install_kokoro_fastapi 工具可帮助你在本地设置免费、私密的开源语音服务。详细用法请参阅 安装工具文档。

配置

• 📖 集成指南 - 每个工具的分步设置说明。
• 🔧 配置参考 - 所有环境变量说明。
• 📁 配置示例 - 现成的配置文件。

快速设置

唯一需要配置的是你的OpenAI API密钥：

export OPENAI_API_KEY="your-key"

可选设置

# 自定义STT/TTS服务（兼容OpenAI）
export STT_BASE_URL="http://127.0.0.1:2022/v1"  # 本地Whisper
export TTS_BASE_URL="http://127.0.0.1:8880/v1"  # 本地TTS
export TTS_VOICE="alloy"                        # 语音选择

# 或者使用语音偏好文件（请参阅配置文档）
# 项目级：/your-project/voices.txt 或 /your-project/.voicemode/voices.txt
# 用户级：~/voices.txt 或 ~/.voicemode/voices.txt

# LiveKit（用于基于房间的通信）
# 有关设置指南，请参阅 docs/livekit/
export LIVEKIT_URL="wss://your-app.livekit.cloud"
export LIVEKIT_API_KEY="your-api-key"
export LIVEKIT_API_SECRET="your-api-secret"

# 调试模式
export VOICEMODE_DEBUG="true"

# 保存所有音频（TTS输出和STT输入）
export VOICEMODE_SAVE_AUDIO="true"

# 音频格式配置（默认：pcm）
export VOICEMODE_AUDIO_FORMAT="pcm"         # 选项：pcm, mp3, wav, flac, aac, opus
export VOICEMODE_TTS_AUDIO_FORMAT="pcm"     # 仅覆盖TTS的格式（默认：pcm）
export VOICEMODE_STT_AUDIO_FORMAT="mp3"     # 覆盖STT上传的格式

# 特定格式的质量设置
export VOICEMODE_OPUS_BITRATE="32000"       # Opus比特率（默认：32kbps）
export VOICEMODE_MP3_BITRATE="64k"          # MP3比特率（默认：64k）

音频格式配置

语音模式默认使用 PCM 音频格式进行TTS流式传输，以实现最佳实时性能：

• PCM（TTS默认）：零延迟，最佳流式传输性能，未压缩。
• MP3：广泛兼容，适合上传的良好压缩格式。
• WAV：未压缩，适合本地处理。
• FLAC：无损压缩，适合存档。
• AAC：良好的压缩格式，适用于苹果生态系统。
• Opus：文件小，但不建议用于流式传输（存在质量问题）。

音频格式会根据提供商的能力自动验证，如果需要，会回退到支持的格式。

本地STT/TTS服务

为了保护隐私或实现离线使用，语音模式支持本地语音服务：

• Whisper.cpp - 具有兼容OpenAI API的本地语音识别服务。
• Kokoro - 具有多种语音选项的本地文本转语音服务。

这些服务提供与OpenAI相同的API接口，允许在云端和本地处理之间无缝切换。

OpenAI API兼容性优势

通过严格遵循OpenAI的API标准，语音模式实现了强大的部署灵活性：

• 🔀 透明路由：用户可以在语音模式之外实现自己的API代理或网关，根据自定义逻辑（成本、延迟、可用性等）将请求路由到不同的提供商。
• 🎯 模型选择：部署路由层，为每个请求选择最佳模型，而无需修改语音模式的配置。
• 💰 成本优化：构建智能路由器，在昂贵的云API和免费的本地模型之间进行平衡。
• 🔧 无锁定：只需更改 BASE_URL 即可切换提供商，无需更改代码。

示例：只需将 OPENAI_BASE_URL 设置为指向你的自定义路由器：

export OPENAI_BASE_URL="https://router.example.com/v1"
export OPENAI_API_KEY="your-key"
# 语音模式现在将所有OpenAI API调用发送到你的路由器

OpenAI SDK会自动处理这些操作，无需对语音模式进行配置！

🔧 技术细节

架构

┌─────────────────────┐     ┌──────────────────┐     ┌─────────────────────┐
│   Claude/LLM        │     │  LiveKit Server  │     │  Voice Frontend     │
│   (MCP Client)      │◄────►│  (Optional)     │◄───►│  (Optional)         │
└─────────────────────┘     └──────────────────┘     └─────────────────────┘
         │                            │
         │                            │
         ▼                            ▼
┌─────────────────────┐     ┌──────────────────┐
│  Voice MCP Server   │     │   Audio Services │
│  • converse         │     │  • OpenAI APIs   │
│  • listen_for_speech│◄───►│  • Local Whisper │
│  • check_room_status│     │  • Local TTS     │
│  • check_audio_devices    └──────────────────┘
└─────────────────────┘

故障排除

常见问题

• 无法访问麦克风：检查终端/应用程序的系统权限。
  • WSL2用户：参阅 WSL2麦克风访问指南。
• 未找到UV：使用 curl -LsSf https://astral.sh/uv/install.sh | sh 进行安装。
• OpenAI API错误：验证你的 OPENAI_API_KEY 是否设置正确。
• 无音频输出：检查系统音频设置和可用设备。

调试模式

启用详细日志记录和音频文件保存：

export VOICEMODE_DEBUG=true

调试音频文件将保存到：~/voicemode_recordings/

音频诊断

运行诊断脚本检查你的音频设置：

python scripts/diagnose-wsl-audio.py

该脚本将检查所需的包和音频服务，并提供具体建议。

音频保存

保存所有音频文件（TTS输出和STT输入）：

export VOICEMODE_SAVE_AUDIO=true

音频文件将保存到：~/voicemode_audio/，文件名包含时间戳。

文档

📚 在voice-mode.readthedocs.io阅读完整文档

入门指南

• 集成指南 - 所有支持工具的分步设置说明。
• 配置指南 - 完整的环境变量参考。

开发

• 使用uv/uvx - 使用uv和uvx进行包管理。
• 本地开发 - 开发设置指南。
• 音频格式 - 音频格式配置和迁移。
• 统计仪表板 - 性能监控和指标。

服务指南

• Whisper.cpp设置 - 本地语音识别配置。
• Kokoro设置 - 本地文本转语音配置。
• LiveKit集成 - 实时语音通信。

故障排除

• WSL2麦克风访问 - WSL2音频设置。
• 迁移指南 - 从旧版本升级。

相关链接

• 官网：getvoicemode.com
• 文档：voice-mode.readthedocs.io
• GitHub：github.com/mbailey/voicemode
• PyPI：pypi.org/project/voice-mode
• npm：npmjs.com/package/voicemode

社区

• Discord：加入我们的社区
• Twitter/X：@getvoicemode
• YouTube：@getvoicemode

其他参考

• 🚀 集成指南 - 所有支持工具的设置说明。
• 🔧 配置参考 - 环境变量和选项。
• 🎤 本地服务设置 - 为保护隐私，本地运行TTS/STT服务。
• 🐛 故障排除 - 常见问题及解决方案。

📄 许可证

本项目采用MIT许可证，由 Failmode 发起。

_项目统计