# Piper TTS Setup Guide

## Quick Start

Piper TTS is now integrated but requires manual voice model setup.

### 1. Install Piper

```bash
cd backend
./install_piper.sh
```

Verify installation:
```bash
piper --version
```

### 2. Download Voice Models

Piper voice models need to be downloaded manually and placed in `backend/piper_models/`.

**Download voices from:**
https://github.com/rhasspy/piper/releases/tag/v1.2.0

**Recommended voices for English:**

1. **en_US-lessac-medium** (Male, American)
   - Download: `en_US-lessac-medium.onnx` and `en_US-lessac-medium.onnx.json`
   - Place in: `backend/piper_models/`

2. **en_US-amy-medium** (Female, American)
   - Download: `en_US-amy-medium.onnx` and `en_US-amy-medium.onnx.json`
   - Place in: `backend/piper_models/`

3. **en_GB-alan-medium** (Male, British)
   - Download: `en_GB-alan-medium.onnx` and `en_GB-alan-medium.onnx.json`
   - Place in: `backend/piper_models/`

### 3. Directory Structure

After downloading, 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
└── ...
```

### 4. Test Piper

```bash
cd backend
python test_piper_direct.py
```

### 5. Use in Application

1. Start the backend server
2. In the frontend, click "Piper TTS" button in Voice Assignment screen
3. Select Piper voices from the dropdown
4. Generate audiobook with pitch control!

## 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)

### "Piper not found" error

- Run `./install_piper.sh` to install Piper
- Or install manually from https://github.com/rhasspy/piper/releases

### Synthesis fails

- Check Piper version: `piper --version`
- Try running Piper directly: `echo "test" | piper --model piper_models/en_US-lessac-medium.onnx --output-raw > test.wav`
- Check backend logs for detailed error messages

## Alternative: Use Kokoro TTS

If Piper setup is too complex, you can continue using Kokoro TTS (the default engine) which works out of the box with no additional setup.

## More Voices

Browse all available Piper voices:
https://rhasspy.github.io/piper-samples/

Download any voice and place the `.onnx` and `.onnx.json` files in `backend/piper_models/`.