Kokoro Text-to-Speech

Overview

KokoroTTSService provides local, offline text-to-speech synthesis using the 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.

Kokoro TTS API Reference

Pipecat’s API methods for Kokoro TTS integration

Example Implementation

Complete example with interruption handling

kokoro-onnx Repository

Official kokoro-onnx project and documentation

Settings Update Example

Example showing runtime settings updates

Installation

To use Kokoro TTS, install the required dependencies:

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. The first time the service is constructed, it downloads two model files to ~/.cache/pipecat/kokoro-onnx/, so the constructor blocks until they arrive:

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.

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

Configuration

KokoroTTSService

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.

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.

str

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=KokoroTTSService.Settings(voice=...) instead.

InputParams

default:"None"

deprecated

Deprecated since 0.0.105, removed in 2.0.0. Use settings=KokoroTTSService.Settings(...) instead.

KokoroTTSService.Settings

default:"None"

Runtime-configurable settings. See Settings below.

Settings

Runtime-configurable settings passed via the settings constructor argument using KokoroTTSService.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 from base settings.)
`voice`	`str`	`None`	Voice identifier (e.g. `"af_heart"`). Required: the constructor raises `ValueError` when it isn’t set or isn’t in the voices file.
`language`	`Language \| str`	`Language.EN`	Language for synthesis. See supported languages.
`speed`	`float`	`1.0`	Speech rate multiplier (0.5-2.0).

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

from pipecat.services.kokoro.tts import KokoroTTSService

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

With Language Configuration

from pipecat.services.kokoro.tts import KokoroTTSService
from pipecat.transcriptions.language import Language

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

With Custom Model Paths

from pipecat.services.kokoro.tts 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",
    ),
)

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.

Get Started

Pipecat Server

Client SDKs

Pipecat Flows

Pipecat Cloud

CLI

Pipecat Context Hub

Kokoro Text-to-Speech

Overview

Kokoro TTS API Reference

Example Implementation

kokoro-onnx Repository

Settings Update Example

Installation

Prerequisites

Local Setup

Configuration

KokoroTTSService

Settings

Supported Languages

Usage

Basic Setup

With Language Configuration

With Custom Model Paths

Notes

​Overview

Kokoro TTS API Reference

Example Implementation

kokoro-onnx Repository

Settings Update Example

​Installation

​Prerequisites

​Local Setup

​Configuration

​KokoroTTSService

​Settings

​Supported Languages

​Usage

​Basic Setup

​With Language Configuration

​With Custom Model Paths

​Notes

Overview

Installation

Prerequisites

Local Setup

Configuration

KokoroTTSService

Settings

Supported Languages

Usage

Basic Setup

With Language Configuration

With Custom Model Paths

Notes