audiobook/TTS_ENGINE_QUICK_REFERENCE.md

TTS Engine Quick Reference

🎯 Which Engine Should I Use?

Use Kokoro TTS (Default) if you want:

• ✅ Zero setup - works immediately
• ✅ High quality voices
• ✅ Many voices - 54 voices, 9 languages
• ✅ Multiple languages - English, French, Japanese, Spanish, etc.

Use Piper TTS if you want:

• ✅ Pitch control - adjust voice pitch per character
• ✅ Fast synthesis - quicker generation
• ✅ Lower memory - smaller models
• ⚠️ Manual setup required - one-time voice download

---

🚀 Quick Start

Kokoro TTS (No Setup)

1. Start the app
2. It just works! ✨

Piper TTS (3-Minute Setup)

1. Install Piper: cd backend && ./install_piper.sh
2. Download voices from: https://github.com/rhasspy/piper/releases/tag/v1.2.0
3. Place .onnx and .onnx.json files in backend/piper_models/
4. Done! See backend/PIPER_SETUP.md for details

---

🎛️ How to Switch Engines

In the UI:

1. Go to Voice Assignment screen
2. Click "Kokoro TTS" or "Piper TTS" button
3. Voice dropdown updates automatically

Via API:

curl -X POST http://localhost:8000/api/tts/engines \
  -H "Content-Type: application/json" \
  -d '{"engine": "piper"}'

Via Environment Variable:

# In backend/.env
TTS_ENGINE=piper  # or kokoro

---

🎵 Pitch Control (Piper Only)

Adjust voice pitch per character in semitones:

+12 = Very high (one octave up)
+6  = Child-like
+3  = Slightly higher (feminine)
0   = Original voice
-3  = Slightly lower (masculine)
-6  = Deep voice
-12 = Very deep (one octave down)

Recommended:

• Female characters: +2 to +5
• Male characters: -2 to -5
• Children: +5 to +8

---

📊 Feature Comparison

Feature	Kokoro	Piper
Setup	None	Manual
Quality	⭐⭐⭐⭐⭐	⭐⭐⭐⭐
Speed	Medium	Fast
Voices	54	5+
Languages	9	English
Pitch Control	❌	✅
Memory	500MB	10-50MB

---

🔧 Troubleshooting

"Voice preview failed"

• Kokoro: Check internet connection (first-time model download)
• Piper: Download voice models manually (see PIPER_SETUP.md)

"Voice model not found"

• Download .onnx and .onnx.json files
• Place in backend/piper_models/
• Restart backend server

"Piper not found"

• Run ./install_piper.sh
• Or install from: https://github.com/rhasspy/piper/releases

---

📚 Documentation

• Piper Setup: backend/PIPER_SETUP.md
• Piper Guide: backend/PIPER_TTS_GUIDE.md
• Status: PIPER_STATUS.md
• Full Details: PIPER_TTS_INTEGRATION.md

---

💡 Pro Tips

1. Start with Kokoro - Try it first, it's easier
2. Try Piper for variety - Pitch control adds character depth
3. Mix engines - Use Kokoro for most, Piper for special characters
4. Download multiple voices - More variety in your audiobooks
5. Test voices - Use preview button before generating full audiobook

---

🆘 Need Help?

1. Check backend/PIPER_SETUP.md for setup
2. Run python test_piper_direct.py to test Piper
3. Check backend logs for detailed errors
4. Fall back to Kokoro if Piper has issues

---

Remember: Both engines work great! Kokoro is easier, Piper is more advanced. Choose based on your needs. 🎉