Using with Docker

Piper provides a Dockerfile for easy containerization, allowing you to build and run the application in a consistent, isolated environment. This is ideal for deployment and ensuring all dependencies are correctly managed.

Building the Docker Image

To build the Docker image, navigate to the root of the piper1-gpl repository and run the following command:

docker build -t piper-tts .

This command will execute the multi-stage build defined in the Dockerfile. It first creates a builder stage to compile the necessary components and then copies the final artifacts into a slim production image.

Running the Docker Container

The Docker image uses an entrypoint.sh script, which allows you to run different Piper commands easily. The main commands are speak, download, and server.

By default, the container's working directory for voice data is /data. It is highly recommended to mount a local directory to this path to persist your downloaded voice models.

Creating a Data Directory

First, create a local directory to store your voices:

mkdir -p ./piper-data

1. Downloading Voices

To download voices into your local data directory, run the download command:

docker run -it --rm -v ./piper-data:/data piper-tts download en_US-lessac-medium

This will download the en_US-lessac-medium voice files and store them in your local ./piper-data directory.

2. Synthesizing Speech (Speak Command)

To synthesize text to a WAV file, use the speak command. The synthesized audio will be written to stdout, so you should redirect it to a file.

docker run -i --rm -v ./piper-data:/data piper-tts speak -m en_US-lessac-medium.onnx -- 'Hello from inside a Docker container.' > output.wav

3. Running the HTTP Server

To run Piper as an HTTP server, use the server command. You'll need to publish the container's port (5000) to your host machine.

docker run -it --rm -p 5000:5000 -v ./piper-data:/data piper-tts server -m en_US-lessac-medium.onnx

The server will start and be accessible at http://localhost:5000. You can then send requests to it as described in the HTTP API documentation.

To run the server in the background (detached mode), add the -d flag:

docker run -d -p 5000:5000 -v ./piper-data:/data piper-tts server -m en_US-lessac-medium.onnx