🍎 Installing Piper TTS on macOS — Step-by-Step Guide

[TacBotDEV]

️ What is Piper TTS?

Piper is a fast, neural text-to-speech engine that runs 100% offline — no data ever leaves your machine. It uses espeak-ng for phonemization and works natively on macOS (both Intel and Apple Silicon).

It supports 40+ languages, including Brazilian Portuguese (pt_BR), with high-quality voices.

---

Installing on macOS

1️⃣ Install Python 3.9+

Option A — Homebrew (recommended):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install [email protected]

Option B — Official Python:
Download the installer from python.org/downloads and run the .pkg file.

Verify the installation:

python3 --version
pip3 --version

---

2️⃣ Install Piper

pip3 install piper-tts

Recommendation: Use a virtual environment:

python3 -m venv piper-env
source piper-env/bin/activate
pip install piper-tts

---

3️⃣ Download a Voice

python3 -m piper.download_voices

To download a specific voice:

# Brazilian Portuguese
python3 -m piper.download_voices pt_BR-edresson-medium

# American English
python3 -m piper.download_voices en_US-lessac-medium

Voices are available at huggingface.co/rhasspy/piper-voices.

---

4️⃣ Test the Voice

python3 -m piper -m pt_BR-edresson-medium -f test.wav -- "Hello! This is a test message from Piper TTS on macOS."

To hear it directly through your speakers:

# Install ffplay via Homebrew
brew install ffmpeg

# Test
python3 -m piper -m pt_BR-edresson-medium -- "Hello, world!"

---

5️⃣ Using the Python API

import wave
from piper import PiperVoice, SynthesisConfig

voice = PiperVoice.load("pt_BR-edresson-medium.onnx")

with wave.open("output.wav", "wb") as wav_file:
    voice.synthesize_wav("Welcome to Piper TTS on Mac!", wav_file)

syn_config = SynthesisConfig(
    volume=1.0,
    length_scale=1.1,
    noise_scale=0.9,
    normalize_audio=True
)
with wave.open("adjusted.wav", "wb") as w:
    voice.synthesize_wav("Customizing the voice...", w, syn_config=syn_config)

---

6️⃣ HTTP Server (continuous use)

To use without reloading the model for each phrase:

python3 -m piper.http_server

Access at: http://localhost:5000

curl -X POST http://localhost:5000/synthesize \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello Piper server!", "voice": "pt_BR-edresson-medium"}' \
  --output audio.wav

---

7️⃣ GPU Acceleration on Mac (Apple Silicon)

On macOS with Apple Silicon (M1/M2/M3/M4), Piper automatically uses CoreML for acceleration. Install onnxruntime-coreml for even better performance:

pip install onnxruntime-coreml

from piper import PiperVoice
voice = PiperVoice.load("voice.onnx", use_cuda=False)  # CoreML is automatic on macOS

---

8️⃣ Automation with macOS Shortcuts

Create an Automator workflow or use the CLI in scripts:

# Script to read text aloud
TEXT="Important system notification"
python3 -m piper -m pt_BR-edresson-medium -- "$TEXT" | ffplay -autoexit -f s16le -ar 22050 -ac 1 -

---

macOS Tips

• Apple Silicon (M1-M4): Excellent performance — a 10-word phrase takes under 1 second
• Intel Mac: Works well too, just slightly slower on medium/large models
• Home Assistant Integration: Piper works as an external TTS server on macOS
• Audio formats: Piper outputs WAV natively; convert with ffmpeg to MP3, AAC, etc.
• Static binaries: Manual build available at github.com/OHF-Voice/piper1-gpl

---

Useful links:

• Voice samples
• Voice downloads
• Official documentation

Questions? Ask here!