Initial commit

docs/integrations/elevenlabs/ELEVENLABS_DEBUG_CHECKLIST.md

@@ -0,0 +1,206 @@
+# ElevenLabs Voice ID Debug Checklist
+
+## Current Issue
+
+- **LocalStorage shows**: `"elevenlabs:undefined"`
+- **Error message**: `Voice not found in available voices: "6WkvZo1vwba1zF4N2vlY"`
+- **Problem**: Voice ID is valid (`6WkvZo1vwba1zF4N2vlY`) but not being captured from API
+
+## What to Check in Console
+
+### 1. When Settings Opens (ElevenLabs API Response)
+
+Look for these logs:
+
+```javascript
+🎤 ElevenLabs API Response: {...}
+🎤 First voice object: {...}
+🎤 Voice properties: [...]
+```
+
+**Check:**
+- ✅ Does the first voice object have a `voice_id` property?
+- ✅ Or does it use `voiceId`, `id`, or something else?
+- ✅ What properties are listed?
+
+### 2. Voice Processing
+
+```javascript
+🔍 Processing voice: {
+  name: "...",
+  voice_id: "...",
+  voiceId: "...",
+  id: "...",
+  finalVoiceId: "...",
+  allKeys: [...]
+}
+```
+
+**Check:**
+- ✅ Which property contains the actual voice ID?
+- ✅ Is `finalVoiceId` populated correctly?
+- ⚠️ Are any voices showing `finalVoiceId: undefined`?
+
+### 3. After API Processing
+
+```javascript
+🎵 ElevenLabs voices loaded: 25
+🎵 Sample voice: {...}
+🎵 All voice IDs: ["Rachel: xxx", "Adam: xxx", ...]
+```
+
+**Check:**
+- ✅ How many voices loaded?
+- ✅ Do the voice IDs look valid? (should be long strings like `6WkvZo1vwba1zF4N2vlY`)
+- ⚠️ Are any showing as "Rachel: undefined"?
+
+### 4. Dropdown Options
+
+```javascript
+📋 Sample ElevenLabs dropdown option: {
+  name: "Rachel",
+  voice_id: "...",
+  optionValue: "elevenlabs:..."
+}
+```
+
+**Check:**
+- ✅ Is `voice_id` populated?
+- ✅ Does `optionValue` look correct? (e.g., `elevenlabs:6WkvZo1vwba1zF4N2vlY`)
+- ⚠️ Is it showing `elevenlabs:undefined`?
+
+### 5. When Selecting a Voice
+
+```javascript
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎛️  Settings: Voice dropdown changed
+📥 Selected value: "elevenlabs:6WkvZo1vwba1zF4N2vlY"
+🔍 Value breakdown: {
+  hasPrefix: true,
+  prefix: "elevenlabs",
+  voiceId: "6WkvZo1vwba1zF4N2vlY"
+}
+💾 LocalStorage ttsVoice: "elevenlabs:6WkvZo1vwba1zF4N2vlY"
+```
+
+**Check:**
+- ✅ Is the selected value correct?
+- ✅ Is the voiceId part valid?
+- ⚠️ Is it showing `elevenlabs:undefined`?
+
+## Possible Scenarios
+
+### Scenario 1: Property Name Mismatch
+
+**Symptoms:**
+```
+voice_id: undefined
+voiceId: undefined
+id: "6WkvZo1vwba1zF4N2vlY"  ← Actual ID
+```
+
+**Solution:** API uses `id` instead of `voice_id`
+- Already handled with fallback: `voice.voice_id || voice.voiceId || voice.id`
+
+### Scenario 2: Nested Property
+
+**Symptoms:**
+```
+allKeys: ["voiceSettings", "data", ...]
+// ID might be in voice.data.id or similar
+```
+
+**Solution:** Need to adjust path to voice ID
+
+### Scenario 3: API Response Structure Different
+
+**Symptoms:**
+```
+response.voices undefined
+// Maybe it's response.data.voices or response.items
+```
+
+**Solution:** Adjust API response parsing
+
+### Scenario 4: Async Timing Issue
+
+**Symptoms:**
+- Voices load correctly in console
+- But dropdown options show undefined
+- Race condition between state updates
+
+**Solution:** Add loading state management
+
+## Quick Test Commands
+
+### Check LocalStorage Directly
+
+```javascript
+// In browser console
+const settings = JSON.parse(localStorage.getItem('eve-settings'))
+console.log('TTS Voice:', settings.state.ttsVoice)
+```
+
+### Check ElevenLabs Client Directly
+
+```javascript
+// After opening settings with API key
+const client = window.__elevenLabsClient // If we expose it
+```
+
+## What to Share
+
+Please copy and share:
+
+1. **All 🎤 logs** (ElevenLabs API Response)
+2. **All 🔍 logs** (Voice processing)
+3. **All 🎵 logs** (Final processed voices)
+4. **All 📋 logs** (Dropdown options)
+5. **The full first voice object** from the API
+
+## Expected Good Output
+
+```javascript
+🎤 First voice object: {
+  voice_id: "6WkvZo1vwba1zF4N2vlY",
+  name: "Rachel",
+  category: "premade",
+  labels: {...}
+}
+
+🔍 Processing voice: {
+  name: "Rachel",
+  voice_id: "6WkvZo1vwba1zF4N2vlY",
+  voiceId: "6WkvZo1vwba1zF4N2vlY",
+  id: "6WkvZo1vwba1zF4N2vlY",
+  finalVoiceId: "6WkvZo1vwba1zF4N2vlY",  ✅
+  allKeys: [...]
+}
+
+🎵 All voice IDs: ["Rachel: 6WkvZo1vwba1zF4N2vlY", ...]  ✅
+
+📋 Sample ElevenLabs dropdown option: {
+  name: "Rachel",
+  voice_id: "6WkvZo1vwba1zF4N2vlY",
+  optionValue: "elevenlabs:6WkvZo1vwba1zF4N2vlY"  ✅
+}
+```
+
+## Next Steps Based on Results
+
+**If voice_id is undefined:**
+→ Check the `allKeys` array to find the correct property name
+
+**If voice_id exists but dropdown shows undefined:**
+→ State/rendering issue, check React component re-render
+
+**If API returns empty:**
+→ API key or permissions issue
+
+**If API returns different structure:**
+→ Need to adjust response parsing
+
+---
+
+**Status**: Waiting for console output  
+**Action**: Open Settings and check console logs