Skip to main content

​
Overview

PiperTTSService provides high-quality neural text-to-speech synthesis through a self-hosted HTTP server. The service offers complete privacy and control with no external API dependencies, making it ideal for on-premise deployments and applications requiring data sovereignty.

Piper TTS API Reference

Pipecat’s API methods for Piper TTS integration

Example Implementation

Browse examples using Piper TTS

Piper Documentation

Official Piper TTS documentation and setup

HTTP Server Setup

Configure Piper HTTP server for Pipecat

​
Installation

To use Piper services, no additional Pipecat dependencies are required: 
pip install "pipecat-ai"  # Base installation is sufficient

​
Prerequisites

​
Piper Server Setup

Before using PiperTTSService, you need:
  1. Piper TTS Server: Set up a running Piper TTS server following the HTTP server documentation
  2. Voice Models: Download and configure voice models for your target languages
  3. Server Configuration: Configure server endpoint and voice selection

​
Required Configuration

  • Server URL: Configure the Piper server endpoint in your service initialization
  • Voice Models: Ensure required voice models are available on the server
Piper runs entirely locally, providing complete privacy and eliminating API key requirements.

​
Configuration

Piper offers two service implementations: PiperTTSService for local inference and PiperHttpTTSService for HTTP server-based synthesis.

​
PiperTTSService

Runs Piper locally, automatically downloading voice models as needed.
​
voice_id
str
required
deprecated
Piper voice model identifier (e.g. en_US-ryan-high). Deprecated in v0.0.105. Use settings=PiperTTSService.Settings(voice=...) instead.
​
settings
PiperTTSService.Settings
default:"None"
Runtime-configurable settings. See PiperTTSService Settings below.
​
download_dir
Path
default:"None"
Directory for storing voice model files. Defaults to the current working directory.
​
force_redownload
bool
default:"False"
Re-download the voice model even if it already exists locally.
​
use_cuda
bool
default:"False"
Use CUDA for GPU-accelerated inference.

​
PiperTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using PiperTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.
ParameterTypeDefaultDescription
modelstrNoneModel identifier. (Inherited.)
voicestrNoneVoice identifier. (Inherited.)
languageLanguage | strNoneLanguage for synthesis. (Inherited.)

​
PiperHttpTTSService

Connects to a running Piper HTTP TTS server.
​
base_url
str
required
Base URL for the Piper TTS HTTP server.
​
aiohttp_session
aiohttp.ClientSession
required
An aiohttp session for HTTP requests.
​
voice_id
str
default:"None"
deprecated
Piper voice model identifier (e.g. en_US-ryan-high). Deprecated in v0.0.105. Use settings=PiperHttpTTSService.Settings(voice=...) instead.
​
settings
PiperHttpTTSService.Settings
default:"None"
Runtime-configurable settings. See PiperHttpTTSService Settings below.

​
PiperHttpTTSService Settings

Runtime-configurable settings passed via the settings constructor argument using PiperHttpTTSService.Settings(...). These can be updated mid-conversation with TTSUpdateSettingsFrame. See Service Settings for details.
ParameterTypeDefaultDescription
modelstrNoneModel identifier. (Inherited.)
voicestrNoneVoice identifier. (Inherited.)
languageLanguage | strNoneLanguage for synthesis. (Inherited.)

​
Usage

​
Local Inference

from pipecat.services.piper import PiperTTSService

tts = PiperTTSService(
    settings=PiperTTSService.Settings(
        voice="en_US-ryan-high",
    ),
)

​
HTTP Server

Start the Piper HTTP server first: 
uv pip install "piper-tts[http]"
uv run python -m piper.http_server -m en_US-ryan-high
Then connect to it: 
import aiohttp
from pipecat.services.piper import PiperHttpTTSService

async with aiohttp.ClientSession() as session:
    tts = PiperHttpTTSService(
        base_url="http://localhost:5000",
        aiohttp_session=session,
        settings=PiperHttpTTSService.Settings(
            voice="en_US-ryan-high",
        ),
    )
The InputParams / params= pattern is deprecated as of v0.0.105. Use Settings / settings= instead. See the Service Settings guide for migration details.

​
Notes

  • Local execution: PiperTTSService runs entirely locally with no network requests. Voice models are automatically downloaded on first use.
  • GPU acceleration: Set use_cuda=True for GPU-accelerated inference with PiperTTSService (requires CUDA-compatible hardware).
  • Audio resampling: Audio output is automatically resampled to match the pipeline’s configured sample rate.
  • No API key required: Piper is open-source and runs locally, so no API credentials are needed.