docs: Add Piper TTS status and setup documentation
- Created PIPER_STATUS.md explaining current state and manual setup - Documented why automatic download doesn't work - Provided clear step-by-step setup instructions - Listed alternative (Kokoro TTS) for users who prefer zero-setup - Added troubleshooting for common errors Piper TTS is fully functional but requires one-time manual voice model download.
This commit is contained in:
150
PIPER_STATUS.md
Normal file
150
PIPER_STATUS.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user