Introduction to Piper

Relevant source files

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

• README.md
• CHANGELOG.md
• src/piper/voice.py
• src/piper/config.py
• libpiper/include/piper.h
• libpiper/src/piper.cpp
• src/piper/main.py
• src/piper/http_server.py

Piper is a fast, local neural text-to-speech (TTS) engine designed for efficiency and high-quality voice synthesis. It leverages ONNX models for inference and embeds espeak-ng directly for the phonemization process, ensuring that the system can run entirely offline without external API dependencies. Piper is versatile, offering a Python API, a C/C++ shared library (libpiper), a command-line interface, and an HTTP web server for integration into various projects.

Sources: README.md:1-20, CHANGELOG.md:31-35, src/piper/voice.py:108-112

Architecture and Components

Piper's architecture is centered around the conversion of raw text into speech audio through a multi-stage pipeline involving phonemization, mapping to IDs, and neural inference via ONNX Runtime.

Core Pipeline

1. Phonemization: Raw text is converted into phonemes (the sounds of speech) using espeak-ng.
2. ID Mapping: Phonemes are mapped to integer IDs based on the specific voice model's configuration.
3. Inference: The phoneme IDs are fed into an ONNX model (typically based on the VITS architecture) to generate raw audio samples.
4. Post-Processing: Audio is optionally normalized and converted to the desired output format (e.g., WAV).

The following diagram illustrates the high-level data flow from input text to generated audio:

Software Interfaces

Piper provides multiple ways to interact with the engine:

Interface	Description	Primary Files
Python API	A PiperVoice class that handles loading models and synthesis.	src/piper/voice.py
C/C++ API	A shared library (libpiper) with a C-style interface for native integration.	libpiper/include/piper.h
CLI	Command-line tool for batch processing text files or stdin.	src/piper/__main__.py
Web Server	A Flask-based HTTP server providing REST endpoints for synthesis.	src/piper/http_server.py

Sources: README.md:8-14, libpiper/README.md:1-10, src/piper/main.py:22-60

Configuration and Synthesis Control

Piper uses a JSON configuration file (typically <model>.onnx.json) to define the voice's characteristics and synthesis defaults. These settings can be overridden at runtime using a SynthesisConfig object in Python or piper_synthesize_options in C.

Key Configuration Parameters

Parameter	Type	Default	Description
length_scale	float	1.0	Controls speaking speed. < 1.0 is faster, > 1.0 is slower.
noise_scale	float	0.667	Controls the variety/noise in the generator.
noise_w_scale	float	0.8	Controls phoneme length variety.
sample_rate	int	-	The frequency of output audio (e.g., 22050Hz).
speaker_id	int	0	The ID of the speaker for multi-speaker models.

Sources: src/piper/config.py:7-11, src/piper/config.py:108-125, libpiper/include/piper.h:124-150

Synthesis State Machine (C API)

The C API follows a specific lifecycle to manage resources and streaming audio generation.

Technical Implementation Details

Phonemization Strategies

Piper supports different PhonemeType values depending on the language and model requirements:

• ESPEAK: Uses the embedded espeak-ng for standard phonemization.
• TEXT: Directly uses UTF-8 codepoints as phonemes (e.g., for models trained on IPA directly).
• PINYIN: Uses g2pW for Chinese (zh-CN) phonemization.

Sources: src/piper/config.py:14-17, src/piper/voice.py:155-200

Alignment Support

Recent versions of Piper include experimental support for phoneme/audio alignments. When enabled, the engine returns PhonemeAlignment data, which maps specific phonemes to the number of samples they produced in the resulting audio. This is achieved by retrieving alignment tensors from the ONNX model during inference.

Sources: src/piper/voice.py:31-40, src/piper/voice.py:270-310, CHANGELOG.md:25-26

Multi-Speaker Management

For models containing multiple voices, Piper uses a speaker_id (integer) or a speaker_id_map (mapping names to IDs). In the ONNX session, this is passed as the sid input tensor.

Sources: src/piper/config.py:34-36, src/piper/voice.py:375-390, libpiper/src/piper.cpp:314-325

Conclusion

Piper provides a robust and high-performance solution for local speech synthesis. By combining the flexibility of Python for development and training with the efficiency of a C++ core for deployment, it serves a wide range of use cases from accessibility tools like NVDA to home automation systems like Home Assistant. Its reliance on ONNX and espeak-ng ensures cross-platform compatibility and privacy by design through offline operation.

Sources: README.md:1-25, CHANGELOG.md:31-40