# Piper TTS Integration Status

## Current State: ✅ Integrated with Manual Setup Required

Piper TTS has been successfully integrated into the application as an alternative to Kokoro TTS. The integration is **complete and functional**, but requires **manual voice model download** before use.

## What Works

✅ **Backend Integration**
- PiperTTSService with pitch control (-12 to +12 semitones)
- UnifiedTTSService managing both engines
- API endpoints for engine selection
- Voice preview support for Piper voices

✅ **Frontend Integration**
- Engine selector UI (Kokoro vs Piper buttons)
- Dynamic voice loading per engine
- Visual feedback for active engine

✅ **Documentation**
- Comprehensive setup guides
- API documentation
- Troubleshooting instructions

## What Requires Manual Setup

⚠️ **Voice Models Must Be Downloaded Manually**

Piper voice models cannot be auto-downloaded due to:
- HuggingFace repository structure complexity
- SSL certificate verification issues in some environments
- Large file sizes (10-50MB per voice)

**This is a one-time setup step.**

## How to Use Piper TTS

### Step 1: Install Piper Binary

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

Verify: `piper --version`

### Step 2: Download Voice Models

1. Visit: https://github.com/rhasspy/piper/releases/tag/v1.2.0
2. Download these files for each voice you want:
   - `en_US-lessac-medium.onnx` (model file)
   - `en_US-lessac-medium.onnx.json` (config file)

3. Place in: `backend/piper_models/`

**Recommended starter voices:**
- `en_US-lessac-medium` (Male, American)
- `en_US-amy-medium` (Female, American)
- `en_GB-alan-medium` (Male, British)

### Step 3: Test Installation

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

### Step 4: Use in Application

1. Start backend: `uvicorn main:app --reload`
2. Start frontend: `npm run dev`
3. In Voice Assignment screen, click "Piper TTS" button
4. Select Piper voices from dropdown
5. Generate audiobook with pitch control!

## Why Manual Download?

We attempted automatic download but encountered:
- **SSL Certificate Issues**: Python's urllib has certificate verification problems
- **URL Structure**: HuggingFace's repository structure is complex
- **Reliability**: Manual download is more reliable across different environments

**Trade-off**: One-time manual setup vs. unreliable automatic downloads

## Alternative: Use Kokoro TTS

If Piper setup is too complex, **Kokoro TTS works perfectly out of the box** with:
- ✅ No manual setup required
- ✅ 54 voices across 9 languages
- ✅ High quality synthesis
- ❌ No pitch control

Simply keep the default "Kokoro TTS" engine selected.

## Error Messages You Might See

### "Voice model not found"

**Cause**: Voice model files not downloaded

**Solution**: Download `.onnx` and `.onnx.json` files and place in `backend/piper_models/`

**See**: `backend/PIPER_SETUP.md` for detailed instructions

### "Piper not found"

**Cause**: Piper binary not installed

**Solution**: Run `./install_piper.sh` or install manually

### "Preview failed"

**Cause**: Voice model missing or Piper not working

**Solution**: 
1. Check voice models are downloaded
2. Test with `python test_piper_direct.py`
3. Check backend logs for detailed errors

## Future Improvements

Potential enhancements for easier setup:

1. **Bundled Voice Models**: Include 1-2 default voices in repository
2. **Download Script**: Create a helper script to download popular voices
3. **UI Download**: Add "Download Voice" button in frontend
4. **Alternative Hosting**: Host models on a simpler CDN
5. **Docker Image**: Pre-package models in Docker image

## Documentation

- **Setup Guide**: `backend/PIPER_SETUP.md`
- **Integration Details**: `PIPER_TTS_INTEGRATION.md`
- **Usage Guide**: `backend/PIPER_TTS_GUIDE.md`
- **Backend README**: `backend/README.md`

## Support

If you encounter issues:

1. Check `backend/PIPER_SETUP.md` for setup instructions
2. Run `python test_piper_direct.py` to diagnose problems
3. Check backend logs for detailed error messages
4. Fall back to Kokoro TTS if needed

## Summary

**Piper TTS is fully integrated and functional**, but requires a one-time manual setup to download voice models. This is a reasonable trade-off for gaining pitch control capabilities. Users who prefer zero-setup can continue using Kokoro TTS.

**Recommendation**: Document the manual setup clearly in user-facing documentation and consider it a "power user" feature.