Voicemode

翻译 Python

🚀 语音模式

语音模式为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密钥（或兼容服务）

系统依赖

Ubuntu/Debian

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

WSL2用户注意：WSL2需要额外的音频包（pulseaudio、libasound2-plugins）才能访问麦克风。如果遇到问题，请查看我们的 WSL2麦克风访问指南。

Fedora/RHEL

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

macOS

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

# 安装依赖
brew install portaudio ffmpeg

Windows (WSL)

在WSL中遵循上述Ubuntu/Debian的安装说明。

NixOS

语音模式包含一个flake.nix文件，其中包含所有必需的依赖项。你可以选择以下方式之一：

使用开发环境（临时）：

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 Code (CLI)

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

或者使用环境变量：

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

Claude Desktop

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

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

Cline

添加到你的Cline MCP设置中：

Windows：

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

macOS/Linux：

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

Continue

添加到你的 .continue/config.json 文件中：

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

Cursor

添加到 ~/.cursor/mcp.json 文件中：

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

VS Code

添加到你的VS Code MCP配置中：

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

Windsurf

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

Zed

添加到你的Zed settings.json 文件中：

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

Roo Code

打开VS Code设置 (Ctrl/Cmd + ,)
在设置搜索栏中搜索 "roo"
找到 "Roo-veterinaryinc.roo-cline → settings → Mcp_settings.json"
点击 "在settings.json中编辑"
添加语音模式配置：

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

其他安装选项

使用Docker

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

pipx install voice-mode

从源代码安装

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

NixOS安装选项

1. 使用nix profile安装（用户级）：

nix profile install github:mbailey/voicemode

2. 添加到NixOS配置（系统级）：

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

3. 添加到home-manager：

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

4. 不安装直接运行：

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`	进行语音对话 - 说话并可选择听取回复	`message`，`wait_for_response`（默认：true），`listen_duration`（默认：30s），`transport`（自动/本地/LiveKit）
`listen_for_speech`	监听语音并转换为文本	`duration`（默认：5s）
`check_room_status`	检查LiveKit房间状态和参与者	无
`check_audio_devices`	列出可用的音频输入/输出设备	无
`start_kokoro`	启动Kokoro TTS服务	`models_dir`（可选，默认为 `~/Models/kokoro`）
`stop_kokoro`	停止Kokoro TTS服务	无
`kokoro_status`	检查Kokoro TTS服务的状态	无
`install_whisper_cpp`	安装whisper.cpp以实现本地语音识别	`install_dir`，`model`（默认：base.en），`use_gpu`（自动检测）
`install_kokoro_fastapi`	安装kokoro-fastapi以实现本地文本转语音	`install_dir`，`port`（默认：8880），`auto_start`（默认：true）

注意：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音频设置。
迁移指南 - 从旧版本升级。

其他参考

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

📄 许可证

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

_项目统计

0 条评论
分类：翻译

Voicemode

🚀 语音模式

🚀 快速开始

✨ 主要特性

📦 安装指南

前提条件

系统依赖

快速安装

AI编码助手的配置

其他安装选项

💻 使用示例

👨‍💻 编程与开发

💡 通用生产力

🎯 语音控制功能

📚 详细文档

支持的工具

工具说明

配置

快速设置

可选设置

音频格式配置

本地STT/TTS服务

OpenAI API兼容性优势

🔧 技术细节

架构

故障排除

常见问题

调试模式

音频诊断

音频保存

文档

入门指南

开发

服务指南

故障排除

相关链接

社区

其他参考

📄 许可证

0 个评论

相似服务问题

相关AI产品

热议话题 »