English Français العربية

dev.voicemode/voicemode

السجل الرسمي الوسائط والتصميم

Natural voice conversations for AI assistants - STT/TTS via MCP

الشيفرة المصدرية التوثيق

ماذا يمكنك أن تفعل مع dev.voicemode/voicemode؟

  • Natural conversations - speak naturally, hear responses immediately
  • Works offline - optional local voice services (Whisper STT, Kokoro TTS)
  • Low latency - fast enough to feel like a real conversation
  • Smart silence detection - stops recording when you stop speaking
  • Privacy options - run entirely locally or use cloud services

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package voice-mode
Claude Code 
claude mcp add voicemode -e 'OPENAI_API_KEY=<your openai_api_key>' -e 'VOICEMODE_DEBUG=<VOICEMODE_DEBUG>' -e 'VOICEMODE_SKIP_TTS=<VOICEMODE_SKIP_TTS>' -e 'VOICEMODE_PREFER_LOCAL=<VOICEMODE_PREFER_LOCAL>' -e 'VOICEMODE_AUDIO_FORMAT=<VOICEMODE_AUDIO_FORMAT>' -e 'VOICEMODE_WHISPER_MODEL=<VOICEMODE_WHISPER_MODEL>' -e 'VOICEMODE_DISABLE_SILENCE_DETECTION=<VOICEMODE_DISABLE_SILENCE_DETECTION>' -- uvx voice-mode==9.0.1
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "voicemode": {
            "command": "uvx",
            "args": [
                "voice-mode==9.0.1"
            ],
            "env": {
                "OPENAI_API_KEY": "<your openai_api_key>",
                "VOICEMODE_DEBUG": "<VOICEMODE_DEBUG>",
                "VOICEMODE_SKIP_TTS": "<VOICEMODE_SKIP_TTS>",
                "VOICEMODE_PREFER_LOCAL": "<VOICEMODE_PREFER_LOCAL>",
                "VOICEMODE_AUDIO_FORMAT": "<VOICEMODE_AUDIO_FORMAT>",
                "VOICEMODE_WHISPER_MODEL": "<VOICEMODE_WHISPER_MODEL>",
                "VOICEMODE_DISABLE_SILENCE_DETECTION": "<VOICEMODE_DISABLE_SILENCE_DETECTION>"
            }
        }
    }
}

متغيرات البيئة

  • OPENAI_API_KEY سري OpenAI API key for cloud-based STT/TTS (optional - local services can be installed)
  • VOICEMODE_DEBUG Enable debug mode with detailed logging (true/false)
  • VOICEMODE_SKIP_TTS Skip TTS and show text only for faster response (true/false)
  • VOICEMODE_PREFER_LOCAL Prefer local services over cloud when available (true/false, default: true)
  • VOICEMODE_AUDIO_FORMAT Audio format: pcm, mp3, wav, flac, aac, opus (default: pcm)
  • VOICEMODE_WHISPER_MODEL Whisper model: tiny, base, small, medium, large (default: base)
  • VOICEMODE_DISABLE_SILENCE_DETECTION Disable silence detection for continuous recording (true/false)

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. VoiceMode
  2. See It In Action
  3. Quick Start
  4. Features
  5. Compatibility
  6. Configuration
  7. Permissions Setup (Optional)
  8. Local Voice Services
  9. Installation Details
  10. Troubleshooting
  11. Documentation
  12. Links
  13. License

VoiceMode

Natural voice conversations with Claude Code (and other MCP capable agents)

VoiceMode enables natural voice conversations with Claude Code. Voice isn't about replacing typing - it's about being available when typing isn't.

Perfect for:

  • Walking to your next meeting
  • Cooking while debugging
  • Giving your eyes a break after hours of screen time
  • Holding a coffee (or a dog)
  • Any moment when your hands or eyes are busy

See It In Action

Quick Start

Requirements: Computer with microphone and speakers

The fastest way for Claude Code users to get started:

# Add the VoiceMode marketplace
claude plugin marketplace add mbailey/voicemode

# Install VoiceMode plugin
claude plugin install voicemode@voicemode

## Install dependencies (CLI, Local Voice Services)

/voicemode:install

# Start talking!
/voicemode:converse
Option 2: Python installer package

Installs dependencies and the VoiceMode Python package.

# Install UV package manager (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the installer (sets up dependencies and local voice services)
uvx voice-mode-install

# Add to Claude Code
claude mcp add --scope user voicemode -- uvx --refresh --from voice-mode voicemode-mcp-launcher

# Optional: Add OpenAI API key as fallback for local services
export OPENAI_API_KEY=your-openai-key

# Start a conversation
claude converse

For manual setup, see the Getting Started Guide.

Features

  • Natural conversations - speak naturally, hear responses immediately
  • Works offline - optional local voice services (Whisper STT, Kokoro TTS)
  • Low latency - fast enough to feel like a real conversation
  • Smart silence detection - stops recording when you stop speaking
  • Privacy options - run entirely locally or use cloud services

Compatibility

Platforms: Linux, macOS, Windows (native or WSL), NixOS Python: 3.10-3.14

Configuration

VoiceMode works out of the box. For customization:

# Set OpenAI API key (if using cloud services)
export OPENAI_API_KEY="your-key"

# Or configure via file
voicemode config edit

See the Configuration Guide for all options.

Permissions Setup (Optional)

To use VoiceMode without permission prompts, add to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__voicemode__converse",
      "mcp__voicemode__service"
    ]
  }
}

See the Permissions Guide for more options.

Local Voice Services

For privacy or offline use, install local speech services:

  • Whisper.cpp - Local speech-to-text
  • Kokoro - Local text-to-speech with multiple voices

These provide the same API as OpenAI, so VoiceMode switches seamlessly between them.

Installation Details

System Dependencies by Platform

Ubuntu/Debian
sudo apt update
sudo apt install -y ffmpeg gcc libasound2-dev libasound2-plugins libportaudio2 portaudio19-dev pulseaudio pulseaudio-utils python3-dev

WSL2 users: The pulseaudio packages above are required for microphone access.

Fedora/RHEL
sudo dnf install alsa-lib-devel ffmpeg gcc portaudio portaudio-devel python3-devel
macOS
brew install ffmpeg node portaudio
NixOS
# Use development shell
nix develop github:mbailey/voicemode

# Or install system-wide
nix profile install github:mbailey/voicemode

Alternative Installation Methods

From source
git clone https://github.com/mbailey/voicemode.git
cd voicemode
uv tool install -e .
NixOS system-wide
# In /etc/nixos/configuration.nix
environment.systemPackages = [
  (builtins.getFlake "github:mbailey/voicemode").packages.${pkgs.system}.default
];

Troubleshooting

ProblemSolution
No microphone accessCheck terminal/app permissions. WSL2 needs pulseaudio packages.
UV not foundRun `curl -LsSf https://astral.sh/uv/install.sh \sh`
OpenAI API errorVerify OPENAI_API_KEY is set correctly
No audio outputCheck system audio settings and available devices
Save Audio for Debugging
export VOICEMODE_SAVE_AUDIO=true
# Files saved to ~/.voicemode/audio/YYYY/MM/

Documentation

Full documentation: voicemode.dev

License

MIT - A Failmode Project

mcp-name: dev.voicemode/voicemode

الأسئلة الشائعة

ما هو dev.voicemode/voicemode؟

Natural voice conversations for AI assistants - STT/TTS via MCP

كيف أثبّت dev.voicemode/voicemode؟

يعمل على جهازك. في Claude Code: claude mcp add voicemode -e 'OPENAI_API_KEY=<your openai_api_key>' -e 'VOICEMODE_DEBUG=<VOICEMODE_DEBUG>' -e 'VOICEMODE_SKIP_TTS=<VOICEMODE_SKIP_TTS>' -e 'VOICEMODE_PREFER_LOCAL=<VOICEMODE_PREFER_LOCAL>' -e 'VOICEMODE_AUDIO_FORMAT=<VOICEMODE_AUDIO_FORMAT>' -e 'VOICEMODE_WHISPER_MODEL=<VOICEMODE_WHISPER_MODEL>' -e 'VOICEMODE_DISABLE_SILENCE_DETECTION=<VOICEMODE_DISABLE_SILENCE_DETECTION>' -- uvx voice-mode==9.0.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج dev.voicemode/voicemode إلى مفتاح API؟

نعم. يتطلب OPENAI_API_KEY، وتضبطها في إعداداته.

هل dev.voicemode/voicemode مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون dev.voicemode/voicemode؟

ينشره mbailey. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.