audiobook/PIPER_STATUS.md

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

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

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.