Registry / ai-ml / piper-tts

piper-tts

JSON →
library1.4.2pypypi✓ verified 85d ago

Piper TTS is a fast, local, and neural text-to-speech engine optimized for CPU performance, allowing speech synthesis directly on device. It is currently at version 1.4.2 and receives frequent minor updates with occasional major version changes that introduce new features and API adjustments.

pip install piper-tts
INSTALL
IMPORT
SIG · PIPER-TTS
P
piper-tts
ai-mlpythonv1.4.2
Install
7.5s avg
Import
339ms
Disk
190MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.4.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
build_error
glibc
py 3.103.920 runs
installs and imports cleanly · install 7.5s · import 0.339s · 226MB
190MB installed
● package 190MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

PiperVoice
from piper import PiperVoice
SynthesisConfig
from piper.voices import SynthesisConfig
from piper import SynthesisConfig
SynthesisConfig resides in the 'voices' submodule since v1.3.0.

This quickstart demonstrates how to load a Piper TTS voice model and synthesize speech. Remember that model files (`.onnx` and `.json`) must be downloaded separately. The `synthesize` method yields audio chunks (bytes) that can then be processed, saved, or played back.

import piper import os # NOTE: Model files (.onnx and .json) are NOT included with the pip package. # You MUST download them separately, e.g., from huggingface.co/rhasspy/piper-voices # Example: 'en_US-lessac-medium.onnx' and 'en_US-lessac-medium.json' # Provide paths to your downloaded model files model_path = os.environ.get('PIPER_MODEL_PATH', 'path/to/your_downloaded_model.onnx') config_path = os.environ.get('PIPER_CONFIG_PATH', 'path/to/your_downloaded_model.json') if not os.path.exists(model_path) or not os.path.exists(config_path): print(f"Error: Model files not found. Please download '.onnx' and '.json' files.") print(f" Expected model at: {model_path}") print(f" Expected config at: {config_path}") print(f" Download example: https://huggingface.co/rhasspy/piper-voices/tree/main") else: try: # Load the voice model voice = piper.PiperVoice.load(model_path, config_path=config_path) # Get default synthesis configuration synthesis_config = voice.config.synthesis text = "Hello, this is a test from Piper TTS." print(f"Synthesizing: '{text}'") audio_chunks_generator = voice.synthesize(text, synthesis_config) num_chunks = 0 for audio_bytes in audio_chunks_generator: num_chunks += 1 # In a real application, you would save audio_bytes to a file # or stream it for real-time playback (e.g., using 'sounddevice'). # Example: print(f"Received chunk of {len(audio_bytes)} bytes.") pass # Just iterate to demonstrate generation print(f"Successfully generated {num_chunks} audio chunks.") print("Audio can be saved to a WAV file using Python's 'wave' module or 'soundfile'.") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingThe Python API for `PiperVoice.synthesize` changed significantly in v1.3.0. It now requires a `SynthesisConfig` object as its second argument and directly yields raw audio bytes, rather than returning a stream or requiring `synthesize_raw`.
fix
Update your code to pass a `piper.voices.SynthesisConfig` object (e.g., `voice.config.synthesis`) and iterate over the generated audio bytes: `for audio_bytes in voice.synthesize(text, synthesis_config): ...`. The `synthesize_raw` method was removed.
affects: >=1.3.0
breakingThe project license changed from MIT to GPLv3 in v1.3.0. This has implications for how you can use and distribute software built with Piper TTS.
fix
Review the GPLv3 license terms to ensure your project's compliance if you are using Piper TTS in a commercial or distributed application.
affects: >=1.3.0
gotchaPiper TTS model files (`.onnx` for the model and `.json` for its configuration) are NOT included with the pip package. You must download them separately from external sources (e.g., Hugging Face).
fix
Download the desired model files (e.g., `en_US-lessac-medium.onnx` and `en_US-lessac-medium.json`) from a repository like `huggingface.co/rhasspy/piper-voices` and provide their paths when loading `PiperVoice`.
affects: All versions
gotchaFor phonemization, Piper TTS relies on `espeak-ng`. While the Python package embeds `espeak-ng`'s Python bindings, the underlying `espeak-ng` C library binaries are still a system-level dependency for many phonemization tasks.
fix
Ensure `espeak-ng` is installed on your operating system (e.g., `sudo apt-get install espeak-ng` on Debian/Ubuntu, `brew install espeak-ng` on macOS, or via your OS's package manager).
affects: All versions
Errors
Common errors & fixes
FileNotFoundError: [Errno 2] No such file or directory: 'path/to/model.onnx'
The Piper TTS model (.onnx) or its configuration file (.json) was not found at the specified path. These files are not installed with the pip package.
fix
Download the desired model and config files (e.g., from huggingface.co/rhasspy/piper-voices) and ensure the `model_path` and `config_path` arguments to `PiperVoice.load()` are correct.
AttributeError: 'PiperVoice' object has no attribute 'synthesize_raw'
The `synthesize_raw` method was removed in version 1.3.0 as part of an API overhaul.
fix
Migrate your code to use the `PiperVoice.synthesize()` method. It now takes a `piper.voices.SynthesisConfig` object (e.g., `voice.config.synthesis`) and yields audio bytes directly.
TypeError: PiperVoice.synthesize() missing 1 required positional argument: 'config'
Since Piper TTS v1.3.0, the `synthesize` method requires a `piper.voices.SynthesisConfig` object as its second argument.
fix
Pass a `SynthesisConfig` object, typically obtained from the loaded voice (`voice.config.synthesis`), as the second argument: `voice.synthesize(text, voice.config.synthesis)`.
Upgrade
Version history
1.4.2latest on PyPI · released Apr 2, 2026
Audit
Dependencies
onnxruntimerequiredCore inference engine for ONNX models.
espeak-ngrequiredSystem-level C library required for phonemization unless using pre-generated phoneme IDs. While Piper embeds its Python bindings, the underlying system library is often still needed.
Agent activity
30 hits · last 30 days
node
28
Amazon
1
OpenAI (training)
1
Resources
piper-tts — pip install piper-tts · libregistry