diff --git a/TTS_ENGINE_QUICK_REFERENCE.md b/TTS_ENGINE_QUICK_REFERENCE.md new file mode 100644 index 0000000..910fb06 --- /dev/null +++ b/TTS_ENGINE_QUICK_REFERENCE.md @@ -0,0 +1,135 @@ +# 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. 🎉