Building from Source

Relevant source files

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

• CMakeLists.txt
• libpiper/CMakeLists.txt
• libpiper/README.md
• setup.py
• README.md
• src/piper/espeakbridge.c

The Piper project provides multiple pathways for building its components from source, catering to different integration needs. This includes a standalone C++ library (libpiper) for low-level integration, a Python package (piper-tts) for high-level scripting, and a specialized C bridge for phonemization.

The build system is primarily driven by CMake and scikit-build, ensuring that complex dependencies like espeak-ng and onnxruntime are handled automatically across different platforms including Linux, Windows (x64), and macOS (x86_64/arm64).
Sources: libpiper/CMakeLists.txt:7-14, setup.py:34-40, README.md:1-15

Build Architectures

Piper's build process is divided into two main streams: the C++ Shared Library and the Python Module. Both streams share a dependency on espeak-ng, which is fetched and compiled as an external project during the build phase.

Build Component Overview

Component	Technology	Primary Build Tool	Key Dependencies
libpiper	C++/C	CMake	espeak-ng, onnxruntime
piper-tts	Python	setup.py (scikit-build)	onnxruntime, espeakbridge
espeakbridge	C	CMake / Python API	espeak-ng, Python Stable ABI

Sources: libpiper/CMakeLists.txt:100-115, CMakeLists.txt:45-50, setup.py:34-45

Dependency Flow Diagram

The following diagram illustrates how external dependencies are integrated into the final Piper binaries.

Building libpiper (C/C++ API)

The libpiper component is built using a standard CMake workflow. It is designed to be a standalone shared library that embeds the ONNX inference engine and the eSpeak-ng phonemizer.

Standard Build Sequence

To build and install the library to a local directory:

cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$PWD/install
cmake --build build
cmake --install build

Sources: libpiper/README.md:11-15

Internal Logic and Dependency Handling

1. espeak-ng: The build system uses ExternalProject_Add to clone a specific git tag of espeak-ng and builds it as a static library with CMAKE_POSITION_INDEPENDENT_CODE enabled.
2. onnxruntime: The system automatically detects the host architecture (Linux x64/aarch64/armv7l, Windows x64, or macOS x86_64/arm64) and downloads the corresponding pre-built binaries from Microsoft's GitHub releases.
3. Data Assets: After compilation, the espeak-ng-data directory is copied from the build artifacts to the install prefix to ensure the library can function immediately.

Sources: libpiper/CMakeLists.txt:24-43, libpiper/CMakeLists.txt:57-98, libpiper/CMakeLists.txt:134-141

Building the Python Module

The Python module build is managed by setup.py using scikit-build, which bridges the Python packaging world with the CMake build system.

Configuration and Requirements

The Python build requires Python 3.9+ and leverages the Stable ABI to ensure single-wheel compatibility across different Python versions within the same platform.

Feature	Description	File Reference
Compiler Standard	C++17	libpiper/CMakeLists.txt:8
Python Interface	C-style bridge (espeakbridge.c)	src/piper/espeakbridge.c
Build Backend	scikit-build	setup.py:34

Sources: setup.py:46-55, CMakeLists.txt:7-12, CHANGELOG.md:27-30

Build Sequence Diagram

The interaction between setup.py and CMake during the Python package installation is shown below.

Platform-Specific Build Notes

The build system contains logic to handle differences between Windows and Unix-like systems, particularly regarding library naming and data paths.

• Windows:
  • Uses .lib for static libraries and .pyd for Python modules.
  • Requires LIBESPEAK_NG_EXPORT definitions to resolve symbol thunk issues.
  • Sources: CMakeLists.txt:62-73, libpiper/CMakeLists.txt:15-18
• Linux/macOS:
  • Uses .a for static libraries and .so for shared modules.
  • Handles specific architectures like aarch64 and armv7l for onnxruntime downloads.
  • Sources: libpiper/CMakeLists.txt:20-22, libpiper/CMakeLists.txt:81-90

Conclusion

Building Piper from source involves a coordinated effort between CMake and Python build tools to manage complex native dependencies. By automating the retrieval of onnxruntime and the compilation of espeak-ng, the project provides a reproducible environment for generating both high-level Python packages and low-level C++ libraries.