Piper Neural Text-to-Speech on AWS User Guide

Overview

This image runs Piper 1.5, the fast, local, neural text-to-speech engine, on Ubuntu 24.04 LTS. Piper is installed into a dedicated Python virtual environment under /opt/piper on Python 3.12 and run by an unprivileged piper system account under a systemd service that starts the HTTP server on boot. A high-quality English voice model (en_US-lessac-medium) is baked into the image, so the server synthesises speech fully offline the moment it boots - no model is fetched at first boot.

The server listens on the loopback address 127.0.0.1:5000; nginx fronts it on port 80 with HTTP Basic Authentication. A lightweight /health endpoint stays open for load balancers; every synthesis request requires the password. The default security group opens port 22 (SSH) and port 80 (HTTP) only, so port 5000 is never reachable externally and no text you synthesise leaves the instance.

On the first boot of every deployed instance a one-shot service generates a fresh password, unique to that instance, and writes it to /root/piper-credentials.txt (mode 0600, root only). No shared or default credentials ship in the image. Voice models live at /var/lib/piper/voices on a dedicated, independently resizable EBS data volume.

Prerequisites

• An AWS account subscribed to this product in AWS Marketplace.
• An EC2 key pair in your target region for SSH access.
• A security group allowing inbound TCP 22 (SSH) from your IP and TCP 80 (HTTP) from your users.
• Recommended instance type: m5.large or larger.

Connecting to your instance

Step 1 - Launch from the AWS Marketplace console

1. Open the product page in AWS Marketplace and choose Continue to Subscribe, then Continue to Configuration.
2. Select the Piper 1.5 on Ubuntu 24.04 delivery option and your region, then Continue to Launch.
3. Choose your instance type, VPC/subnet, key pair and the security group described above, and launch.

Step 2 - Launch from the AWS CLI

aws ec2 run-instances \
  --image-id ami-xxxxxxxxxxxxxxxxx \
  --instance-type m5.large \
  --key-name your-key \
  --security-group-ids sg-xxxxxxxx \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=piper-tts}]'

Step 3 - Connect to your instance

ssh -i your-key.pem ubuntu@<instance-public-ip>

Step 4 - Confirm the services are running

systemctl is-active piper-http.service nginx.service
curl -s http://127.0.0.1/health

Expected output:

active
active
ok

Step 5 - Retrieve your password

sudo cat /root/piper-credentials.txt

# Piper TTS - generated on first boot by piper-firstboot.service
PIPER_URL=http://<instance-public-ip>/
PIPER_USERNAME=admin
PIPER_PASSWORD=<your-unique-password>

The synthesis API is gated by HTTP Basic Authentication (user admin and the password above). Only /health is open.

Step 6 - Synthesise speech over the HTTP API

The /synthesize endpoint accepts a POST with JSON {"text": "..."} and returns a WAV file. Read the per-instance password from the credentials file and post some text:

PASS=$(sudo grep '^PIPER_PASSWORD=' /root/piper-credentials.txt | cut -d= -f2-)
curl -s -u "admin:$PASS" -X POST -H 'Content-Type: application/json' \
  -d '{"text":"Hello from Piper, deployed by cloudimg."}' \
  -o /tmp/hello.wav http://127.0.0.1/synthesize
file /tmp/hello.wav

Expected output:

/tmp/hello.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 16 bit, mono 22050 Hz

From your own machine, point the same request at the instance's public IP on port 80 (HTTP Basic auth, user admin):

curl -u admin:<your-unique-password> -X POST -H 'Content-Type: application/json' \
  -d '{"text":"Hello from Piper"}' -o hello.wav http://<instance-public-ip>/synthesize

Optional JSON fields include voice, speaker_id, length_scale (speaking rate), noise_scale and noise_w_scale. A request without valid credentials is rejected with 401 Unauthorized.

Step 7 - Confirm the runtime

/opt/piper/venv/bin/pip show piper-tts | grep ^Version

Version: 1.5.0

Adding more voices

The default en_US-lessac-medium voice ships baked in. Download additional voices into the dedicated voice store on the data volume, then reference them by name in the synthesis request or as the server default:

sudo -u piper /opt/piper/venv/bin/python -m piper.download_voices en_GB-alba-medium \
  --data-dir /var/lib/piper/voices
sudo systemctl restart piper-http.service

Browse the full voice catalogue at the Piper project's voice list. Each voice is an .onnx model plus an .onnx.json config stored under /var/lib/piper/voices.

Enabling HTTPS

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.example.com

certbot edits the nginx site at /etc/nginx/sites-available/cloudimg-piper to add the TLS listener and arranges automatic renewal.

Backup and maintenance

• Voice models live under /var/lib/piper/voices on their own EBS volume. Snapshot that volume to back up any voices you have added.
• The password is in the nginx htpasswd file /etc/nginx/.piper.htpasswd; rotate it with sudo htpasswd /etc/nginx/.piper.htpasswd admin.
• Restart with sudo systemctl restart piper-http.service; logs: sudo journalctl -u piper-http.service.

Support

cloudimg provides 24/7 technical support for this image by email and chat, covering Piper deployment, adding and selecting voices, tuning synthesis parameters, backups, TLS termination and scaling. Contact details are on the AWS Marketplace listing.