Command Line Interface

Relevant source files

The following files were used as context for generating this wiki page:

• src/piper/__main__.py
• src/piper/config.py
• src/piper/voice.py
• src/piper/download_voices.py
• src/piper/http_server.py
• README.md

The Command Line Interface (CLI) is the primary entry point for users to interact with the Piper neural text-to-speech engine. It provides a robust set of tools for loading ONNX-based voice models, processing input text from multiple sources (standard input, command arguments, or files), and generating high-quality speech audio in various formats including WAV files and raw PCM streams.

The CLI is designed to be fast and local, utilizing onnxruntime for inference and embedding espeak-ng for phonemization. It supports advanced features such as multi-speaker selection, adjustable synthesis parameters (speed, noise, volume), and direct audio playback via external utilities like ffplay.

Sources: src/piper/__main__.py:13-20, README.md:1-20

CLI Architecture and Execution Flow

The CLI is implemented in the src/piper/__main__.py script, which uses Python's argparse module to handle user inputs. The execution flow follows a structured path from argument parsing to audio output generation.

Execution Logic

1. Argument Parsing: The system collects model paths, input text sources, and synthesis parameters.
2. Voice Loading: It attempts to locate the ONNX model file either via a direct path or by searching configured data directories.
3. Synthesis Configuration: A SynthesisConfig object is instantiated to hold parameters like speaker_id and length_scale.
4. Text Processing: Input is processed line-by-line, either from sys.stdin or provided files.
5. Audio Generation: The PiperVoice.synthesize method is called for each line, producing AudioChunk objects.
6. Output Routing: Depending on flags, audio is written to a single WAV, multiple WAVs in a directory, streamed as raw bytes to stdout, or played via an AudioPlayer.

Sources: src/piper/__main__.py:23-145, src/piper/voice.py:165-200

System Data Flow

The following diagram illustrates how text data is transformed into audio output through the CLI:

A flowchart showing the data path from user input through the synthesis engine to various output destinations.
Sources: src/piper/__main__.py:150-250

Configuration and Synthesis Parameters

The CLI provides granular control over the synthesis process through various command-line arguments. These arguments map directly to the SynthesisConfig data structure.

Synthesis Options Table

Argument	Description	Mapping	Default
-m, --model	Path to ONNX model file	model_path	Required
-s, --speaker	Id of speaker (multi-speaker models)	speaker_id	0
--length-scale	Controls phoneme length (speed)	length_scale	1.0
--noise-scale	Controls generator noise	noise_scale	0.667
--noise-w-scale	Controls phoneme width noise	noise_w_scale	0.8
--volume	Multiplier for output volume	volume	1.0
--sentence-silence	Seconds of silence after sentences	args.sentence_silence	0.0

Sources: src/piper/__main__.py:25-78, src/piper/config.py:114-135

Model Discovery Logic

If a direct path to a model is not found, the CLI searches through directories specified by the --data-dir flag. It looks for files named {model_name}.onnx within these paths.

A flowchart showing the model resolution logic used by the CLI.
Sources: src/piper/__main__.py:118-135

Output Management

Piper's CLI supports multiple output modes to accommodate different use cases, from batch processing to real-time streaming.

Output Modes and Behaviors

• WAV File: Using -f or --output-file. If - is provided, the WAV file header and data are written to standard output.
• Directory Batching: Using -d or --output-dir. This generates one WAV file per line of input text. Naming can be based on a timestamp or a sanitized version of the input text.
• Raw Audio: Using --output-raw. This bypasses WAV headers and streams raw 16-bit PCM bytes directly to stdout, suitable for piping into other audio processing tools.
• Direct Playback: If no output file is specified and ffplay is available, the CLI uses the AudioPlayer class to play audio in real-time.

Sources: src/piper/__main__.py:176-247, src/piper/__main__.py:46-60

Support Utilities

The Piper project includes secondary CLI utilities for managing voice assets.

Download Utility

The piper.download_voices module allows users to fetch models and configurations from the official HuggingFace repository. It parses voice strings in the format <language>-<name>-<quality> (e.g., en_US-lessac-medium).

A sequence diagram showing the interaction between the download utility and the remote repository.
Sources: src/piper/download_voices.py:17-100

HTTP Server CLI

A Flask-based web server is provided via src/piper/http_server.py. It shares many arguments with the main CLI but exposes synthesis via POST endpoints.

Endpoint	Method	Purpose
/	POST	Synthesize text provided in JSON body
/voices	GET	List locally available voices
/download	POST	Trigger download of a specific voice model

Sources: src/piper/http_server.py:100-245

Conclusion

The Piper CLI serves as a flexible and efficient interface for local neural text-to-speech. By combining comprehensive argument parsing with a modular synthesis pipeline, it enables users to integrate high-quality TTS into shell scripts, batch processing workflows, or real-time applications with minimal overhead.