A fast and local neural text-to-speech engine that embeds espeak-ng for phonemization.

This fork extends Piper's reach by providing a streamlined, robust build process specifically for Termux (Android), making it easily installable via pip install . and thus more universally accessible across various platforms.

Install with:

pip install piper-tts

• 🎧 Samples
• 💡 Demo
• 🗣️ Voices
• 🖥️ Command-line interface
• 🌐 Web server
• 🐍 Python API
• 🔧 C/C++ API
• 🏋️ Training new voices
• 🛠️ Building manually

---

🚀 Quick Start (Recommended Method)

Prerequisites

Ensure you have the necessary build tools installed:

pkg update && pkg install build-essential cmake git ninja-build

Installation

With the prerequisites in place, you can install the piper-tts package directly from this repository:

pip install .

This single command handles the download, compilation, and installation of all dependencies. For detailed build information, see the docs/BUILDING.md file.

Standard Linux, macOS, and Windows Builds

For standard desktop platforms, the build process also uses CMake to automate dependency handling.

• espeak-ng: This dependency is handled automatically. The build script will download and compile espeak-ng from source, then statically link it into the final espeakbridge library. You do not need to install it manually.

• onnxruntime: CURRENTLY INCOMPLETE: The build scripts for standard platforms do not yet link against onnxruntime. This is a known issue that will prevent the compiled program from functioning.

• Theory: Deep Wiki's analysis of this repo

The original, manual build guide and usage examples are preserved below for reference.

---

People/projects using Piper:

• Home Assistant
• NVDA - NonVisual Desktop Access
• Image Captioning for the Visually Impaired and Blind: A Recipe for Low-Resource Languages
• Video tutorial by Thorsten Müller
• Open Voice Operating System
• JetsonGPT
• LocalAI
• Lernstick EDU / EXAM: reading clipboard content aloud with language detection
• Natural Speech - A plugin for Runelite, an OSRS Client
• mintPiper
• Vim-Piper
• POTaTOS
• Narration Studio
• Basic TTS - Simple online text-to-speech converter.

---

🗣️ Usage

Once the package is installed, you can use Piper from the command line.

First, download a voice model if you haven't already:

python3 -m piper.download_voices

Command Line Options

Usage:
  python3 -m piper [OPTIONS] [-- TEXT]
  echo "TEXT" | python3 -m piper [OPTIONS]

Description:
  piper is a lightweight text-to-speech (TTS) command-line interface
  for Termux using Piper and eSpeak-ng.

Options:
  -m, --model MODEL_NAME
        Name of the ONNX voice model to use (without .onnx extension).
        This option is required.

  -f, --file OUTPUT_FILE
        Write synthesized audio to the given file (RAW format).
        Default: 'output.raw' if this option is used without a file name.

  --output-raw -
        Write audio output to standard output (stdout).
        This allows piping to audio players like 'play' or 'aplay'.

  -- TEXT
        Input text to synthesize. If not provided, text will be read from stdin.

Examples

1. Read text from clipboard and play output (requires sox package):

   termux-clipboard-get | python3 -m piper --model en_US-lessac-medium --output-raw | play -t raw -r 22050 -e signed-integer -b 16 -c 1 -

2. Write audio to a file:

   python3 -m piper -m fa_IR-gyro-medium -f output.raw -- "سلام دنیا"

3. Use default output file (output.raw) with stdin:

   echo "Hello world" | python3 -m piper -m en_US-mlm -f

Environment Variables

The piper command-line interface and Python API can be configured with the following environment variables:

Variable	Description
PIPER_VOICE_PATH	Path to the directory containing your downloaded voice models (.onnx and .onnx.json files). If not set, Piper will search in the current directory.
ESPEAK_DATA_PATH	Path to the espeak-ng-data directory. This is usually handled automatically if espeak-ng is installed correctly via pkg. You only need to set this if you are using a custom location for the espeak data.

Notes

• Output is always in 32-bit float RAW format at 22050Hz, mono.
• When using --output-raw -, the output can be piped directly to 'play' or other audio tools.
• This CLI is designed for use within Termux and supports local model/data directories.

🛠️ Building from Source & Development

For detailed instructions on building from source, setting up a development environment, or troubleshooting the build process, please refer to our comprehensive guide:

• 📄 docs/BUILDING.md

This document provides a deep dive into the build architecture, including the automated CMake process and manual verification steps.