# 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! 🚀