> ## Documentation Index
> Fetch the complete documentation index at: https://daily-main.mintlify.site/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/pipecat/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/pipecat/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/pipecat/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/pipecat/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 codes are mapped to espeak-ng voice names internally; Mandarin uses `cmn` and French variants use region-specific codes (`fr-fr`, `fr-be`, etc.) rather than ISO codes.

| Language             | Code             |
| -------------------- | ---------------- |
| English (US)         | `Language.EN_US` |
| English (UK)         | `Language.EN_GB` |
| English (generic)    | `Language.EN`    |
| Spanish              | `Language.ES`    |
| French (France)      | `Language.FR`    |
| French (Belgium)     | `Language.FR_BE` |
| French (Canada)      | `Language.FR_CA` |
| French (Switzerland) | `Language.FR_CH` |
| Hindi                | `Language.HI`    |
| Italian              | `Language.IT`    |
| Japanese             | `Language.JA`    |
| Portuguese           | `Language.PT`    |
| Portuguese (Brazil)  | `Language.PT_BR` |
| Chinese (Mandarin)   | `Language.ZH`    |
| Chinese (Simplified) | `Language.ZH_CN` |
| Chinese (Hong Kong)  | `Language.ZH_HK` |
| Chinese (Taiwan)     | `Language.ZH_TW` |
| Mandarin             | `Language.CMN`   |
| Cantonese            | `Language.YUE`   |

## 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/pipecat/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.
* **Language mapping**: Kokoro phonemizes through espeak-ng, so languages use espeak-ng voice names (e.g., `cmn` for Mandarin, `fr-fr` for French) rather than ISO codes. An unsupported language name fails at synthesis time.