eve-alpha/docs/tts/TTS_DEBUGGING_GUIDE.md

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

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

Force Set Voice

// 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

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

Test Voice Directly

// 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:

   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