Python API Reference
Relevant source files
The following files were used as context for generating this wiki page:
Piper is a fast, local neural text-to-speech engine designed to provide high-quality speech synthesis with minimal dependencies. The Python API provides developers with the tools to load ONNX-based voice models, perform phonemization via espeak-ng, and generate audio chunks or WAV files.
The API is structured around the PiperVoice class, which handles the orchestration between text processing (phonemization) and neural inference (ONNX Runtime). It supports various phoneme types, including espeak, pinyin, and direct text input, and offers configurable synthesis parameters such as length and noise scales.
Sources: src/piper/voice.py, src/piper/config.py, README.md:3-10
Core Classes and Data Structures
The Python API utilizes several dataclasses to manage configuration and output data. The primary interaction point for synthesis is the PiperVoice class.
PiperVoice
The central class responsible for loading models and executing synthesis. It manages the ONNX inference session and handles optional features like Arabic diacritization (Tashkeel).
load(model_path, ...): A static method to initialize a voice from an ONNX model and its corresponding JSON configuration.synthesize(text, ...): An iterable generator that yieldsAudioChunkobjects for each sentence in the input text.phonemize(text): Converts raw text into a list of phonemes, handling special blocks like[[ raw phonemes ]].
Sources: src/piper/voice.py:100-244
Configuration Classes
Piper uses two main configuration structures to separate persistent model traits from per-request synthesis settings.
| Class | Purpose | Key Fields |
|---|---|---|
PiperConfig | Defines model-specific parameters loaded from .onnx.json. | sample_rate, num_speakers, phoneme_type, phoneme_id_map. |
SynthesisConfig | Defines per-request parameters for audio generation. | speaker_id, length_scale, noise_scale, volume. |
Sources: src/piper/config.py:20-112
AudioChunk
The output of the synthesis process, containing raw audio data and metadata regarding the phonemes that produced it.
The AudioChunk provides properties to easily convert the raw floating-point audio from the neural model into 16-bit PCM data suitable for WAV files or playback.
Sources: src/piper/voice.py:44-97
Synthesis Workflow
The synthesis process follows a linear pipeline from raw text to audio samples. It involves phonemization, ID mapping, and ONNX inference.
Text Processing and Phonemization
Piper supports three phoneme types defined in the PhonemeType enum: espeak (default), text (direct IPA), and pinyin (for Chinese). For espeak, it uses a bridge to espeak-ng. It also supports "raw phonemes" within text using the [[ phonemes ]] syntax, which bypasses the standard phonemizer for those specific segments.
Sources: src/piper/voice.py:146-200, src/piper/config.py:14-18
Inference and Audio Generation
The phoneme_ids_to_audio method prepares the input tensors for the ONNX model, including input (IDs), input_lengths, scales (noise and length parameters), and an optional sid (speaker ID) for multi-speaker models.
Sources: src/piper/voice.py:382-441
Utility Functions
Voice Downloading
The piper.download_voices module provides a programmatic way to fetch models from the official HuggingFace repository.
download_voice(voice, download_dir, ...): Downloads the.onnxand.onnx.jsonfiles based on a voice name string likeen_US-lessac-medium.list_voices(): Fetches and prints thevoices.jsonindex from the remote repository.
Sources: src/piper/download_voices.py:65-116
Web API Integration
The http_server.py module demonstrates how to wrap the Python API in a Flask application, providing endpoints for listing voices, downloading models, and synthesizing audio via HTTP POST requests.
| Endpoint | Method | Description |
|---|---|---|
/ | POST | Synthesizes text; returns a WAV file. |
/voices | GET | Lists locally available voice models. |
/download | POST | Downloads a specific voice model to the server. |
Sources: src/piper/http_server.py:99-232
Summary
The Piper Python API provides a high-level interface for local text-to-speech. By leveraging onnxruntime for inference and espeak-ng for linguistic processing, it achieves high performance while remaining flexible through its SynthesisConfig and PiperVoice abstractions. Developers can use it for simple CLI tools, embedded applications, or as the backend for distributed web services.