# Troubleshooting Guide

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

- Skill: `tools-only/troubleshooting-guide-5` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/troubleshooting-guide-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/troubleshooting-guide-5/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/troubleshooting-guide-5

---

# Troubleshooting Guide

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

## Quick Diagnostic Flowchart

```mermaid
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:
```python
voicemode:converse("message", listen_duration_min=5.0)
```

**Manual Recovery:** If audio was saved but STT failed, manually transcribe the recording:
```bash
# 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

```bash
# 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

```bash
# 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

| Issue | Command | Purpose |
|-------|---------|---------|
| No audio | `voicemode diag devices` | List available audio devices |
| Test voice | `voicemode converse` | Interactive voice test |
| Service down | `voicemode whisper status` | Check Whisper service |
| API errors | `voicemode config get OPENAI_API_KEY` | Verify API key |
| Debug mode | `export VOICEMODE_DEBUG=true` | Enable detailed logging |

## Getting Help

If you can't resolve your issue:

1. Check the [GitHub Issues](https://github.com/mbailey/voicemode/issues) for similar problems
2. Review the [documentation](https://voicemode.dev)
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!