High-Level Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• libpiper/include/piper.h
• src/piper/init.py
• src/piper/voice.py
• libpiper/src/piper.cpp
• src/piper/config.py
• libpiper/include/piper_impl.hpp
• src/piper/main.py

Piper is a fast, local neural text-to-speech (TTS) engine designed to run efficiently on a variety of hardware. The architecture centers around a decoupled design where text phonemization is handled by embedded [espeak-ng] and neural inference is performed using [ONNX Runtime].

The system provides multiple interfaces including a Python API, a C/C++ shared library (libpiper), and a command-line interface. It supports both single-speaker and multi-speaker models, featuring adjustable synthesis parameters such as length scale (speed), noise scale, and phoneme width noise.
Sources: README.md:1-15, libpiper/include/piper.h:122-132, src/piper/voice.py:84-110

Core Components and System Flow

The Piper architecture consists of three primary stages: Input Processing (Phonemization), Neural Inference, and Output Generation.

System Flow Diagram

The following diagram illustrates the end-to-end data flow from raw text input to synthesized audio chunks.

Software Layers

Piper is implemented with a dual-layer approach to maximize both accessibility and performance.

1. Python API Layer

The Python layer provides a high-level interface via the PiperVoice class. It manages the lifecycle of the ONNX inference session and orchestrates the phonemization process.

• PiperVoice: The central class for loading models and performing synthesis.
• AudioChunk: A dataclass containing raw audio samples, sample rate, and alignment data.
• SynthesisConfig: Parameters for controlling speaker ID, speed, and noise.

Sources: src/piper/voice.py:84-150, src/piper/config.py:90-112

2. C/C++ Native Layer (libpiper)

For low-level integration, libpiper offers a C-style API that wraps the C++ implementation. It provides stable handles for the synthesizer and direct access to audio chunks.

Component	Description
piper_synthesizer	Opaque handle to the internal C++ synthesizer state.
piper_audio_chunk	Struct containing raw float samples, sample rate, and phoneme alignments.
piper_create	Factory function to initialize the engine with model, config, and espeak-ng data.

Sources: libpiper/include/piper.h:20-55, libpiper/src/piper.cpp:14-30

Synthesis Logic and Data Structures

The synthesis process relies on a mapping between text characters, phonemes, and numerical IDs that the neural model understands.

Phonemization and ID Mapping

Piper supports multiple phoneme types, primarily relying on espeak-ng. The process involves:

1. Text Normalization: Cleaning input and handling language-specific features (e.g., Arabic Tashkeel).
2. Phonemization: Converting text to IPA phonemes using espeak-ng.
3. ID Conversion: Mapping phonemes to specific integer IDs defined in the voice's config.json.

Key Data Structures

PiperConfig (Python) / piper_synthesizer (C++)

Stores the model's metadata and default inference settings.

• sample_rate: Target frequency (e.g., 22050 Hz).
• phoneme_id_map: Dictionary/Map of phoneme strings to integer sequences.
• num_symbols: Size of the phoneme vocabulary.
• num_speakers: Count of supported voices in the model.

Sources: src/piper/config.py:27-55, libpiper/include/piper_impl.hpp:60-75

Deployment Interfaces

Piper provides several ways to interact with the core engine:

1. Command Line: The piper entry point allows piping text from stdin to WAV files or raw audio streams.
2. HTTP Server: A Flask-based server providing a REST API for remote synthesis.
3. Direct Integration: Using import piper in Python or linking libpiper in C/C++.

Synthesis Options (Configuration)

Parameter	Type	Default	Description
length_scale	float	1.0	Speed of speech. < 1.0 is faster, > 1.0 is slower.
noise_scale	float	0.667	Emotional variance/vibrancy.
noise_w_scale	float	0.8	Variance in phoneme duration.
speaker_id	int	0	Index for multi-speaker models.

Sources: src/piper/config.py:12-18, src/piper/main.py:50-80, src/piper/http_server.py:160-190

Conclusion

Piper's architecture is optimized for low-latency, local execution by leveraging the performance of ONNX Runtime and the linguistic breadth of espeak-ng. By abstracting the complexity of neural TTS behind consistent Python and C APIs, it enables easy integration into various applications ranging from home automation to accessibility tools.
Sources: README.md:1-10, src/piper/voice.py:350-400