> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pipecat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Piper

> Text-to-speech service implementation using the Piper TTS server

## 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.

<CardGroup cols={2}>
  <Card title="Piper TTS API Reference" icon="code" href="https://reference-server.pipecat.ai/en/latest/api/pipecat.services.piper.tts.html">
    Pipecat's API methods for Piper TTS integration
  </Card>

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/tree/main/examples">
    Browse examples using Piper TTS
  </Card>

  <Card title="Piper Documentation" icon="book" href="https://github.com/OHF-Voice/piper1-gpl">
    Official Piper TTS documentation and setup
  </Card>

  <Card title="HTTP Server Setup" icon="server" href="https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/API_HTTP.md">
    Configure Piper HTTP server for Pipecat
  </Card>
</CardGroup>

## Installation

To use Piper services, no additional Pipecat dependencies are required:

```bash theme={null}
uv add "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](https://github.com/OHF-Voice/piper1-gpl/blob/main/docs/API_HTTP.md)
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

<Tip>
  Piper runs entirely locally, providing complete privacy and eliminating API
  key requirements.
</Tip>

## 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.

<ParamField path="voice_id" type="str" required deprecated>
  Piper voice model identifier (e.g. `en_US-ryan-high`). *Deprecated in
  v0.0.105. Use `settings=PiperTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="settings" type="PiperTTSService.Settings" default="None">
  Runtime-configurable settings. See [PiperTTSService
  Settings](#piperttsservice-settings) below.
</ParamField>

<ParamField path="download_dir" type="Path" default="None">
  Directory for storing voice model files. Defaults to the current working
  directory.
</ParamField>

<ParamField path="force_redownload" type="bool" default="False">
  Re-download the voice model even if it already exists locally.
</ParamField>

<ParamField path="use_cuda" type="bool" default="False">
  Use CUDA for GPU-accelerated inference.
</ParamField>

#### 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](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default | Description                            |
| ---------- | ----------------- | ------- | -------------------------------------- |
| `model`    | `str`             | `None`  | Model identifier. *(Inherited.)*       |
| `voice`    | `str`             | `None`  | Voice identifier. *(Inherited.)*       |
| `language` | `Language \| str` | `None`  | Language for synthesis. *(Inherited.)* |

### PiperHttpTTSService

Connects to a running Piper HTTP TTS server.

<ParamField path="base_url" type="str" required>
  Base URL for the Piper TTS HTTP server.
</ParamField>

<ParamField path="aiohttp_session" type="aiohttp.ClientSession" required>
  An aiohttp session for HTTP requests.
</ParamField>

<ParamField path="voice_id" type="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.*
</ParamField>

<ParamField path="settings" type="PiperHttpTTSService.Settings" default="None">
  Runtime-configurable settings. See [PiperHttpTTSService
  Settings](#piperhttpttsservice-settings) below.
</ParamField>

#### 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](/pipecat/fundamentals/service-settings) for details.

| Parameter  | Type              | Default | Description                            |
| ---------- | ----------------- | ------- | -------------------------------------- |
| `model`    | `str`             | `None`  | Model identifier. *(Inherited.)*       |
| `voice`    | `str`             | `None`  | Voice identifier. *(Inherited.)*       |
| `language` | `Language \| str` | `None`  | Language for synthesis. *(Inherited.)* |

## Usage

### Local Inference

```python theme={null}
from pipecat.services.piper import PiperTTSService

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

### HTTP Server

Start the Piper HTTP server first:

```bash theme={null}
uv add "piper-tts[http]"
uv run python -m piper.http_server -m en_US-ryan-high
```

Then connect to it:

```python theme={null}
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",
        ),
    )
```

<Tip>
  The `InputParams` / `params=` pattern is deprecated as of v0.0.105. Use
  `Settings` / `settings=` instead. See the [Service Settings
  guide](/pipecat/fundamentals/service-settings) for migration details.
</Tip>

## 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.