From 7ef969314bc9ab0c4bfeab76c22875bf4c56241a Mon Sep 17 00:00:00 2001 From: Paul Bailey Date: Tue, 9 Dec 2025 11:05:22 +0000 Subject: [PATCH] Add comprehensive testing guide for AI-powered features - Step-by-step testing instructions - Multiple test scenarios with expected results - Troubleshooting section - Tips for best results - Comparison of before/after AI features --- TESTING_GUIDE.md | 197 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 TESTING_GUIDE.md diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md new file mode 100644 index 0000000..4d36fdd --- /dev/null +++ b/TESTING_GUIDE.md @@ -0,0 +1,197 @@ +# 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! 🎙️✨