HTTP Server API
Relevant source files
The following files were used as context for generating this wiki page:
The Piper HTTP Server API provides a web-based interface for the Piper text-to-speech engine. Built using the Flask framework, it allows users to discover available voice models, download new voices from remote repositories, and perform high-speed, local speech synthesis via HTTP requests.
The server serves as a bridge between the core PiperVoice synthesis logic and external applications, enabling integration with platforms like Home Assistant or any client capable of making HTTP POST requests. It handles model management by checking local data directories and can dynamically load voices as requested by the client.
Sources: src/piper/http_server.py:1-25, README.md:10-15
Server Architecture and Initialization
The HTTP server is initialized through a CLI entry point that configures the host, port, and default voice model. Upon startup, the server performs a lookup for the specified ONNX model file across multiple data directories. If found, it pre-loads the default voice into memory using the PiperVoice class.
The server maintains a loaded_voices dictionary to cache PiperVoice instances, preventing redundant disk I/O when switching between frequently used voices during synthesis requests.
Sources: src/piper/http_server.py:31-92, src/piper/voice.py:165-200
API Endpoints
1. Speech Synthesis (POST /)
The primary endpoint for generating audio. It accepts a JSON payload containing the text to be spoken and optional synthesis parameters. The server returns a raw WAV file stream.
Request Payload Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
text | string | Yes | The input text to be converted to speech. |
voice | string | No | The ID of the voice model to use. |
speaker_id | integer | No | ID of the speaker for multi-speaker models. |
length_scale | float | No | Controls phoneme length (speed). |
noise_scale | float | No | Controls generator noise. |
noise_w_scale | float | No | Controls phoneme width noise. |
Sources: src/piper/http_server.py:161-205, src/piper/config.py:118-138
2. List Downloaded Voices (GET /voices)
Scans all configured data directories for .onnx files and their corresponding .onnx.json metadata files. It returns a JSON object where keys are model IDs and values are the voice configurations.
Sources: src/piper/http_server.py:97-126
3. List Remote Voices (GET /all-voices)
Fetches the master voices.json from the HuggingFace piper-voices repository. This allows clients to see all voices available for download even if they are not stored locally.
Sources: src/piper/http_server.py:128-135, src/piper/download_voices.py:19-21
4. Download Voice (POST /download)
Triggers the asynchronous download of a voice model (.onnx) and its metadata (.onnx.json) to the server's download directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
voice | string | Yes | The voice name (e.g., "en_US-lessac-medium"). |
force_redownload | boolean | No | If true, overwrites existing local files. |
Sources: src/piper/http_server.py:137-159, src/piper/download_voices.py:73-100
Data Flow: Synthesis Request
When a synthesis request is received, the server orchestrates phonemization, ONNX inference, and WAV encoding.
The server utilizes io.BytesIO to construct the WAV file in memory. It iterates through audio_chunk objects produced by voice.synthesize, setting WAV parameters (sample rate, width, channels) from the first chunk received. If a sentence_silence value is configured, the server inserts silence frames between sentence chunks.
Sources: src/piper/http_server.py:207-241, src/piper/voice.py:270-320
Configuration and Defaults
The server supports several CLI arguments that define global default behaviors if not overridden in individual API requests.
| Argument | Default | Description |
|---|---|---|
--host | 0.0.0.0 | Network interface to bind to. |
--port | 5000 | Port for the HTTP server. |
--model | Required | Path to the default ONNX model. |
--cuda | False | Use GPU for synthesis. |
--data-dir | cwd | Directories to search for models. |
--sentence-silence | 0.0 | Seconds of silence between sentences. |
Sources: src/piper/http_server.py:33-72, src/piper/config.py:13-20
Summary
The HTTP Server API in Piper provides a flexible and efficient way to deploy text-to-speech services locally. By leveraging Flask for endpoint management and ONNX Runtime for high-performance inference, it supports dynamic model loading and real-time audio generation. Its ability to interface with remote repositories for voice management makes it a self-contained solution for voice synthesis applications.
Sources: src/piper/http_server.py, README.md