Installation Guide
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 that can be installed as a Python package or built as a standalone C++ library (libpiper). The system embeds espeak-ng for phonemization and utilizes onnxruntime for model inference.
Sources: README.md:3-5, CHANGELOG.md:30-32
Python Installation
The easiest way to install Piper for general use is via the Python package manager. Piper supports Python 3.9 through 3.13 and uses a stable ABI wheel to ensure compatibility across different Python versions on the same platform.
Sources: setup.py:44-52, CHANGELOG.md:34
Standard Installation
To install the core text-to-speech engine, run:
pip install piper-tts
Sources: README.md:9
Installation Extras
Piper provides several optional dependency groups for specific features:
| Extra | Description | Key Dependencies |
|---|---|---|
train | Tools for training new voice models | torch, lightning, onnx, cython |
http | Runs Piper as a Flask web server | flask |
zh | Chinese language support (pinyin) | g2pW, unicode-rbnf, torch |
dev | Development and testing tools | pytest, black, flake8, cmake |
Sources: setup.py:56-105
C/C++ Library Build (libpiper)
For integration into C++ applications, Piper provides libpiper, a shared library with a C-style API. The build process uses CMake and automatically manages external dependencies.
Sources: libpiper/README.md:3-5
Build Process Flow
The following diagram illustrates the automated build sequence when using CMake for libpiper.
The build system downloads espeak-ng (specifically git tag 212928b) and the appropriate onnxruntime version (defaulting to 1.22.0) based on the host architecture (Linux x64/ARM, Windows x64, or macOS).
Sources: libpiper/CMakeLists.txt:13-90, libpiper/README.md:14-15
Build Commands
To build and install the library manually:
cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build
cmake --install build
Sources: libpiper/README.md:9-12
System Requirements and Dependencies
Core Components
Piper's architecture relies on three primary components that must be present after installation:
- libpiper / piper-tts: The core logic for synthesis.
- onnxruntime: The engine that executes the neural network models.
- espeak-ng-data: Required data files for the phonemization engine.
Sources: libpiper/README.md:17-21
Platform Support
Piper supports multiple architectures, specifically handling library paths and extensions for:
- Windows: Uses
.liband.pyd(for Python modules) and.zipfor ONNX downloads. - Linux: Uses
.aand.soand.tgzfor ONNX downloads. Supports x86_64, aarch64, and armv7l. - macOS: Supports both x86_64 and Apple Silicon (arm64).
Sources: libpiper/CMakeLists.txt:14-80, CMakeLists.txt:60-70
Manual Building for Python
When installing from source or via setup.py, the project uses scikit-build to bridge Python and CMake. This process compiles the espeakbridge C module and ensures espeak-ng-data is copied into the package directory.
Sources: setup.py:34-40, CMakeLists.txt:1-10
Sources: CMakeLists.txt:10-86, setup.py:115-123
Conclusion
Piper offers a flexible installation path depending on the use case. Python users can quickly deploy via pip, while C++ developers can utilize the CMake-based build system to generate a standalone shared library with all necessary neural inference and phonemization dependencies bundled.