# Piper TTS

## Overview

**Name:** Piper TTS

**Description:** Lightweight, fast neural TTS (Text-to-Speech) designed for embedded devices and real-time use, from the Rhasspy team. Piper delivers high-quality speech synthesis with minimal computational overhead, making it ideal for IoT devices, Raspberry Pi, and edge computing applications.

## Key Features

### Strengths
- **Offline Operation**: Fully self-contained, works without internet connectivity
- **Low-Latency**: Optimized for real-time speech generation with minimal delays
- **Extensive Language Support**: 50+ voices across multiple languages
- **ONNX Runtime Efficiency**: Leverages ONNX for optimal performance across platforms
- **Resource Efficient**: Lightweight models suitable for embedded systems

### Specifications
- Model architecture: Fast, lightweight neural vocoder
- Runtime: ONNX (Open Neural Network Exchange)
- Model sizes: Approximately 100MB per model
- Voice options: 100+ voices total
- Language coverage: Multiple languages with native speaker variants

### Pros
- Runs efficiently on Raspberry Pi and other single-board computers
- Low CPU and memory requirements
- Open-source and community-supported
- Fast inference time suitable for real-time applications
- Good naturalness for a lightweight model

### Cons
- Less expressive than larger models (e.g., XTTS, Coqui)
- Limited emotion/style control
- Smaller voice selection compared to commercial solutions
- May lack fine-grained prosody control

## License

**MIT License** - Permissive open-source license allowing commercial and private use with attribution.

## Links

- **GitHub**: https://github.com/rhasspy/piper
- **Original Rhasspy**: https://github.com/rhasspy/rhasspy
- **OHF-Voice Fork**: https://github.com/openhomefoundation/piper (community continuation)
- **Voice Models Repository**: https://github.com/rhasspy/piper/releases
- **Documentation**: https://github.com/rhasspy/piper/blob/master/README.md

## Integration Status

**Current Status:** Currently integrated for `tts-1` model designation

The `tts-1` model in this project uses Piper as one of the supported TTS engines, providing a lightweight alternative to other TTS solutions.

### Integration Points
- Model selection: Available via `tts-1` model identifier
- Voice selection: Access to multiple language variants
- Runtime: ONNX-based execution for broad platform support
- Configuration: Voice selection per request or global settings

## Technical Details

### Runtime Environment
- **Framework**: ONNX (Open Neural Network Exchange)
- **Compatibility**: Cross-platform (Linux, Windows, macOS, ARM-based systems)
- **Dependencies**: Minimal runtime dependencies

### Model Architecture
- **Vocoder Type**: Fast, lightweight neural vocoder
- **Model Sizes**: Approximately 100MB per language/voice variant
- **Quantization**: Supported for further size reduction
- **Voice Count**: 100+ distinct voices
- **Language Support**: Covers multiple languages with regional variants

### Performance Characteristics
- **Inference Speed**: Optimized for embedded devices
- **Memory Footprint**: Minimal RAM requirements (typically < 500MB)
- **CPU Usage**: Low CPU utilization suitable for background tasks
- **Throughput**: Capable of real-time speech synthesis on modest hardware

## Available Voices

### Language Coverage
Piper supports voices across multiple languages:

- **English** (US, British variants)
- **Spanish**
- **French**
- **German**
- **Italian**
- **Portuguese**
- **Russian**
- **Dutch**
- **Polish**
- **Turkish**
- **Additional languages**: Continued expansion through community contributions

### Accent and Variant Options
- Male and female voices for each language
- Regional accent variations
- Multiple speaker variants per language
- Quality tiers (fast vs. high-quality)

### Voice Selection
Voices are typically identified by language code and speaker identifier:
```
piper-{language_code}-{speaker_id}-medium
```

Example identifiers:
- `en-us-lessac-medium` (US English)
- `en-gb-glow-tts` (British English)
- `es-es-carlfm-medium` (Spanish)
- `fr-fr-tom-medium` (French)

## Performance Metrics

### Real-Time Factor (RTF)
- **Target RTF**: < 1.0 for real-time operation
- **Typical RTF on Raspberry Pi 4**: 0.3-0.5 (faster than real-time)
- **RTF on modern CPUs**: 0.1-0.3 (significantly faster than real-time)

*Note: RTF of 0.5 means audio is generated 2x faster than playback speed*

### Memory Usage
- **Model Loading**: 100-200MB per voice model
- **Runtime RAM**: 50-150MB during active synthesis
- **Total System Usage**: Generally < 300MB on embedded systems

### Latency
- **First Syllable Latency**: 50-200ms (depending on hardware)
- **Streaming Latency**: 10-50ms per chunk
- **Total Overhead**: Minimal additional latency from ONNX runtime

### CPU Utilization
- Single core usage: 40-80% on Raspberry Pi
- Multi-core systems: Scales efficiently
- Background operation possible without noticeable system impact

## Raccoon Mission Notes

### Background
The Raccoon Mission encompasses efforts to preserve and maintain open-source TTS and voice technology as part of a larger initiative to maintain speech synthesis capabilities.

### Original Rhasspy Abandonment
The original Rhasspy project, which includes Piper TTS, transitioned to community maintenance. The Rhasspy team shifted focus, leaving the original repository in maintenance mode. This necessitated community efforts to continue development and support.

### OHF-Voice Fork Status
The **Open Home Foundation (OHF) Voice** fork of Piper represents a community-driven continuation:

- **Repository**: https://github.com/openhomefoundation/piper
- **Status**: Active community maintenance and enhancement
- **Focus Areas**:
  - Additional language support
  - Voice quality improvements
  - Performance optimizations
  - Bug fixes and compatibility updates
- **Integration**: Provides modern continuation of Piper development

### Mirroring and Preservation Needs

#### Why Mirroring Matters
1. **Availability**: Ensures models remain accessible despite upstream changes
2. **Stability**: Provides fixed points for reproducible deployments
3. **Resilience**: Protects against future abandonment or upstream deletion
4. **Performance**: Local mirrors reduce external dependency on remote sources

#### Mirroring Strategy
- Mirror Piper voice models from official release sources
- Archive OHF-Voice fork releases
- Document specific model versions for reproducibility
- Maintain checksums for integrity verification

#### Current Mirroring Status
Refer to `/docs/MIRRORS.md` for comprehensive mirroring information and current status of archived Piper models and related resources.

#### Recommended Actions
- Regularly sync mirror repositories with upstream sources
- Maintain documentation of model versions and availability
- Test model compatibility with current integration
- Plan for alternative sources if primary repository becomes unavailable

## Integration with uncloseai-speech

### Model Selection
Piper is available as a lightweight TTS option within the project's model ecosystem:

```bash
# Using Piper TTS via tts-1 model designation
python -m uncloseai_speech --model tts-1 --voice en-us-lessac --text "Hello world"
```

### Configuration
Voice selection and model parameters can be configured through environment variables or command-line arguments. See `/docs/MODELS.md` for integration details.

### Performance Optimization
For embedded systems or resource-constrained environments, Piper provides optimal balance of quality and performance compared to larger models like XTTS.

## Troubleshooting

### Common Issues

**Issue: Model files not found**
- Ensure voice models are downloaded and accessible
- Check model path configuration
- Verify ONNX runtime installation

**Issue: High latency or stuttering**
- Reduce audio chunk size for streaming
- Close other applications consuming CPU
- Consider hardware acceleration options

**Issue: Audio quality concerns**
- Try different voice variants (some voices may sound better than others)
- Adjust speaking rate if supported
- Check ONNX runtime version compatibility

## References

- Piper GitHub Repository: https://github.com/rhasspy/piper
- ONNX Runtime Documentation: https://onnxruntime.ai/
- Rhasspy Project: https://rhasspy.readthedocs.io/
- Open Home Foundation: https://www.openhomelabs.org/

## See Also

- `/docs/MODELS.md` - Overview of all integrated TTS models
- `/docs/MIRRORS.md` - Mirroring and preservation documentation
- `/docs/CLAUDE.md` - Development guide for this project