audiobook/TESTING_GUIDE.md

# Testing Guide for AI-Powered Audiobook Features

## ✅ Services Status

Both services are now running:
- **Backend**: http://localhost:8002
- **Frontend**: http://localhost:5173
- **Ollama**: http://localhost:11434 (required for AI features)

## 🎯 How to Test AI Features

### Test 1: AI Speaker Detection (No Markers Needed!)

Open the frontend at http://localhost:5173 and try this text:

```
The old wizard Merlin gazed into his crystal ball with concern. Dark times are coming, he whispered to himself.

A young knight named Arthur entered the chamber. Master Merlin, I heard your summons, he said with determination.

Merlin turned to face him. Arthur, the kingdom needs you now more than ever.

Arthur drew his sword. I am ready to defend our people.

From the shadows, the sorceress Morgana watched silently. She knew the prophecy would unfold exactly as foretold.
```

**What should happen:**
1. Click "Next: Assign voices"
2. The AI should detect: **Merlin**, **Arthur**, **Morgana** (and possibly Narrator)
3. Assign different voices to each character
4. Click "Generate Audiobook"
5. The AI will intelligently split the text so:
   - Narrative descriptions → Narrator voice
   - Merlin's dialogue → Merlin's voice
   - Arthur's dialogue → Arthur's voice
   - Morgana's thoughts → Morgana's voice

### Test 2: Mixed Marked and Unmarked Text

Try this text that combines explicit markers with unmarked dialogue:

```
Alice: Hello there!
Bob: Hi Alice, how are you?
[Narrator] They continued talking in the garden.
Charlie joined them later and smiled warmly.
```

**What should happen:**
- AI detects: Alice, Bob, Narrator, Charlie
- Pattern matching catches Alice, Bob, Narrator from markers
- AI catches Charlie from the unmarked text

### Test 3: Pure Narrative (No Dialogue)

Try this descriptive text:

```
The sun set over the mountains. Birds flew across the orange sky. A gentle breeze rustled through the trees. Peace settled over the valley.
```

**What should happen:**
- AI detects: Narrator (default for pure narrative)
- All text assigned to Narrator voice

### Test 4: Complex Dialogue Scene

Try this more complex scene:

```
The detective examined the evidence carefully. This doesn't add up, she muttered.

Her partner looked over her shoulder. What did you find?

She pointed at the photograph. Look at the timestamp. This photo was taken after the victim was already dead.

The partner's eyes widened. That means someone is lying.

Exactly, the detective replied. And I think I know who.
```

**What should happen:**
- AI detects: Detective, Partner (and possibly Narrator)
- Intelligently assigns dialogue to each character
- Narrative descriptions go to Narrator

## 🔍 Verification

### Check Backend Logs

The backend logs will show which detection method is being used:

```bash
# Look for these log messages:
- "AI detection found X roles"
- "Pattern detection found X roles"
- "Using AI-powered segmentation"
- "Using pattern-based segmentation as fallback"
```

### Test via API Directly

You can also test the API directly:

```bash
# Test role detection
curl -X POST http://localhost:8002/api/tts/roles \
  -H "Content-Type: application/json" \
  -d '{"text": "The wizard spoke. The knight replied."}'

# Expected: Detects "Wizard" and "Knight" without any markers!
```

## 🎭 Voice Options Available

When assigning voices, you have these options:
- **af_bella** - Female, American
- **af_sarah** - Female, American
- **am_adam** - Male, American
- **am_michael** - Male, American
- **bf_emma** - Female, British
- **bf_isabella** - Female, British
- **bm_george** - Male, British
- **bm_lewis** - Male, British

## 🚨 Troubleshooting

### If AI detection isn't working:

1. **Check Ollama is running:**
   ```bash
   curl http://localhost:11434/api/tags
   ```

2. **Check llama3 model is available:**
   ```bash
   ollama list | grep llama3
   ```

3. **If model is missing:**
   ```bash
   ollama pull llama3
   ```

4. **Restart Ollama:**
   ```bash
   # Stop Ollama (Ctrl+C if running in terminal)
   ollama serve
   ```

### If backend isn't responding:

```bash
# Check if backend is running
curl http://localhost:8002/api/health

# If not, restart it
cd backend
source venv/bin/activate
uvicorn main:app --reload --host 0.0.0.0 --port 8002
```

### If frontend isn't loading:

```bash
# Check if frontend is running
curl http://localhost:5173

# If not, restart it
cd frontend
npm run dev
```

## 🎉 What Makes This Powerful

**Before (Pattern-only):**
- Required explicit markers like "Alice:" or "[Narrator]"
- Unmarked text all went to Narrator
- Manual markup was tedious

**After (AI-powered):**
- ✨ Detects characters automatically from context
- ✨ Intelligently assigns dialogue to speakers
- ✨ Handles narrative and dialogue seamlessly
- ✨ No manual markup needed!
- ✨ Still supports explicit markers as fallback

## 📝 Tips for Best Results

1. **Use clear character names** in the narrative (e.g., "The wizard Merlin" instead of just "He")
2. **Include dialogue tags** like "he said", "she replied" to help AI identify speakers
3. **Keep paragraphs focused** on one speaker at a time when possible
4. **Mix narrative and dialogue** for more natural audiobooks
5. **Test with short samples first** to verify voice assignments before generating long audiobooks

Enjoy your powerful AI-driven audiobook generator! 🎙️✨