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

# Kokoro

> Local text-to-speech synthesis using Kokoro ONNX

## Overview

`KokoroTTSService` provides local, offline text-to-speech synthesis using the [kokoro-onnx](https://github.com/thewh1teagle/kokoro-onnx) engine. It runs entirely on the host machine with no external API calls or authentication required. Model files are automatically downloaded to `~/.cache/kokoro-onnx/` on first use.

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

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

  <Card title="kokoro-onnx Repository" icon="book" href="https://github.com/thewh1teagle/kokoro-onnx">
    Official kokoro-onnx 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-kokoro.py">
    Example showing runtime settings updates
  </Card>
</CardGroup>

## Installation

To use Kokoro TTS, install the required dependencies:

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

This installs `kokoro-onnx>=0.5.0` and its dependencies.

## Prerequisites

### Local Setup

Kokoro runs locally and does not require an API key or external service. On first use, the service automatically downloads two model files to `~/.cache/kokoro-onnx/`:

* `kokoro-v1.0.onnx` -- the ONNX speech synthesis model
* `voices-v1.0.bin` -- the voice data file

You can also provide custom paths to pre-downloaded model files via the `model_path` and `voices_path` constructor parameters.

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

## Configuration

### KokoroTTSService

<ParamField path="model_path" type="str" default="None">
  Path to a custom ONNX model file. When `None`, the model is automatically
  downloaded to `~/.cache/kokoro-onnx/kokoro-v1.0.onnx`.
</ParamField>

<ParamField path="voices_path" type="str" default="None">
  Path to a custom voices binary file. When `None`, the file is automatically
  downloaded to `~/.cache/kokoro-onnx/voices-v1.0.bin`.
</ParamField>

<ParamField path="voice_id" type="str" default="None" deprecated>
  Voice identifier for synthesis. *Deprecated in v0.0.105. Use
  `settings=KokoroTTSService.Settings(voice=...)` instead.*
</ParamField>

<ParamField path="params" type="InputParams" default="None" deprecated>
  *Deprecated in v0.0.105. Use `settings=KokoroTTSService.Settings(...)`
  instead.*
</ParamField>

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

### Settings

Runtime-configurable settings passed via the `settings` constructor argument using `KokoroTTSService.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`             | `None`        | Voice identifier (e.g. `"af_heart"`).               |
| `language` | `Language \| str` | `Language.EN` | Language for synthesis. See supported languages.    |

### Supported Languages

Kokoro supports the following languages:

| Language          | Code             |
| ----------------- | ---------------- |
| English (US)      | `Language.EN_US` |
| English (UK)      | `Language.EN_GB` |
| English (generic) | `Language.EN`    |
| Spanish           | `Language.ES`    |
| French            | `Language.FR`    |
| Hindi             | `Language.HI`    |
| Italian           | `Language.IT`    |
| Japanese          | `Language.JA`    |
| Portuguese        | `Language.PT`    |
| Chinese           | `Language.ZH`    |

## Usage

### Basic Setup

```python theme={null}
from pipecat.services.kokoro import KokoroTTSService

tts = KokoroTTSService(
    settings=KokoroTTSService.Settings(
        voice="af_heart",
    ),
)
```

### With Language Configuration

```python theme={null}
from pipecat.services.kokoro import KokoroTTSService
from pipecat.transcriptions.language import Language

tts = KokoroTTSService(
    settings=KokoroTTSService.Settings(
        voice="af_heart",
        language=Language.ES,
    ),
)
```

### With Custom Model Paths

```python theme={null}
from pipecat.services.kokoro import KokoroTTSService

tts = KokoroTTSService(
    model_path="/path/to/kokoro-v1.0.onnx",
    voices_path="/path/to/voices-v1.0.bin",
    settings=KokoroTTSService.Settings(
        voice="af_heart",
    ),
)
```

<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

* **Fully local**: Kokoro runs entirely on the host machine using ONNX Runtime. No API keys, network access, or external services are required after the initial model download.
* **Automatic model caching**: Model files are downloaded once to `~/.cache/kokoro-onnx/` and reused on subsequent runs. You can also pre-download models and specify custom paths.
* **Audio resampling**: Kokoro's native output is automatically resampled to match the pipeline's configured sample rate.
* **Streaming output**: The service uses kokoro-onnx's async 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.