Initial commit
This commit is contained in:
Aodhan Collins
326
docs/tts/TTS_DEBUGGING_GUIDE.md
Normal file
326
docs/tts/TTS_DEBUGGING_GUIDE.md
Normal file
@@ -0,0 +1,326 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user