Piper Text-to-Speech

Overview

PiperTTSService runs Piper neural text-to-speech in-process, and PiperHttpTTSService connects to a self-hosted Piper HTTP server. Both offer complete privacy and control with no external API dependencies, making them 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

Both services are imported from pipecat.services.piper.tts, which requires the piper extra:

uv add "pipecat-ai[piper]"

Prerequisites

Piper Server Setup

Before using PiperHttpTTSService, you need:

Piper TTS Server: Set up a running Piper TTS server following the HTTP server documentation
Voice Models: Download and configure voice models for your target languages
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.

str

default:"None"

deprecated

Piper voice model identifier (e.g. en_US-ryan-high). Deprecated in v0.0.105. Use settings=PiperTTSService.Settings(voice=...) instead.

PiperTTSService.Settings

default:"None"

Service settings. See PiperTTSService Settings below.

Path

default:"None"

Directory for storing voice model files. Defaults to Pipecat’s cache directory (~/.cache/pipecat/piper).

bool

default:"False"

Re-download the voice model even if it already exists locally.

bool

default:"False"

Use CUDA for GPU-accelerated inference.

PiperTTSService Settings

Settings passed via the settings constructor argument using PiperTTSService.Settings(...). The voice model is loaded once when the service is created, so updates sent with TTSUpdateSettingsFrame are not applied: the service logs a warning and keeps the original voice. See Service Settings for details.

Parameter	Type	Default	Description
`model`	`str`	`None`	Not sent by this service; reported only as the model name in metrics and traces. (Inherited.)
`voice`	`str`	`None`	Piper voice model identifier (e.g. `en_US-ryan-high`). (Inherited.) Required: raises `ValueError` when unset.
`language`	`Language \| str`	`None`	Language used to split text into sentences; not sent to Piper. (Inherited.)

PiperHttpTTSService

Connects to a running Piper HTTP TTS server.

str

required

Base URL for the Piper TTS HTTP server.

aiohttp.ClientSession

required

An aiohttp session for HTTP requests.

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.

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.

Parameter	Type	Default	Description
`model`	`str`	`None`	Not sent by this service; reported only as the model name in metrics and traces. (Inherited.)
`voice`	`str`	`None`	Voice identifier. (Inherited.)
`language`	`Language \| str`	`None`	Language used to split text into sentences; not sent to Piper. (Inherited.)

Usage

Local Inference

from pipecat.services.piper.tts import PiperTTSService

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

HTTP Server

Start the Piper HTTP server first:

uv add "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.tts 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",
        ),
    )

Notes

Local execution: PiperTTSService runs inference locally. If the voice model isn’t already in download_dir, it is downloaded when the service is created.
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.
GPL-3.0 license: Both services import the piper-tts package (the piper extra), which is GPL-3.0 licensed, and PiperTTSService runs it in-process. Distributing an application that includes it may subject the application to the GPL’s source-disclosure terms.

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Piper Text-to-Speech

Overview

Piper TTS API Reference

Example Implementation

Piper Documentation

HTTP Server Setup

Installation

Prerequisites

Piper Server Setup

Required Configuration

Configuration

PiperTTSService

PiperTTSService Settings

PiperHttpTTSService

PiperHttpTTSService Settings

Usage

Local Inference

HTTP Server

Notes

​Overview

Piper TTS API Reference

Example Implementation

Piper Documentation

HTTP Server Setup

​Installation

​Prerequisites

​Piper Server Setup

​Required Configuration

​Configuration

​PiperTTSService

​PiperTTSService Settings

​PiperHttpTTSService

​PiperHttpTTSService Settings

​Usage

​Local Inference

​HTTP Server

​Notes

Overview

Installation

Prerequisites

Piper Server Setup

Required Configuration

Configuration

PiperTTSService

PiperTTSService Settings

PiperHttpTTSService

PiperHttpTTSService Settings

Usage

Local Inference

HTTP Server

Notes