PiperRead

English | Français | Deutsch | Español

Description

PiperRead is a lightweight automation solution designed to bring high-quality neural text-to-speech (TTS) to Linux desktops.

Official Website: piperread.davalan.fr

Unlike cloud-based solutions, PiperRead operates entirely offline (locally) thanks to the Piper engine. It acts as a bridge between your desktop environment (Clipboard/Mouse) and the synthesis engine.

It allows you to read aloud any text selected with the mouse or copied to the clipboard, without requiring a complex screen reader.

Two ways to read

The two are independent: neither drives the other, and either works without the other. Installation starts with the choice between them.

• The launcher (piperread, or read.sh from a clone): a button or a keyboard shortcut reads the selection. Nothing runs between two readings; the voice is loaded again at each click, so the first sound comes about 1.3 seconds later.
• The interface (piperread-gui, a separate package): a resident tray icon that starts with your session and keeps the voice loaded. Reading starts within 168 milliseconds of the click, and it adds pause, resume and sentence-by-sentence navigation. It also runs on Windows.

Started together, both read at the same time (two voices overlapping): pick one gesture.

The interface is an icon in the notification area; a right click on it opens its menu.

       

_{KDE Plasma, GNOME (with the AppIndicator extension) and Windows 11}

Use Cases

• Accessibility: Quick reading of content for people with mild visual impairment or eye fatigue.
• Productivity: Listening to articles or documents while performing another task.
• Proofreading: Hearing your own text read by a third-party voice to detect errors.

Key Features

• Total Privacy: 100% local processing. No data is sent to any cloud.
• Zero Latency: no network round trip, and measured: about 1.3 seconds from the launcher to the first sound, 168 milliseconds from a click to the first sound with the resident interface (measurements below).
• Universal Compatibility: Automatically detects and adapts to Wayland (Debian 12/13) or X11.
• Smart Selection: Prioritizes mouse selection (primary) and switches to clipboard if no selection is active.
• Isolation: Runs in its own Python virtual environment to avoid polluting your system.

---

Installation from a package

Do you want the interface?

Terminal and button. A keyboard shortcut, the piperread command or the Read Selection button in your applications menu reads the selection. One package, about 195 MB to download and 680 MB once installed on Debian 13.

With the interface. The same, plus a tray icon that starts with your session, keeps the voice loaded and adds pause, resume and sentence-by-sentence navigation. Two packages in one "all in one" archive, about 460 MB to download and 1.4 GB once installed on Debian 13, because the interface uses Qt (PySide6), which the distributions do not package.

The figures were measured in a container on Debian 13, dependencies included (other distributions: 117 to 304 MB and 329 to 792 MB for the terminal, 421 to 483 MB and 1.26 to 1.49 GB with the interface). If you are not sure, take the terminal and button: the interface can be added later in one command. Follow one sequence from its first step to its last; the prerequisites are installed by the package manager.

Terminal and button

1. Download the package for your system from the download page or from the latest release. The Release stores ~ as . in file names (piperread_0.4.1.beta_all.deb for piperread_0.4.1~beta_all.deb): in the command below, type the name of the file you downloaded.

2. Install it:

   # Debian 12 and 13, Ubuntu 22.04 and 24.04, Linux Mint
   sudo apt install ./piperread_0.4.1~beta_all.deb
   
   # Fedora 44
   sudo dnf install ./piperread-0.4.1~beta-1.fc44.noarch.rpm
   
   # openSUSE Leap 16.0
   sudo zypper install ./piperread-0.4.1~beta-1.leap160.noarch.rpm
   
   # Arch Linux
   sudo pacman -U ./piperread-0.4.1beta-1-any.pkg.tar.zst

   The package installs the Piper engine with pip when it is configured, with network access needed at that moment only. It ships no voice.

3. Add a voice. The first line of piperread --list-voices is the exact command that installs the recommended voice of your language; the second command below offers that voice and asks for confirmation.

   piperread --list-voices
   piperread --download-voice

4. Select a text with the mouse, then run piperread (or click Read Selection in your applications menu). Check the installation with piperread --diagnose.

With the interface

1. Download the "all in one" archive for your distribution family (debian, fedora, opensuse or arch) from the download page or from the latest release. It holds piperread and piperread-gui, and nothing else.

2. Extract it and install both packages in one command:

   # Debian 12 and 13, Ubuntu 22.04 and 24.04, Linux Mint
   tar -xzf piperread-all-in-one-0.4.1-beta-debian.tar.gz
   sudo apt install ./piperread_0.4.1~beta_all.deb ./piperread-gui_0.4.1~beta_all.deb
   
   # Fedora 44
   tar -xzf piperread-all-in-one-0.4.1-beta-fedora.tar.gz
   sudo dnf install ./piperread-0.4.1~beta-1.fc44.noarch.rpm ./piperread-gui-0.4.1~beta-1.fc44.noarch.rpm
   
   # openSUSE Leap 16.0
   tar -xzf piperread-all-in-one-0.4.1-beta-opensuse.tar.gz
   sudo zypper install ./piperread-0.4.1~beta-1.leap160.noarch.rpm ./piperread-gui-0.4.1~beta-1.leap160.noarch.rpm
   
   # Arch Linux
   tar -xzf piperread-all-in-one-0.4.1-beta-arch.tar.gz
   sudo pacman -U ./piperread-0.4.1beta-1-any.pkg.tar.zst ./piperread-gui-0.4.1beta-1-any.pkg.tar.zst

   The installation fetches the engine, then Qt (about 245 MB) into private virtual environments, with network access needed at that moment only. No voice is shipped.

3. Start the interface: choose PiperRead in your applications menu, or run piperread-gui --play (it also starts by itself at your next session). With no voice installed, a window called "Download a voice" opens: choose a voice and click Download. Nothing is downloaded before that click.

4. Select or copy a text, then click the tray icon: it reads when stopped, pauses while reading and resumes when paused.

The packages were validated in containers (installation, update from the previous version, diagnostic and removal) on Debian 12 and 13, Ubuntu 22.04 and 24.04, Fedora 44 and Arch Linux. On openSUSE Leap 16.0, installation, diagnostic and removal were validated in a container. A container proves the installation, the diagnostic and the removal, not the sound, the clipboard, the menu entry or the display. The manual is available as a page (man piperread) and as a PDF in four languages on the download page.

With the interface, on Windows

On Windows, only the interface is available, as a self-contained folder.

1. Download piperread-gui-windows.zip from the latest release.
2. Unzip it anywhere, keeping the folder whole.
3. Double-click piperread-gui.exe. With no voice installed, the "Download a voice" window opens: choose a voice and click Download. (By hand: put two files with the same name, <name>.onnx and <name>.onnx.json, from rhasspy/piper-voices, in the voices folder.)
4. Copy a text with Ctrl+C, then click the tray icon.

The build is not signed with a certificate Windows recognises: SmartScreen may warn on the first launch (choose "More info", then "Run anyway"). It reads the clipboard only, not the mouse selection. It is an executable built on Windows and tested by hand on Windows 11; there is no automated test matrix for Windows as there is for the Linux packages.

Prerequisites

Before installing from the sources, ensure your system has the required audio and clipboard tools.

# System update
sudo apt update

# Install Python, Audio, and Clipboard tools
# (Installs both wl-clipboard for Wayland and xsel for X11 to ensure compatibility)
sudo apt install -y python3 python3-venv python3-pip alsa-utils wl-clipboard xsel libnotify-bin

---

Installation from the sources

Since this project relies on large voice models and a specific virtual environment, you must initialize the project after cloning it.

1. Clone the repository

mkdir -p $HOME/git/piper
cd $HOME/git/piper
git clone https://github.com/RonanDavalan/PiperRead.git
cd PiperRead

2. Initialize the environment (Critical)

This step creates the Python isolation, installs the engine, then downloads the voice you choose. ./read.sh --list-voices lists the proposed voices with their licence, size and listening links; the voice quality is a matter of personal taste.

# Create virtual environment
python3 -m venv piper-env

# Install Piper TTS Engine
./piper-env/bin/pip install piper-tts

# Download a voice (see the choices with ./read.sh --list-voices)
./read.sh --download-voice en_US-ljspeech-medium

3. Configure permissions

chmod 700 read.sh

4. Desktop Integration (Icon and Menu)

To launch PiperRead like a native application:

# Create local applications and icons folders
mkdir -p $HOME/.local/share/applications $HOME/.local/share/icons/hicolor/scalable/apps

# Install the icon
cp Ressources/piperread.svg $HOME/.local/share/icons/hicolor/scalable/apps/

# Generate the desktop file with the actual installation path
sed "s|\$HOME/git/piper/PiperRead|$(pwd)|g" Ressources/PiperRead.desktop > $HOME/.local/share/applications/piperread.desktop

# Update menu database
update-desktop-database $HOME/.local/share/applications

5. The interface

The tray interface lives in the gui/ folder of the repository and runs from a clone too, with its own Python environment: see gui/README.md. Once that environment is set up, start the interface with gui/.venv/bin/python3 -m piperread_gui.app; with the piperread-gui package installed, the command is piperread-gui.

---

Usage

Method 1: Mouse Selection (Recommended)

1. Highlight text in any application (Browser, PDF, Editor).
2. Click the PiperRead icon in your menu (or use your custom keyboard shortcut).
3. The text is read immediately.

Method 2: Clipboard

1. Copy text (Ctrl+C).
2. Launch PiperRead.

Stopping Playback

Run piperread --stop (or ./read.sh --stop from a clone) to end the reading, --pause to suspend it and --resume to continue where it stopped. Bind these commands to keyboard shortcuts if you like.

The resident interface

The piperread-gui package starts with your session (a Linux desktop reads its autostart entry; on Windows, PiperRead adds itself to the startup programs at the first launch). A tray icon appears; the voice loads in the background and stays loaded, and while a sentence plays the next one is already being synthesized.

• Left click on the icon: read when stopped, pause while reading, resume when paused.
• Right click: the menu (Play, Pause, Stop, Previous sentence, Next sentence, Settings, Restart, Quit), in the language of your configuration.
• What is read: the mouse selection, or the clipboard when nothing is selected (Linux, the same order as the launcher); the clipboard only on Windows. Markdown markup is removed first.
• Settings: the menu entry opens a dialog for the voice, the speed, the language and "Start with the session" (on by default; untick it to stop the automatic start), with a "Download a voice..." button. It writes the same piperread.conf as the launcher.

The interface is also driven from the command line, which is how you bind it to keyboard shortcuts:

piperread-gui --play      # read; starts the interface first if it is not running
piperread-gui --pause
piperread-gui --resume
piperread-gui --stop
piperread-gui --next
piperread-gui --previous
piperread-gui --quit

Except --play, these commands report an error when no interface is running. On desktops that show a tray natively (KDE Plasma, XFCE, Cinnamon, MATE, LXQt) the icon simply appears. GNOME shows no tray by default: PiperRead says so once in a notification and stays fully usable through the commands above; to get the icon, install the "AppIndicator and KStatusNotifierItem Support" extension.

Measured latency

"Zero latency" means there is no network round trip between the selection and the first sound: everything runs on your machine. The duration itself was measured on 23 September 2026, on the maintainer's machine (32 cores) with the fr_FR-siwis-medium voice. It varies with the machine and the voice; treat it as an order of magnitude, not a guarantee.

Path	Measured
Launcher (read.sh auto), voice loaded at each click	1.31 to 1.34 s from the launch to the first audio byte
Interface, voice already loaded	168 ms from the click to the opening of the audio stream

At rest the interface uses no CPU; its memory is about 100 MB, plus 150 MB (voice loaded) to 370 MB (after use) for the synthesis server it starts, which listens on 127.0.0.1 only.

Configuration

Four settings can be adjusted: reading speed (a multiplier from 0.5 to 3.0, 1 is the natural voice), voice (the model name, as listed by --list-voices), lang (the message language: en, fr, de or es) and telemetry (on or off, see below). Each one is resolved in this order — the first level that provides a valid value wins:

1. Command-line option — --speed 1.25, --voice en_US-ljspeech-medium, --lang en (telemetry has no option).
2. Environment variable — PIPERREAD_SPEED, PIPERREAD_VOICE, PIPERREAD_LANG, PIPERREAD_TELEMETRY.
3. Configuration file — ~/.config/piperread/piperread.conf (on Windows, %USERPROFILE%\.config\piperread\piperread.conf), one key=value line per setting:

   speed=1.25
   voice=en_US-ljspeech-medium
   lang=en
   telemetry=off
   

4. Default — natural speed, the first installed voice in alphabetical order, English messages, telemetry off.

An invalid value at any level below the option is ignored and the next level is tried instead; an invalid command-line option stops the reading.

Engine telemetry

The inference library that Piper pulls in (onnxruntime) sends usage events to Microsoft by default. PiperRead turns them off before starting the engine, so that reading stays offline: strace shows no external connection while reading, with the launcher and with the interface. On Windows, the library writes its events to the system, which may forward them according to your privacy settings; PiperRead calls the library's own switch, and a measurement showed 4 initialisation events remaining against 15 without it. telemetry=on (or PIPERREAD_TELEMETRY=on) turns them back on.

---

Quality

This project was born from a discovery: the impressive quality of the Piper engine for a fully free and local solution.

• Natural Vocal Rendering: The choice of this neural technology allows for fluid and poised reading, making listening comfortable over time.
• Lightweight Architecture: PiperRead is not a heavy application, but a minimalist orchestrator. It connects your desktop and the audio engine with an almost non-existent system footprint.
• Clean Installation: The strict use of virtual environments (venv) ensures that the software remains confined and does not modify your main system libraries.

---

Project Origin

The impetus for this project comes from my brother, a historic Debian user, who identified Piper as a useful solution for local TTS.

---

Credits & "Vibe Coding"

The PiperRead project is the result of a hybrid Human-AI collaboration:

• Ronan Davalan: Architect & Arbiter. Product vision, security requirements, project direction, validation and testing. All architectural decisions are validated by him.
• Claude Code (Anthropic): Systems Engineer & Lead Developer. Implementation of the Bash scripts, the documentation and the website; technical choices within the validated architecture. Principal author of the source code.
• Google Gemini: Synthesizer & Strategic Advisor. Independent architectural analysis, logical conflict resolution, workflow optimisation, cross-validation of technical decisions.
• Muse Spark: Synthesizer & Strategic Advisor. Replaces Gemini in some sessions, with good results; some of its answers were passed on to Claude Code.
• DeepSeek: Cleanup of the project's working framework at the start of the project.
• MiMo v2.5 (Xiaomi, via opencode): Third-party review of the translations (manual page and three guides), 21 September 2026; part of its remarks held, part did not.
• Publication Guarantor (Claude Code, Anthropic): Examines each version against the project's publication rules before anything is published, and writes its opinion; a separate session with its own framework.
• Core Engine: Piper TTS, licensed GPL-3.0-or-later. On Linux it is installed on your machine by pip and called as an external program; the Windows archive embeds it, with its GPL-3.0-or-later licence text and the location of its sources (folder licenses\ and section "Licenses" of the archive's README.txt).

Licenses

PiperRead is released under the MIT licence (LICENSE). The Windows archive piperread-gui-windows.zip also embeds Piper (GPL-3.0-or-later) and Qt for Python (LGPL-3.0-only): their licence texts are in its licenses\ folder, and the "Licenses" section of its README.txt gives the location of their sources and the versions embedded.