Troubleshooting Guide

Troubleshooting Guide

This guide helps you diagnose and resolve common issues with VoiceMode.

Quick Diagnostic Flowchart

graph TD
    A[VoiceMode Issue] --> B{Voice working?}
    B -->|No| C[Check Microphone]
    B -->|Yes| D{Speech detected?}

    C --> C1[Check system audio settings]
    C --> C2[Run 'voicemode diag devices']
    C --> C3[Test with 'voicemode converse --debug']

    D -->|No| E[No Speech Detected]
    D -->|Yes| F{Quality issues?}

    E --> E1[Increase min_listen_duration]
    E --> E2[Adjust VAD settings]
    E --> E3[Check microphone levels]

    F -->|Yes| G[Audio Quality]
    F -->|No| H{Slow response?}

    G --> G1[Check TTS/STT provider]
    G --> G2[Verify audio format settings]

    H -->|Yes| I[Performance Issues]
    H -->|No| J[Check logs]

    I --> I1[Check network latency]
    I --> I2[Try local services]

Most Common Issues

1. No Speech Detected

Symptoms: Recording completes but no speech is recognized

Quick Fix: Adjust minimum listen duration to allow more speaking time:

voicemode:converse("message", listen_duration_min=5.0)

Manual Recovery: If audio was saved but STT failed, manually transcribe the recording:

# Check if recording exists and transcribe it
if [ -f ~/.voicemode/audio/latest-STT.wav ]; then
  whisper-cli ~/.voicemode/audio/latest-STT.wav
fi

Prerequisites for manual recovery:

• Audio saving must be enabled (VOICEMODE_SAVE_AUDIO=true, VOICEMODE_SAVE_ALL=true, or VOICEMODE_DEBUG=true)
• Recording file exists at ~/.voicemode/audio/latest-STT.wav (symlink to most recent)

This recovery technique allows you to retrieve the transcription without asking the user to repeat themselves.

2. API Authentication Failed

Symptoms: "Unauthorized" or "Invalid API key" errors Quick Fix: Set OPENAI_API_KEY in your MCP configuration

3. Microphone Not Found

Symptoms: "No audio input device" errors Quick Fix: Run voicemode diag devices and check system permissions

4. Service Not Available

Symptoms: "Failed to connect to TTS/STT service" Quick Fix: Check service status with voicemode whisper status or voicemode kokoro status

5. Poor Audio Quality

Symptoms: Garbled or robotic voice output Quick Fix: Verify audio format with voicemode config get VOICEMODE_TTS_AUDIO_FORMAT

Troubleshooting by Category

Voice Interaction Issues

• No Speech Detected - Recording but no recognition (coming soon)
• Audio Quality Problems - Poor TTS/STT quality (coming soon)
• Response Delays - Slow processing times (coming soon)

Setup & Configuration

• API Authentication - OpenAI key issues (coming soon)
• Missing Dependencies - FFmpeg, Python packages (coming soon)
• MCP Connection - Claude Code integration (coming soon)

Service Issues

• Provider Selection - Failover and discovery (coming soon)
• Whisper Problems - Local STT service (coming soon)
• Kokoro Problems - Local TTS service (coming soon)
• LiveKit Issues - Room-based communication (coming soon)

Audio Device Problems

• Microphone Access - Permissions and detection (coming soon)
• WSL2 Audio - Windows Subsystem for Linux (coming soon)
• macOS Permissions - Privacy settings (coming soon)

Getting Debug Information

Enable Debug Logging

# For detailed debug output
export VOICEMODE_DEBUG=true

# For VAD (Voice Activity Detection) debugging
export VOICEMODE_VAD_DEBUG=true

# Run with debug flags
voicemode converse --debug

Check System Status

# Show system information
voicemode diag info

# List audio devices
voicemode diag devices

# Check service status
voicemode whisper status
voicemode kokoro status

# View recent logs
voicemode logs --tail 50

Collect Diagnostics for Bug Reports

When reporting issues, include:

1. System info: voicemode diag info
2. Debug logs: Run command with --debug flag
3. Event logs: voicemode logs --tail 100
4. Configuration: voicemode config list

Quick Command Reference

Getting Help

If you can't resolve your issue:

1. Check the GitHub Issues for similar problems
2. Review the documentation
3. File a new issue with diagnostic information

Contributing

Found a solution to a problem not documented here? Please contribute:

1. Add your solution to the appropriate troubleshooting document
2. Update this index if adding a new category
3. Submit a pull request

Your contributions help make VoiceMode better for everyone!