# TTS Voice Selection Debugging Guide

## Overview

Comprehensive debugging has been added to track the entire TTS voice selection flow from settings to playback.

## Debug Logging System

### 1. Settings Panel (SettingsPanel.tsx)

**On Mount:**
```
⚙️  SettingsPanel mounted
📥 Current ttsVoice from store: browser:Google US English
💾 LocalStorage contents: {"state":{"ttsVoice":"browser:Google US English",...},...}
🔊 Loaded 23 browser voices
```

**On Voice Change:**
```
🎛️  Settings: Voice selection changed to: browser:Microsoft David
🎙️ Settings Store: Saving TTS voice: browser:Microsoft David
💾 LocalStorage after change: {"state":{"ttsVoice":"browser:Microsoft David",...},...}
```

### 2. TTS Controls (TTSControls.tsx)

**On Component Load:**
```
🔊 TTSControls: Current TTS voice from store: browser:Google US English
```

**On Play Button Click:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎬 TTSControls: Starting TTS playback
📥 Raw voice from store: browser:Google US English
🔑 ElevenLabs API Key present: false
🎤 Processed voice ID: browser:Google US English
📝 Text to speak: This is a test message...
✅ TTS playback started successfully
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### 3. TTS Manager (tts.ts)

**speak() Method:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎵 TTS Manager: speak() called
📥 Input options: {voiceId: "browser:Google US English", provider: "browser", volume: 1}
✅ Detected browser voice: Google US English
🎯 Final provider: browser
🎯 Final voice ID: Google US English
➡️  Routing to Browser TTS
```

**Browser TTS Setup:**
```
🔧 Browser TTS: Setting up utterance
📊 Utterance settings: {rate: 1, pitch: 1, volume: 1}
🔍 Browser TTS: Searching for voice: Google US English
📋 Browser TTS: 23 voices available:
   1. Google US English | URI: Google US English | Lang: en-US
   2. Microsoft David | URI: Microsoft David | Lang: en-US
   3. Microsoft Zira | URI: Microsoft Zira | Lang: en-US
   ... [more voices]
🎯 Searching for match with: Google US English
✅ MATCH FOUND: Google US English (Google US English)
🎤 Setting utterance voice to: Google US English
✅ Voice successfully assigned to utterance
🎙️  Final utterance voice: Google US English
▶️  Starting speech synthesis...
✅ Browser TTS: Playback ended
```

## How to Use Debug Logs

### Step 1: Open Browser Console

1. Open EVE app
2. Press **F12** to open DevTools
3. Go to **Console** tab

### Step 2: Test Voice Selection

1. Open Settings (⚙️ icon)
2. Enable TTS
3. Select a voice from dropdown
4. Watch console for:
   - `🎛️  Settings: Voice selection changed`
   - `🎙️ Settings Store: Saving TTS voice`
   - `💾 LocalStorage after change`

### Step 3: Test Playback

1. Send a message to EVE
2. Click 🔊 speaker icon
3. Watch console for full flow:
   - TTSControls logs
   - TTS Manager logs
   - Browser TTS logs

## Common Issues & Solutions

### Issue 1: Voice Not Saving

**Symptoms:**
```
🎛️  Settings: Voice selection changed to: browser:Microsoft David
🎙️ Settings Store: Saving TTS voice: browser:Microsoft David
💾 LocalStorage after change: {"state":{"ttsVoice":"default",...},...}
```

**Problem:** LocalStorage shows "default" instead of selected voice

**Solutions:**
- Check browser permissions for localStorage
- Try incognito/private mode
- Clear localStorage and try again: `localStorage.clear()`

### Issue 2: Voice Not Loading from Store

**Symptoms:**
```
⚙️  SettingsPanel mounted
📥 Current ttsVoice from store: default
💾 LocalStorage contents: null
```

**Problem:** Store not loading from localStorage

**Solutions:**
- Check Zustand persist middleware is working
- Verify localStorage permissions
- Check browser console for errors

### Issue 3: Wrong Voice Used

**Symptoms:**
```
🔍 Browser TTS: Searching for voice: Google US English
📋 Browser TTS: 23 voices available:
   ... [list of voices]
❌ Voice not found in available voices: Google US English
⚠️  Will use system default voice instead
```

**Problem:** Voice ID doesn't match available voices

**Solutions:**
- Check exact voice URI in available voices list
- Some voices may not be available on all systems
- Try a different voice
- Check voice name vs voiceURI mismatch

### Issue 4: Prefix Not Stripped

**Symptoms:**
```
🎵 TTS Manager: speak() called
📥 Input options: {voiceId: "browser:Google US English", ...}
⚠️  No prefix detected, using as-is: browser:Google US English
```

**Problem:** Prefix detection not working

**Check:**
- Voice ID should start with "browser:" or "elevenlabs:"
- If not, check SettingsPanel dropdown values

### Issue 5: Default Voice Always Used

**Symptoms:**
```
🎬 TTSControls: Starting TTS playback
📥 Raw voice from store: default
```

**Problem:** Store contains "default" value

**Solutions:**
1. Check if voice was actually selected in settings
2. Verify dropdown onChange is firing
3. Check localStorage was updated
4. Try selecting voice again

## Manual Debugging Commands

### Check Current Settings

```javascript
// In browser console
JSON.parse(localStorage.getItem('eve-settings'))
```

### Force Set Voice

```javascript
// In browser console
const settings = JSON.parse(localStorage.getItem('eve-settings'))
settings.state.ttsVoice = "browser:Google US English"
localStorage.setItem('eve-settings', JSON.stringify(settings))
location.reload()
```

### List Available Voices

```javascript
// In browser console
window.speechSynthesis.getVoices().forEach((v, i) => {
  console.log(`${i + 1}. ${v.name} | ${v.voiceURI} | ${v.lang}`)
})
```

### Test Voice Directly

```javascript
// In browser console
const utterance = new SpeechSynthesisUtterance("Testing voice")
const voices = window.speechSynthesis.getVoices()
utterance.voice = voices[0] // Try different indices
window.speechSynthesis.speak(utterance)
```

## Log Analysis Guide

### Healthy Flow

✅ Complete successful flow:
```
1. 🎛️  Settings: Voice selection changed
2. 🎙️ Settings Store: Saving TTS voice
3. 💾 LocalStorage shows correct voice
4. 🔊 TTSControls: Current TTS voice matches
5. 🎵 TTS Manager receives correct voice
6. ✅ Detected browser voice (prefix stripped)
7. 📋 Voice found in available list
8. ✅ MATCH FOUND
9. ✅ Voice successfully assigned
10. ▶️  Starting speech synthesis
11. ✅ Playback ended
```

### Broken Flow Examples

❌ **Voice not saving:**
```
1. 🎛️  Settings: Voice selection changed to X
2. 🎙️ Settings Store: Saving TTS voice: X
3. 💾 LocalStorage still shows "default" ❌
```

❌ **Voice not found:**
```
1. 🔍 Browser TTS: Searching for voice: X
2. 📋 Browser TTS: [list of voices]
3. ❌ Voice not found in available voices ❌
4. ⚠️  Will use system default voice instead
```

❌ **Wrong voice passed:**
```
1. 📥 Raw voice from store: default ❌
2. Should be: browser:SomeVoice
```

## Platform-Specific Notes

### Linux
- May have fewer voices available
- eSpeak voices common
- Check: `apt list --installed | grep speech`

### macOS
- Many high-quality voices
- "Alex" is common default
- Check: System Preferences > Accessibility > Speech

### Windows
- Microsoft voices (David, Zira, etc.)
- Check: Settings > Time & Language > Speech

## Expected Log Volume

**Normal operation:**
- Settings change: ~5-10 log lines
- Play button click: ~20-40 log lines
- Component mount: ~5 log lines

**Total per test:** ~30-55 log lines

## Disabling Debug Logs

To remove debug logs in production:

1. Search for `console.log` in:
   - `src/components/SettingsPanel.tsx`
   - `src/components/TTSControls.tsx`
   - `src/lib/tts.ts`
   - `src/stores/settingsStore.ts`

2. Comment out or remove debug statements

3. Or wrap in development check:
   ```typescript
   if (import.meta.env.DEV) {
     console.log('Debug message')
   }
   ```

## Getting Help

If voice selection still doesn't work after checking logs:

1. Copy full console output
2. Check localStorage contents
3. List available voices
4. Note operating system & browser
5. Report issue with all above information

---

**Status**: Debug logging active  
**Version**: v0.2.0-rc  
**Date**: October 5, 2025