# Selecting Voices

Voice Mode supports multiple TTS providers with different voices. This guide helps you choose and configure voices for the best experience.

## Available Voices


### Kokoro Voices (Local TTS)
- **af_sky** - Natural female voice
- **af_sarah** - Alternative female voice
- **am_adam** - Natural male voice
- **af_river** - Additional female option
- **am_michael** - Additional male option

### OpenAI Voices
- **alloy** - Balanced, neutral voice (default)
- **nova** - Warm, expressive female voice
- **shimmer** - Bright, energetic female voice
- **fable** - Calm, storytelling voice
- **echo** - Clear, professional voice
- **onyx** - Deep, authoritative male voice

## Voice Selection Strategy

Voice Mode uses a **voice-first selection algorithm**:

1. **Try each preferred voice** in order from `VOICEMODE_VOICES`
2. **Find first healthy endpoint** that supports that voice
3. **Use that voice and endpoint** for TTS

This ensures you get your preferred voice when possible, regardless of which provider supports it.

## Configuring Voice Preferences

### Quick Setup
Add to your `.voicemode.env`:
```bash
# Try Kokoro first, fallback to OpenAI
VOICEMODE_VOICES=af_sky,nova,alloy
```

### Voice-First Examples

**Prefer expressive female voices:**
```bash
VOICEMODE_VOICES=shimmer,nova,af_sky
```

**Prefer male voices:**
```bash
VOICEMODE_VOICES=am_adam,onyx,echo
```

**Local-first setup:**
```bash
VOICEMODE_VOICES=af_sky,am_adam,nova
```

**Cloud-first setup:**
```bash
VOICEMODE_VOICES=nova,shimmer,af_sky
```

## Provider Considerations

### OpenAI (Cloud)
- **Pros**: Reliable, consistent quality, no setup
- **Cons**: Requires API key, costs money, internet dependent
- **Best for**: Quick setup, reliable fallback

### Kokoro (Local)
- **Pros**: Free, private, works offline
- **Cons**: Requires setup, resource intensive
- **Best for**: Privacy, cost control, offline use

## Configuration Hierarchy

Voice preferences follow this priority order:

1. **Environment variables** (`VOICEMODE_VOICES=voice1,voice2`)
2. **Project `.voicemode.env`** files (searched up directory tree)
3. **Global `~/.voicemode/voicemode.env`**
4. **Built-in defaults** (`af_sky,alloy`)

## Testing Voice Selection

You can test specific voices:

```bash
VOICEMODE_VOICES=af_sky voicemode converse
```

## Troubleshooting

**Voice not working?**
1. Verify the provider is healthy
2. Try a different voice as fallback

**Provider switching unexpectedly?**
- Voice-first selection will switch providers to get your preferred voice
- This is intentional behavior for the best voice experience
- Add multiple voices from the same provider if you want to stick to one provider

## Best Practices

1. **Always include fallbacks** - List multiple voices in case one isn't available
2. **Mix providers** - Include both local and cloud voices for flexibility  
3. **Test your setup** - Use `voice_registry()` to verify availability
4. **Project-specific voices** - Use different voices for different types of projects
5. **Consider context** - Professional voices for work, expressive for creative projects
