| Name | voice-mode JSON |
| Version |
6.0.5
JSON |
| download |
| home_page | None |
| Summary | VoiceMode - Voice interaction capabilities for AI assistants (formerly voice-mcp) |
| upload_time | 2025-10-26 23:13:39 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
ai
livekit
llm
mcp
speech
stt
tts
voice
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# VoiceMode
> **Install via:** `uv tool install voice-mode` | [getvoicemode.com](https://getvoicemode.com)
[](https://pepy.tech/project/voice-mode)
[](https://pepy.tech/project/voice-mode)
[](https://pepy.tech/project/voice-mode)
Natural voice conversations for AI assistants. VoiceMode brings human-like voice interactions to Claude Code, AI code editors through the Model Context Protocol (MCP).
## 🖥️ Compatibility
**Runs on:** Linux • macOS • Windows (WSL) • NixOS | **Python:** 3.10+
## ✨ Features
- **🎙️ Natural Voice Conversations** with Claude Code - ask questions and hear responses
- **🗣️ Supports local Voice Models** - works with any OpenAI API compatible STT/TTS services
- **⚡ Real-time** - low-latency voice interactions with automatic transport selection
- **🔧 MCP Integration** - seamless with Claude Code (and other MCP clients)
- **🎯 Silence detection** - automatically stops recording when you stop speaking (no more waiting!)
- **🔄 Multiple transports** - local microphone or LiveKit room-based communication
## 🎯 Simple Requirements
**All you need to get started:**
1. **🎤 Computer with microphone and speakers**
2. **🔑 OpenAI API Key** (Recommended, if only as a backup for local services)
## Quick Start
### Install VoiceMode and dependencies with UV (Recommended)
- Linux (fedora, debian/ubuntu)
- macOS
- Windows WSL
```bash
# Install VoiceMode MCP python package and dependencies
curl -LsSf https://astral.sh/uv/install.sh | sh
uvx voice-mode-install
# While local voice services can be installed automatically, we recommend
# providing an OpenAI API key as a fallback in case local services are unavailable
export OPENAI_API_KEY=your-openai-key # Optional but recommended
# Add VoiceMode to Claude
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
# Start a voice conversation
claude converse
```
### Manual Installation
For manual setup steps, see the [Getting Started Guide](docs/tutorials/getting-started.md).
## 🎬 Demo
Watch VoiceMode in action with Claude Code:
[](https://www.youtube.com/watch?v=cYdwOD_-dQc)
The `converse` function makes voice interactions natural - it automatically waits for your response by default, creating a real conversation flow.
## Installation
### Prerequisites
- Python >= 3.10
- [Astral UV](https://github.com/astral-sh/uv) - Package manager (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`)
- OpenAI API Key (or compatible service)
#### System Dependencies
<details>
<summary><strong>Ubuntu/Debian</strong></summary>
```bash
sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev
```
**Note for WSL2 users**: WSL2 requires additional audio packages (pulseaudio, libasound2-plugins) for microphone access.
</details>
<details>
<summary><strong>Fedora/RHEL</strong></summary>
```bash
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
```
</details>
<details>
<summary><strong>macOS</strong></summary>
```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install dependencies
brew install ffmpeg node portaudio
```
</details>
<details>
<summary><strong>Windows (WSL)</strong></summary>
Follow the Ubuntu/Debian instructions above within WSL.
</details>
<details>
<summary><strong>NixOS</strong></summary>
VoiceMode includes a flake.nix with all required dependencies. You can either:
1. **Use the development shell** (temporary):
```bash
nix develop github:mbailey/voicemode
```
2. **Install system-wide** (see Installation section below)
</details>
### Quick Install
```bash
# Using Claude Code (recommended)
claude mcp add --scope user voicemode uvx --refresh voice-mode
```
### Configuration for AI Coding Assistants
> 📖 **Looking for detailed setup instructions?** Check our comprehensive [Getting Started Guide](docs/tutorials/getting-started.md) for step-by-step instructions!
Below are quick configuration snippets. For full installation and setup instructions, see the integration guides above.
<details>
<summary><strong>Claude Code (CLI)</strong></summary>
```bash
claude mcp add --scope user voicemode -- uvx --refresh voice-mode
```
Or with environment variables:
```bash
claude mcp add --scope user --env OPENAI_API_KEY=your-openai-key voicemode -- uvx --refresh voice-mode
```
</details>
### Alternative Installation Options
<details>
<summary><strong>From source</strong></summary>
```bash
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
```
</details>
<details>
<summary><strong>NixOS Installation Options</strong></summary>
**1. Install with nix profile (user-wide):**
```bash
nix profile install github:mbailey/voicemode
```
**2. Add to NixOS configuration (system-wide):**
```nix
# In /etc/nixos/configuration.nix
environment.systemPackages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
```
**3. Add to home-manager:**
```nix
# In home-manager configuration
home.packages = [
(builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];
```
**4. Run without installing:**
```bash
nix run github:mbailey/voicemode
```
</details>
## Configuration
- 📖 **[Getting Started](docs/tutorials/getting-started.md)** - Step-by-step setup guide
- 🔧 **[Configuration Reference](docs/guides/configuration.md)** - All environment variables
### Quick Setup
The only required configuration is your OpenAI API key:
```bash
export OPENAI_API_KEY="your-key"
```
## Local STT/TTS Services
For privacy-focused or offline usage, VoiceMode supports local speech services:
- **[Whisper.cpp](docs/guides/whisper-setup.md)** - Local speech-to-text with OpenAI-compatible API
- **[Kokoro](docs/guides/kokoro-setup.md)** - Local text-to-speech with multiple voice options
These services provide the same API interface as OpenAI, allowing seamless switching between cloud and local processing.
## Troubleshooting
### Common Issues
- **No microphone access**: Check system permissions for terminal/application
- **WSL2 Users**: Additional audio packages (pulseaudio, libasound2-plugins) required for microphone access
- **UV not found**: Install with `curl -LsSf https://astral.sh/uv/install.sh | sh`
- **OpenAI API error**: Verify your `OPENAI_API_KEY` is set correctly
- **No audio output**: Check system audio settings and available devices
### Audio Saving
To save all audio files (both TTS output and STT input):
```bash
export VOICEMODE_SAVE_AUDIO=true
```
Audio files are saved to: `~/.voicemode/audio/YYYY/MM/` with timestamps in the filename.
## Documentation
📚 **[Read the full documentation at voice-mode.readthedocs.io](https://voice-mode.readthedocs.io)**
### Getting Started
- **[Getting Started](docs/tutorials/getting-started.md)** - Step-by-step setup for all supported tools
- **[Configuration Guide](docs/guides/configuration.md)** - Complete environment variable reference
### Development
- **[Development Setup](docs/tutorials/development-setup.md)** - Local development guide
### Service Guides
- **[Whisper.cpp Setup](docs/guides/whisper-setup.md)** - Local speech-to-text configuration
- **[Kokoro Setup](docs/guides/kokoro-setup.md)** - Local text-to-speech configuration
- **[LiveKit Integration](docs/guides/livekit-setup.md)** - Real-time voice communication
## Links
- **Website**: [getvoicemode.com](https://getvoicemode.com)
- **Documentation**: [voice-mode.readthedocs.io](https://voice-mode.readthedocs.io)
- **GitHub**: [github.com/mbailey/voicemode](https://github.com/mbailey/voicemode)
- **PyPI**: [pypi.org/project/voice-mode](https://pypi.org/project/voice-mode/)
### Community
- **Twitter/X**: [@getvoicemode](https://twitter.com/getvoicemode)
- **YouTube**: [@getvoicemode](https://youtube.com/@getvoicemode)
## See Also
- 🚀 [Getting Started](docs/tutorials/getting-started.md) - Setup instructions for all supported tools
- 🔧 [Configuration Reference](docs/guides/configuration.md) - Environment variables and options
- 🎤 [Local Services Setup](docs/guides/kokoro-setup.md) - Run TTS/STT locally for privacy
## License
MIT - A [Failmode](https://failmode.com) Project
---
mcp-name: com.failmode/voicemode
Raw data
{
"_id": null,
"home_page": null,
"name": "voice-mode",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, livekit, llm, mcp, speech, stt, tts, voice",
"author": null,
"author_email": "mbailey <mbailey@example.com>",
"download_url": "https://files.pythonhosted.org/packages/80/95/d403e6f0d8efb3789e30b8c7ecf1d863e75b78ccbe0c4e110337a04ef620/voice_mode-6.0.5.tar.gz",
"platform": null,
"description": "# VoiceMode\n\n\n> **Install via:** `uv tool install voice-mode` | [getvoicemode.com](https://getvoicemode.com)\n\n[](https://pepy.tech/project/voice-mode)\n[](https://pepy.tech/project/voice-mode)\n[](https://pepy.tech/project/voice-mode)\n\nNatural voice conversations for AI assistants. VoiceMode brings human-like voice interactions to Claude Code, AI code editors through the Model Context Protocol (MCP).\n\n## \ud83d\udda5\ufe0f Compatibility\n\n**Runs on:** Linux \u2022 macOS \u2022 Windows (WSL) \u2022 NixOS | **Python:** 3.10+\n\n## \u2728 Features\n\n- **\ud83c\udf99\ufe0f Natural Voice Conversations** with Claude Code - ask questions and hear responses\n- **\ud83d\udde3\ufe0f Supports local Voice Models** - works with any OpenAI API compatible STT/TTS services\n- **\u26a1 Real-time** - low-latency voice interactions with automatic transport selection\n- **\ud83d\udd27 MCP Integration** - seamless with Claude Code (and other MCP clients)\n- **\ud83c\udfaf Silence detection** - automatically stops recording when you stop speaking (no more waiting!)\n- **\ud83d\udd04 Multiple transports** - local microphone or LiveKit room-based communication \n\n## \ud83c\udfaf Simple Requirements\n\n**All you need to get started:**\n\n1. **\ud83c\udfa4 Computer with microphone and speakers**\n2. **\ud83d\udd11 OpenAI API Key** (Recommended, if only as a backup for local services)\n\n## Quick Start\n\n### Install VoiceMode and dependencies with UV (Recommended)\n\n- Linux (fedora, debian/ubuntu) \n- macOS\n- Windows WSL\n\n```bash\n# Install VoiceMode MCP python package and dependencies\ncurl -LsSf https://astral.sh/uv/install.sh | sh \nuvx voice-mode-install\n\n# While local voice services can be installed automatically, we recommend\n# providing an OpenAI API key as a fallback in case local services are unavailable\nexport OPENAI_API_KEY=your-openai-key # Optional but recommended\n\n# Add VoiceMode to Claude\nclaude mcp add --scope user voicemode -- uvx --refresh voice-mode\n\n# Start a voice conversation\nclaude converse\n```\n\n### Manual Installation\n\nFor manual setup steps, see the [Getting Started Guide](docs/tutorials/getting-started.md).\n\n## \ud83c\udfac Demo\n\nWatch VoiceMode in action with Claude Code:\n\n[](https://www.youtube.com/watch?v=cYdwOD_-dQc)\n\nThe `converse` function makes voice interactions natural - it automatically waits for your response by default, creating a real conversation flow.\n\n## Installation\n\n### Prerequisites\n- Python >= 3.10\n- [Astral UV](https://github.com/astral-sh/uv) - Package manager (install with `curl -LsSf https://astral.sh/uv/install.sh | sh`)\n- OpenAI API Key (or compatible service)\n\n#### System Dependencies\n\n<details>\n<summary><strong>Ubuntu/Debian</strong></summary>\n\n```bash\nsudo apt update\nsudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev\n```\n\n**Note for WSL2 users**: WSL2 requires additional audio packages (pulseaudio, libasound2-plugins) for microphone access.\n</details>\n\n<details>\n<summary><strong>Fedora/RHEL</strong></summary>\n\n```bash\nsudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel\n```\n</details>\n\n<details>\n<summary><strong>macOS</strong></summary>\n\n```bash\n# Install Homebrew if not already installed\n/bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n\n# Install dependencies\nbrew install ffmpeg node portaudio\n```\n</details>\n\n<details>\n<summary><strong>Windows (WSL)</strong></summary>\n\nFollow the Ubuntu/Debian instructions above within WSL.\n</details>\n\n<details>\n<summary><strong>NixOS</strong></summary>\n\nVoiceMode includes a flake.nix with all required dependencies. You can either:\n\n1. **Use the development shell** (temporary):\n```bash\nnix develop github:mbailey/voicemode\n```\n\n2. **Install system-wide** (see Installation section below)\n</details>\n\n### Quick Install\n\n```bash\n# Using Claude Code (recommended)\nclaude mcp add --scope user voicemode uvx --refresh voice-mode\n```\n\n### Configuration for AI Coding Assistants\n\n> \ud83d\udcd6 **Looking for detailed setup instructions?** Check our comprehensive [Getting Started Guide](docs/tutorials/getting-started.md) for step-by-step instructions!\n\nBelow are quick configuration snippets. For full installation and setup instructions, see the integration guides above.\n\n<details>\n<summary><strong>Claude Code (CLI)</strong></summary>\n\n```bash\nclaude mcp add --scope user voicemode -- uvx --refresh voice-mode\n```\n\nOr with environment variables:\n```bash\nclaude mcp add --scope user --env OPENAI_API_KEY=your-openai-key voicemode -- uvx --refresh voice-mode\n```\n</details>\n\n### Alternative Installation Options\n\n<details>\n<summary><strong>From source</strong></summary>\n\n```bash\ngit clone https://github.com/mbailey/voicemode.git\ncd voicemode\nuv tool install -e .\n```\n</details>\n\n<details>\n<summary><strong>NixOS Installation Options</strong></summary>\n\n**1. Install with nix profile (user-wide):**\n```bash\nnix profile install github:mbailey/voicemode\n```\n\n**2. Add to NixOS configuration (system-wide):**\n```nix\n# In /etc/nixos/configuration.nix\nenvironment.systemPackages = [\n (builtins.getFlake \"github:mbailey/voicemode\").packages.${pkgs.system}.default\n];\n```\n\n**3. Add to home-manager:**\n```nix\n# In home-manager configuration\nhome.packages = [\n (builtins.getFlake \"github:mbailey/voicemode\").packages.${pkgs.system}.default\n];\n```\n\n**4. Run without installing:**\n```bash\nnix run github:mbailey/voicemode\n```\n</details>\n\n## Configuration\n\n- \ud83d\udcd6 **[Getting Started](docs/tutorials/getting-started.md)** - Step-by-step setup guide\n- \ud83d\udd27 **[Configuration Reference](docs/guides/configuration.md)** - All environment variables\n\n### Quick Setup\n\nThe only required configuration is your OpenAI API key:\n\n```bash\nexport OPENAI_API_KEY=\"your-key\"\n```\n\n## Local STT/TTS Services\n\nFor privacy-focused or offline usage, VoiceMode supports local speech services:\n\n- **[Whisper.cpp](docs/guides/whisper-setup.md)** - Local speech-to-text with OpenAI-compatible API\n- **[Kokoro](docs/guides/kokoro-setup.md)** - Local text-to-speech with multiple voice options\n\nThese services provide the same API interface as OpenAI, allowing seamless switching between cloud and local processing.\n\n## Troubleshooting\n\n### Common Issues\n\n- **No microphone access**: Check system permissions for terminal/application\n - **WSL2 Users**: Additional audio packages (pulseaudio, libasound2-plugins) required for microphone access\n- **UV not found**: Install with `curl -LsSf https://astral.sh/uv/install.sh | sh`\n- **OpenAI API error**: Verify your `OPENAI_API_KEY` is set correctly\n- **No audio output**: Check system audio settings and available devices\n\n### Audio Saving\n\nTo save all audio files (both TTS output and STT input):\n\n```bash\nexport VOICEMODE_SAVE_AUDIO=true\n```\n\nAudio files are saved to: `~/.voicemode/audio/YYYY/MM/` with timestamps in the filename.\n\n## Documentation\n\n\ud83d\udcda **[Read the full documentation at voice-mode.readthedocs.io](https://voice-mode.readthedocs.io)**\n\n### Getting Started\n\n- **[Getting Started](docs/tutorials/getting-started.md)** - Step-by-step setup for all supported tools\n- **[Configuration Guide](docs/guides/configuration.md)** - Complete environment variable reference\n\n### Development\n\n- **[Development Setup](docs/tutorials/development-setup.md)** - Local development guide\n\n### Service Guides\n\n- **[Whisper.cpp Setup](docs/guides/whisper-setup.md)** - Local speech-to-text configuration\n- **[Kokoro Setup](docs/guides/kokoro-setup.md)** - Local text-to-speech configuration\n- **[LiveKit Integration](docs/guides/livekit-setup.md)** - Real-time voice communication\n\n## Links\n\n- **Website**: [getvoicemode.com](https://getvoicemode.com)\n- **Documentation**: [voice-mode.readthedocs.io](https://voice-mode.readthedocs.io)\n- **GitHub**: [github.com/mbailey/voicemode](https://github.com/mbailey/voicemode)\n- **PyPI**: [pypi.org/project/voice-mode](https://pypi.org/project/voice-mode/)\n\n### Community\n\n- **Twitter/X**: [@getvoicemode](https://twitter.com/getvoicemode)\n- **YouTube**: [@getvoicemode](https://youtube.com/@getvoicemode)\n\n## See Also\n\n- \ud83d\ude80 [Getting Started](docs/tutorials/getting-started.md) - Setup instructions for all supported tools\n- \ud83d\udd27 [Configuration Reference](docs/guides/configuration.md) - Environment variables and options\n- \ud83c\udfa4 [Local Services Setup](docs/guides/kokoro-setup.md) - Run TTS/STT locally for privacy\n\n## License\n\nMIT - A [Failmode](https://failmode.com) Project\n\n---\nmcp-name: com.failmode/voicemode\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "VoiceMode - Voice interaction capabilities for AI assistants (formerly voice-mcp)",
"version": "6.0.5",
"project_urls": {
"Homepage": "https://github.com/mbailey/voicemode",
"Issues": "https://github.com/mbailey/voicemode/issues",
"Repository": "https://github.com/mbailey/voicemode"
},
"split_keywords": [
"ai",
" livekit",
" llm",
" mcp",
" speech",
" stt",
" tts",
" voice"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "82c16e5b62a49638925142a22b2fb31620beeabd9b932787b3d491ffdd581aca",
"md5": "e27299415504565a18853a223d4f7dec",
"sha256": "fdc59cf008e5efeb93de7bd9acd435989c23e3015bdd58fcc012774f3566fe5b"
},
"downloads": -1,
"filename": "voice_mode-6.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e27299415504565a18853a223d4f7dec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 1526738,
"upload_time": "2025-10-26T23:13:37",
"upload_time_iso_8601": "2025-10-26T23:13:37.062100Z",
"url": "https://files.pythonhosted.org/packages/82/c1/6e5b62a49638925142a22b2fb31620beeabd9b932787b3d491ffdd581aca/voice_mode-6.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "8095d403e6f0d8efb3789e30b8c7ecf1d863e75b78ccbe0c4e110337a04ef620",
"md5": "3759975f71e2cdbad658781d29ac41af",
"sha256": "02e9c6e3225f6583628bff743d248e1dc69d2f5cb2c4e22b2d8e98654ddb0618"
},
"downloads": -1,
"filename": "voice_mode-6.0.5.tar.gz",
"has_sig": false,
"md5_digest": "3759975f71e2cdbad658781d29ac41af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 332572,
"upload_time": "2025-10-26T23:13:39",
"upload_time_iso_8601": "2025-10-26T23:13:39.422247Z",
"url": "https://files.pythonhosted.org/packages/80/95/d403e6f0d8efb3789e30b8c7ecf1d863e75b78ccbe0c4e110337a04ef620/voice_mode-6.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 23:13:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mbailey",
"github_project": "voicemode",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "voice-mode"
}
