# 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:
```bash
curl -X POST http://localhost:8000/api/tts/engines \
  -H "Content-Type: application/json" \
  -d '{"engine": "piper"}'
```

### Via Environment Variable:
```bash
# 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. 🎉