piper-speak

Simple text-to-speech wrapper for Piper TTS on Linux and macOS.

• piper-speak - Pipe text to speech with double-buffered playback
• speak-selection - Read highlighted text aloud (Linux/Wayland)
• speak-selection-macos - Read clipboard text aloud (macOS)

Features

• Double-buffered audio generation for gapless playback
• Automatic text chunking (by paragraph, then sentence)
• Handles long documents without memory issues
• Graceful Ctrl+C handling

Installation

Arch Linux (AUR)

yay -S piper-speak

Includes the default voice model (en_US-lessac-medium).

Build from source

Requires Go 1.21+

git clone https://github.com/kgn/piper-speak.git
cd piper-speak
go build -o piper-speak ./cmd/piper-speak/
sudo install -Dm755 piper-speak /usr/bin/piper-speak
sudo install -Dm755 scripts/speak-selection /usr/bin/speak-selection

# Download a voice model
mkdir -p ~/.local/share/piper/voices
curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx" \
    -o ~/.local/share/piper/voices/en_US-lessac-medium.onnx
curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json" \
    -o ~/.local/share/piper/voices/en_US-lessac-medium.onnx.json

macOS

# Install piper-tts via pip
pip3 install piper-tts

# Build piper-speak
git clone https://github.com/kgn/piper-speak.git
cd piper-speak
go build -o piper-speak ./cmd/piper-speak/
sudo install -Dm755 piper-speak /usr/local/bin/piper-speak
sudo install -Dm755 scripts/speak-selection-macos /usr/local/bin/speak-selection-macos

# Download a voice model
mkdir -p ~/.local/share/piper/voices
curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx" \
    -o ~/.local/share/piper/voices/en_US-lessac-medium.onnx
curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json" \
    -o ~/.local/share/piper/voices/en_US-lessac-medium.onnx.json

Dependencies

Linux:

• piper-tts - yay -S piper-tts-bin
• pipewire - pacman -S pipewire pipewire-pulse
• wl-clipboard - pacman -S wl-clipboard (for speak-selection)

macOS:

• piper-tts - pip3 install piper-tts
• afplay (built-in)

Usage

piper-speak

# Pipe text
echo "Hello world" | piper-speak

# Direct argument
piper-speak "Hello world"

# Adjust speed (lower = faster, default: 0.7)
echo "Slower speech" | piper-speak --speed 1.0

# Run in background
echo "Background speech" | piper-speak --bg

# Read a long document (automatically chunked)
cat large-document.txt | piper-speak

# Adjust chunk size (default: 500 characters)
cat book.txt | piper-speak --chunk-size 800

speak-selection

Reads highlighted text aloud. Press the hotkey again to stop.

Add a keybinding in your window manager:

Hyprland:

bind = SUPER SHIFT, period, exec, speak-selection

Sway:

bindsym $mod+Shift+period exec speak-selection

speak-selection-macos

Reads clipboard text aloud. Run again to stop. Copy text first, then trigger the script.

Set up a keyboard shortcut via System Settings > Keyboard > Shortcuts > Services, or use a tool like Raycast/Hammerspoon.

Configuration

Environment variables:

Variable	Default	Description
PIPER_VOICE_DIR	~/.local/share/piper/voices	User voice model directory
PIPER_VOICE	en_US-lessac-medium	Default voice model

Voice models are searched in user directory first, then /usr/share/piper-speak/voices.

Voices

Download additional voices from rhasspy/piper-voices:

# Example: download a different voice
curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high/en_US-ryan-high.onnx" \
    -o ~/.local/share/piper/voices/en_US-ryan-high.onnx
curl -L "https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/ryan/high/en_US-ryan-high.onnx.json" \
    -o ~/.local/share/piper/voices/en_US-ryan-high.onnx.json

# Use it
echo "Hello" | piper-speak --voice en_US-ryan-high

Popular English voices:

Voice	Quality	Description
en_US-lessac-medium	Medium	Clear American English (default)
en_US-lessac-high	High	Higher quality, slower
en_US-amy-medium	Medium	Female American English
en_US-ryan-medium	Medium	Male American English
en_GB-alan-medium	Medium	Male British English

License

MIT