Skip to content

How to run Piper text-to-speech on your Mac, using Docker

Updated: 2024-06-17

Status: Work-in-progress

Goals

  • "I have an open-source text-to-speech engine on my Mac, with a variety of great-sounding voices."
  • "I can easily create high-quality voice files on my Mac."

What is Piper?

A fast, local neural text to speech system.

Piper Commands

echo 'Welcome to the world of speech synthesis!' | \
  ./piper --model en_US-lessac-medium.onnx --output_file welcome.wav

Piper Demo - Voice samples

Available Voices

Favorite & Interesting Voices

English / British

  • Danny - Sounds like a Professor

English / American

  • Amy - Calm, plain
  • Joe - Deep voice, calming, explaining
  • Kausal - A bit nerdy
  • Norman - Deep male voice

Multi-speakers

Installing Voices

You will need two files per voice:

  • A .onnx model file, such as en_US-lessac-medium.onnx
  • A .onnx.json config file, such as en_US-lessac-medium.onnx.json

Terminology

  • Multi-speaker: Multi-speaker models can quickly switch between different speakers
  • VITS

Video Tutorials

Resources

Piper for Python

pip install piper-tts

echo 'Welcome to the world of speech synthesis!' | piper \
  --model en_US-lessac-medium \
  --output_file welcome.wav

Piper HTTP server

HTTP GET request, using curl

curl -G --data-urlencode 'text=This is a test.' -o test.wav 'localhost:5000'

HTTP POST request, using curl

curl -X POST -H 'Content-Type: text/plain' --data 'This is a test.' -o test.wav 'localhost:5000'

Download voices

Test it out

echo 'Welcome to the world of speech synthesis!' | \
  ./piper --model en_US-lessac-medium.onnx --output_file welcome.wav

Input

Piper executable can accept JSON input when using the --json-input flag. Each line of input must be a JSON object with text field.

Example:

{ "text": "First sentence to speak." }
{ "text": "Second sentence to speak." }

The following example writes two sentences with different speakers to different files:

{ "text": "First speaker.", "speaker_id": 0, "output_file": "/tmp/speaker_0.wav" }
{ "text": "Second speaker.", "speaker_id": 1, "output_file": "/tmp/speaker_1.wav" }

Output formats

  • WAV

Getting help

  • Run piper --help for options

Piper on Docker

https://github.com/linuxserver/docker-piper

Shell access

docker exec -it piper /bin/bash

Monitor logs in real-time

docker logs -f piper

Docker

Update images with Docker Compose

docker-compose pull piper

Update container

docker-compose up -d piper

Remove un-used Docker images

docker image prune

Docker Compose vs Docker Run

  • docker run is command line based
  • docker-compose reads configuration data from a YAML file.

Docker run can only start one container at a time Docker-compose will configure and run multiple containers at a time.

More information about Docker Run & Docker Compose

Run Piper on Docker

Install Docker Desktop on Mac

  • Ensure Docker is installed

Clone Piper TTS Repository:

git clone https://github.com/rhasspy/piper.git
cd piper

Configure Piper TTS

Piper TTS requires a configuration file (config.json) to define the synthesis backend and other settings. You can use the provided example configuration file as a starting point.

cp config.example.json config.json

Build Docker Image

docker build -t piper-tts .

Run Piper TTS Container

Start a Docker container based on the piper-tts image, ensuring to mount the config.json file into the container:

docker run -d --name piper-tts \
  -p 5002:5002 \
  -v "$(pwd)/config.json:/app/config.json" \
  piper-tts
  • -d: Runs the container in detached mode (background).
  • --name piper-tts: Assigns a name to the container (optional but recommended).
  • -p 5002:5002: Maps port 5002 of the container to port 5002 on your host (adjust port numbers if necessary).
  • -v "$(pwd)/config.json:/app/config.json": Mounts the local config.json file into the container at /app/config.json.

Verify Piper TTS is Running:

Check the logs of the running container to verify that Piper TTS has started successfully:

docker logs piper-tts

Access Piper TTS

Once the container is running, Piper TTS should be accessible at http://127.0.0.1:5002/. You can interact with Piper TTS via HTTP requests.

Example HTTP requests using curl:

curl -X POST \
  http://localhost:5002/api/tts \
  -H 'Content-Type: application/json' \
  -d '{"text":"Hello, this is a test."}' \
  --output output.wav
  • -X POST: Specifies a POST request.
  • -H 'Content-Type: application/json': Sets the request header to specify JSON content.
  • -d '{"text":"Hello, this is a test."}': Sends JSON data containing the text to be synthesized.
  • --output output.wav: Specifies the output file (output.wav in this case) where the synthesized audio will be saved.

Example HTTP requests using Python requests:

import requests
import json

url = 'http://localhost:5002/api/tts'
data = {'text': 'Hello, this is a test.'}
headers = {'Content-Type': 'application/json'}

response = requests.post(url, headers=headers, data=json.dumps(data))

if response.status_code == 200:
    with open('output.wav', 'wb') as f:
        f.write(response.content)
else:
    print(f'Error: {response.status_code} - {response.text}')

Shut it down

When you're done using Piper TTS, stop and remove the Docker container:

docker stop piper-tts
docker rm piper-tts

Setup Piper using Docker Compose

Create a Docker Compose File (docker-compose.yml)

Create a docker-compose.yml file.

version: '3'
services:
  piper-tts:
    image: rhasspy/piper:latest
    ports:
      - "5002:5002"
    volumes:
      - ./config.json:/app/config.json
    environment:
      - TZ=UTC  # Timezone

Create a config.json file in the same directory where docker-compose.yml is located.

Example config.json file:

{
  "server": {
    "host": "0.0.0.0",
    "port": 5002
  },
  "tts": {
    "system": "espeak",
    "espeak": {
      "path": "/usr/bin/espeak"
    }
  }
}

Start Piper TTS Using Docker Compose

docker-compose up -d
  • -d: Runs containers in detached mode (in the background).

Verify Piper TTS is Running

docker-compose logs -f

You should see output indicating that Piper TTS is up and running without any errors.

Access Piper TTS

Once running, Piper TTS should be accessible at http://localhost:5002 from your web browser or through HTTP requests

Stop and Remove Containers

When you're done using Piper TTS, stop and remove the Docker containers:

docker-compose down

Piper Config File

Example:

{
  "server": {
    "host": "0.0.0.0",  
    "port": 5002
  },
  "tts": {
    "system": "espeak",
    "espeak": {
      "path": "/usr/bin/espeak" 
    }
  }
}