diff --git a/PIPER_STATUS.md b/PIPER_STATUS.md new file mode 100644 index 0000000..a2e5118 --- /dev/null +++ b/PIPER_STATUS.md @@ -0,0 +1,150 @@ +# 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.