Docker Deployment

Relevant source files

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

• README.md
• src/piper/http_server.py
• src/piper/main.py
• setup.py
• src/piper/download_voices.py
• libpiper/CMakeLists.txt

Piper provides a fast, local neural text-to-speech engine designed for efficient deployment in containerized environments. The deployment primarily focuses on providing a standalone Web Server or a Command-line Interface that can be bundled into Docker images for integration with platforms like Home Assistant or LocalAI.

The system is built to run entirely locally, embedding espeak-ng for phonemization and using onnxruntime for high-performance inference. This architecture ensures that once a Docker container is deployed, it does not require external API calls for speech synthesis, maintaining privacy and reducing latency.

Sources: README.md:3-33, src/piper/http_server.py:14-25

Deployment Architecture

The Docker deployment typically wraps the Piper Python package and its dependencies. The architecture consists of the Piper engine, pre-trained ONNX models, and supporting data files (espeak-ng data and tashkeel models).

The diagram above illustrates the internal components of a Piper container, showing how the synthesis engine interacts with the ONNX runtime and linguistic data.

Sources: setup.py:10-25, src/piper/http_server.py:53-85, libpiper/CMakeLists.txt:127-142

Web Server API

The most common Docker use case involves running Piper as an HTTP server using Flask. This allows other containers or external services to request audio synthesis via a REST API.

Endpoint Configuration

The server defaults to 0.0.0.0:5000 to allow external traffic within a Docker network.

Option	Argument	Default	Description
Host	--host	0.0.0.0	Network interface to bind to
Port	--port	5000	Port for the HTTP server
Model	-m, --model	Required	Path to the .onnx model file
Data Dir	--data-dir	Current Dir	Directory to search for voices
CUDA	--cuda	False	Enables GPU acceleration

Sources: src/piper/http_server.py:28-66

API Workflow

When a request is received, the server checks if the requested voice is loaded. If not, it attempts to load the model from the specified data directory before performing synthesis.

Environment Preparation

For successful Docker deployment, the container must include specific data directories and libraries. The setup.py and CMakeLists.txt files define the necessary assets that must be present in the image.

Required Data Files

• espeak-ng-data: Necessary for phonemization across different languages.
• Tashkeel: Required specifically for Arabic diacritization.
• ONNX Models: The .onnx model and its corresponding .onnx.json configuration file.

Sources: setup.py:10-25, libpiper/CMakeLists.txt:140-145

Automated Voice Management

The piper.download_voices module can be used during the Docker image build process or at container runtime to fetch specific voices from the HuggingFace repository.

# Example of downloading a voice within a container
from piper.download_voices import download_voice
from pathlib import Path

download_voice("en_US-lessac-medium", Path("/path/to/data"))

Sources: src/piper/download_voices.py:91-118

CLI Execution

Alternatively, Piper can be deployed as a short-lived container or a worker that processes text through a command-line interface. This is useful for batch processing or piping audio to other tools.

CLI Data Flow

1. Input: Text via standard input or --input-file.
2. Processing: Phonemization via espeak-ng followed by ONNX inference.
3. Output: Raw PCM bytes to standard output or a WAV file.

Summary

Piper's Docker deployment is centered around its ability to provide a localized, high-performance TTS service. By leveraging the Flask-based HTTP server, it integrates seamlessly into containerized microservice architectures. Deployment requires careful management of the espeak-ng-data and .onnx model files, which are essential for the engine's phonemization and synthesis stages.

Sources: README.md:1-20, src/piper/http_server.py:226-231