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

# Pocket TTS

> Local CPU-only text-to-speech synthesis using kyutai-labs' pocket-tts

## Overview

`PocketTTSService` provides local, CPU-only text-to-speech synthesis using the [pocket-tts](https://github.com/kyutai-labs/pocket-tts) streaming model. It runs entirely on the host machine with no external API calls or authentication required. Model weights and voice prompts are downloaded from Hugging Face on first use.

The voice may be a predefined voice name (e.g. `"alba"`), a local `.wav` file to clone, an exported `.safetensors` voice state, or an `hf://` path. The voice can be changed at runtime; the language cannot, since model weights are loaded per language.

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

  <Card title="Example Implementation" icon="play" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/voice/voice-pockettts.py">
    Complete example with voice conversation
  </Card>

  <Card title="pocket-tts Repository" icon="book" href="https://github.com/kyutai-labs/pocket-tts">
    Official pocket-tts project and documentation
  </Card>

  <Card title="Settings Update Example" icon="gear" href="https://github.com/pipecat-ai/pipecat/blob/main/examples/update-settings/tts/tts-pockettts.py">
    Example showing runtime settings updates
  </Card>
</CardGroup>

## Installation

To use Pocket TTS, install the required dependencies:

```bash theme={null}
uv add "pipecat-ai[pocket-tts]"
```

This installs `pocket-tts>=2.1.0` and its dependencies.

## Prerequisites

### Local Setup

Pocket TTS runs locally and does not require an API key or external service. On first use, the service automatically downloads model weights and voice prompts from Hugging Face, which may block for a while.

<Note>
  The initial model download may take a few minutes depending on your connection
  speed. Subsequent runs use the cached files.
</Note>

## Configuration

### PocketTTSService

<ParamField path="temp" type="float" default="None">
  Sampling temperature for audio generation. When `None`, uses the pocket-tts
  model default.
</ParamField>

<ParamField path="quantize" type="bool" default="False">
  Quantize model weights for faster CPU inference (requires the `torchao`
  package).
</ParamField>

<ParamField path="settings" type="PocketTTSService.Settings" default="None">
  Runtime-configurable settings. Defaults to the `"alba"` voice and English. See
  [Settings](#settings) below.
</ParamField>

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `PocketTTSService.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 from base settings.)*                                                   |
| `voice`    | `str`             | `"alba"`      | Voice identifier (e.g. `"alba"`, `"jane"`), local `.wav` file, `.safetensors` state, or `hf://` path. |
| `language` | `Language \| str` | `Language.EN` | Language for synthesis. See supported languages below.                                                |

### Supported Languages

Pocket TTS supports the following languages:

| Language   | Code          |
| ---------- | ------------- |
| German     | `Language.DE` |
| English    | `Language.EN` |
| Spanish    | `Language.ES` |
| French     | `Language.FR` |
| Italian    | `Language.IT` |
| Portuguese | `Language.PT` |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.pocket_tts.tts import PocketTTSService

tts = PocketTTSService(
    settings=PocketTTSService.Settings(
        voice="alba",
    ),
)
```

### With Language Configuration

```python theme={null}
from pipecat.services.pocket_tts.tts import PocketTTSService
from pipecat.transcriptions.language import Language

tts = PocketTTSService(
    settings=PocketTTSService.Settings(
        voice="anna",
        language=Language.FR,
    ),
)
```

### With Voice Cloning

```python theme={null}
from pipecat.services.pocket_tts.tts import PocketTTSService

tts = PocketTTSService(
    settings=PocketTTSService.Settings(
        voice="/path/to/voice-sample.wav",
    ),
)
```

### With Quantization

```python theme={null}
from pipecat.services.pocket_tts.tts import PocketTTSService

tts = PocketTTSService(
    quantize=True,
    settings=PocketTTSService.Settings(
        voice="alba",
    ),
)
```

## Notes

* **Fully local**: Pocket TTS runs entirely on the host machine using CPU. No API keys, network access, or external services are required after the initial model download.
* **Model caching**: Model weights and voice prompts are downloaded from Hugging Face on first use and cached locally. Subsequent runs use the cached files.
* **Voice cloning**: The service supports voice cloning from `.wav` files, exported `.safetensors` voice states, or `hf://` paths.
* **Runtime voice updates**: The voice can be changed mid-conversation using `TTSUpdateSettingsFrame`. The voice state is re-derived lazily on the next utterance.
* **Language immutability**: The language cannot be changed at runtime since model weights are loaded per language.
* **Streaming output**: The service uses pocket-tts' streaming API, delivering audio frames incrementally as they are generated.
* **Metrics support**: The service supports TTFB (time to first byte) and usage metrics for performance monitoring.