audiobook/backend/EASY_PIPER_SETUP.md

Easy Piper TTS Setup (5 Minutes)

The Problem

Piper voice models can't be auto-downloaded due to HuggingFace's complex repository structure. But don't worry - manual download is quick and easy!

Quick Setup (3 Steps)

Step 1: Download Voice Files

Visit this page: https://github.com/rhasspy/piper/releases/tag/v1.2.0

Scroll down to "Assets" section and download these files:

Recommended Starter Pack (3 voices):

1. en_US-lessac-medium (Male, American)

   • Download: en_US-lessac-medium.onnx (63 MB)
   • Download: en_US-lessac-medium.onnx.json (8 KB)

2. en_US-amy-medium (Female, American)

   • Download: en_US-amy-medium.onnx (63 MB)
   • Download: en_US-amy-medium.onnx.json (8 KB)

3. en_GB-alan-medium (Male, British)

   • Download: en_GB-alan-medium.onnx (63 MB)
   • Download: en_GB-alan-medium.onnx.json (8 KB)

Total download: ~190 MB for 3 voices

Step 2: Place Files

Move all downloaded files to:

backend/piper_models/

Your directory should look like:

backend/piper_models/
├── en_US-lessac-medium.onnx
├── en_US-lessac-medium.onnx.json
├── en_US-amy-medium.onnx
├── en_US-amy-medium.onnx.json
├── en_GB-alan-medium.onnx
└── en_GB-alan-medium.onnx.json

Step 3: Test

cd backend
python test_piper_direct.py

You should see: "✓ Synthesis successful"

Done! 🎉

Now you can:

1. Start the backend: uvicorn main:app --reload
2. Open the UI
3. Click "Piper TTS" button
4. Select Piper voices
5. Generate audiobooks with pitch control!

More Voices (Optional)

Want more variety? Download additional voices from the same page:

More American English:

• en_US-libritts-high (High quality, neutral)
• en_US-ryan-high (Male, high quality)

More British English:

• en_GB-alba-medium (Female)
• en_GB-jenny_dioco-medium (Female)

Other Languages:

• Browse the releases page for Spanish, French, German, etc.

Troubleshooting

"Model not found" error

• Make sure you downloaded BOTH .onnx and .onnx.json files
• Check files are in backend/piper_models/ directory
• Verify filenames match exactly (case-sensitive)

Files won't download

• Try a different browser
• Check your internet connection
• Download one at a time if needed

Still having issues?

• Fall back to Kokoro TTS (works out of the box)
• Check backend/PIPER_SETUP.md for detailed troubleshooting

Why Manual Download?

We tried automatic download but encountered:

• ❌ Complex HuggingFace URL structure
• ❌ SSL certificate issues
• ❌ Unreliable across different systems

Manual download is:

• ✅ Fast (5 minutes)
• ✅ Reliable (always works)
• ✅ One-time setup
• ✅ You control what you download

Alternative: Use Kokoro TTS

If this seems like too much work, Kokoro TTS works perfectly with zero setup:

• ✅ No downloads needed
• ✅ 54 voices, 9 languages
• ✅ High quality
• ❌ No pitch control

Just keep "Kokoro TTS" selected in the UI!

Need Help?

1. Check the files are in the right place
2. Run python test_piper_direct.py to diagnose
3. Check backend logs for errors
4. See PIPER_STATUS.md for more troubleshooting

---

Remember: This is a one-time setup. Once downloaded, Piper voices work forever! 🚀