feat: Add Piper voice download helpers and guides

- Created download_piper_voices.py for automated download attempts
- Created download_piper_voices.sh as alternative bash script
- Created EASY_PIPER_SETUP.md with simple 3-step instructions
- Created PIPER_DOWNLOAD_GUIDE.md with visual step-by-step guide
- Includes troubleshooting, checklists, and pro tips

Makes Piper setup much easier for users with multiple guide options.
This commit is contained in:
2025-12-09 15:04:29 +00:00
parent b1ce561dc4
commit 4e627aed12
4 changed files with 652 additions and 0 deletions

130
backend/EASY_PIPER_SETUP.md Normal file
View File

@@ -0,0 +1,130 @@
# 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
```bash
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! 🚀