audiobook/backend/PIPER_TTS_GUIDE.md

Piper TTS Integration Guide

This guide covers the Piper TTS engine integration, including installation, configuration, and usage.

What is Piper TTS?

Piper is a fast, local neural text-to-speech system that runs entirely on your machine. It offers:

• Fast synthesis: Faster than Kokoro for most use cases
• Pitch control: Adjust voice pitch per character (-12 to +12 semitones)
• Multiple voices: Various English voices with different characteristics
• Low resource usage: Smaller models and lower memory footprint
• Privacy: All processing happens locally

Installation

Automated Installation (Recommended)

cd backend
./install_piper.sh

This script will:

1. Detect your OS and architecture
2. Download the appropriate Piper binary
3. Install it to /usr/local/bin
4. Verify the installation

Manual Installation

1. Visit Piper Releases
2. Download the appropriate archive for your platform:
   • Linux x86_64: piper_amd64.tar.gz
   • Linux ARM64: piper_arm64.tar.gz
   • macOS: piper_macos_x64.tar.gz
3. Extract the archive
4. Copy the piper binary to a directory in your PATH

Verify Installation

piper --version

You should see output like: 1.2.0

Available Voices

Piper supports multiple English voices:

Voice ID	Language	Gender	Quality	Description
en_US-lessac-medium	US English	Male	Medium	Clear, neutral male voice
en_US-libritts-high	US English	Neutral	High	High-quality neutral voice
en_US-amy-medium	US English	Female	Medium	Clear female voice
en_GB-alan-medium	UK English	Male	Medium	British male voice
en_GB-alba-medium	UK English	Female	Medium	British female voice

Voice models are automatically downloaded on first use (~10-50MB each).

Configuration

Set Piper as Default Engine

Option 1: Environment Variable

export TTS_ENGINE=piper

Add to your .env file:

TTS_ENGINE=piper

Option 2: Runtime API Call

curl -X POST http://localhost:8000/api/tts/engines \
  -H "Content-Type: application/json" \
  -d '{"engine": "piper"}'

Voice Model Storage

Voice models are stored in:

backend/piper_models/

Models are downloaded automatically on first use. You can pre-download models manually if needed.

Usage Examples

Basic Text-to-Speech

curl -X POST http://localhost:8000/api/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test of Piper TTS.",
    "lang": "a",
    "roles": [
      {"id": "Narrator", "voice": "en_US-lessac-medium"}
    ],
    "speed": 1.0
  }' \
  --output test.wav

Multi-Voice with Pitch Control

curl -X POST http://localhost:8000/api/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Alice: Hello Bob!\nBob: Hi Alice, how are you?\nNarrator: They greeted each other warmly.",
    "lang": "a",
    "roles": [
      {"id": "Alice", "voice": "en_US-amy-medium"},
      {"id": "Bob", "voice": "en_US-lessac-medium"},
      {"id": "Narrator", "voice": "en_GB-alan-medium"}
    ],
    "speed": 1.0,
    "pitch_adjustments": [
      {"id": "Alice", "pitch": 4},
      {"id": "Bob", "pitch": -3},
      {"id": "Narrator", "pitch": 0}
    ]
  }' \
  --output audiobook.wav

Pitch Adjustment Guidelines

Pitch is measured in semitones (half-steps on a musical scale):

• +12 semitones: One octave higher (very high-pitched)
• +6 semitones: Noticeably higher (child-like)
• +3 semitones: Slightly higher (feminine adjustment)
• 0 semitones: Original voice (no change)
• -3 semitones: Slightly lower (masculine adjustment)
• -6 semitones: Noticeably lower (deep voice)
• -12 semitones: One octave lower (very deep)

Recommended ranges:

• Female characters: +2 to +5
• Male characters: -2 to -5
• Children: +5 to +8
• Elderly/deep voices: -4 to -8

Python API Usage

from services.unified_tts_service import UnifiedTTSService

# Initialize with Piper engine
tts = UnifiedTTSService(engine="piper")

# Generate audiobook with pitch control
audio_bytes = await tts.generate_audiobook(
    text="Alice: Hello!\nBob: Hi there!",
    lang="a",
    role_voice_map={
        "Alice": "en_US-amy-medium",
        "Bob": "en_US-lessac-medium"
    },
    speed=1.0,
    pitch_adjustments={
        "Alice": 3,
        "Bob": -2
    }
)

# Save to file
with open("output.wav", "wb") as f:
    f.write(audio_bytes)

Performance Comparison

Feature	Kokoro TTS	Piper TTS
Speed	Medium	Fast
Quality	High	Medium-High
Pitch Control	❌ No	✅ Yes
Model Size	~500MB	~10-50MB per voice
Memory Usage	Higher	Lower
Voice Variety	10+ voices	5+ voices (expandable)
Languages	4 languages	English (more available)

Troubleshooting

Piper Not Found

Error: piper: command not found

Solution:

# Check if piper is in PATH
which piper

# If not found, reinstall
./install_piper.sh

# Or add to PATH manually
export PATH="/usr/local/bin:$PATH"

Voice Model Download Fails

Error: Model download timeout or failure

Solution:

1. Check internet connection
2. Manually download models from Piper releases
3. Place .onnx and .onnx.json files in backend/piper_models/

Audio Quality Issues

Problem: Distorted or robotic audio

Solutions:

• Reduce pitch shift amount (stay within ±6 semitones)
• Try different voice models
• Adjust speed (try 0.9 or 1.1)
• Check for text formatting issues

Synthesis Timeout

Error: Piper synthesis times out

Solutions:

• Break text into smaller chunks
• Increase timeout in piper_tts_service.py
• Check system resources (CPU, memory)

Advanced Configuration

Custom Voice Models

To add custom Piper voice models:

1. Download .onnx and .onnx.json files
2. Place in backend/piper_models/
3. Update AVAILABLE_VOICES in piper_tts_service.py:

AVAILABLE_VOICES = {
    "en_US-custom-voice": {"lang": "en", "gender": "female", "quality": "high"},
    # ... existing voices
}

Adjusting Audio Effects

Modify _apply_audio_effects() in piper_tts_service.py to customize:

• Pitch shifting algorithm
• Speed adjustment method
• Audio processing pipeline

Best Practices

1. Voice Selection

   • Use distinct voices for different characters
   • Match voice gender to character when possible
   • Use British voices for variety

2. Pitch Adjustments

   • Start with small adjustments (±2-3 semitones)
   • Test and iterate to find natural-sounding values
   • Avoid extreme values (±10+) unless intentional

3. Performance

   • Pre-download voice models for faster first use
   • Cache generated audio when possible
   • Use appropriate chunk sizes for long texts

4. Quality

   • Use high-quality voice models when available
   • Adjust speed slightly (0.95-1.05) for more natural pacing
   • Combine with AI segmentation for best results

Resources

• Piper GitHub Repository
• Piper Voice Samples
• Voice Model Downloads
• Piper Documentation

License

Piper TTS is licensed under the MIT License.