Voicemode

🚀 语音模式

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

🚀 快速开始

📖 使用其他工具？ 查看我们为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客户端无缝集成。
• 🎯 静音检测：当您停止说话时，自动停止录音（无需再等待！）

🎯 简单要求

开始使用所需的全部条件：

1. 🔑 OpenAI API密钥（或兼容服务）：用于语音转文本和文本转语音。
2. 🎤 配备麦克风和扬声器的计算机 或 ☁️ LiveKit服务器（LiveKit Cloud 或 自建）

🎬 演示

观看语音模式与Claude Code的实际运行效果：

语音模式与Gemini CLI

查看语音模式与Google的Gemini CLI（Claude Code的实现版本）的配合使用效果：

💻 使用示例

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

👨‍💻 编程与开发

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

💡 通用生产力

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

🎯 语音控制功能

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

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

📦 安装指南

前提条件

• 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和Nix
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

📚 详细文档

工具说明

⚠️ 重要提示

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 开发。

_项目统计