PyKokoro

PyKokoro is a Kokoro speech-synthesis engine. It accepts prepared speech text and explicit pronunciation context, uses KokoroG2P for model-compatible phonemization, and uses OnnxVoice for Kokoro ONNX inference. Document parsing, SSMD interpretation, speech planning, timeline composition, embedded audio, and final-output mastering are intentionally outside PyKokoro.

Quick start

Install one ONNX Runtime provider, then synthesize a prepared string:

pip install "pykokoro[cpu]"

from pykokoro import GenerationConfig, KokoroSynthesizer, SynthesisConfig

config = SynthesisConfig(
    voice="af_sarah",
    generation=GenerationConfig(lang="en-us"),
)
with KokoroSynthesizer(config) as synthesizer:
    rendered = synthesizer.synthesize_text(
        "Hello, world.",
        language="en-us",
        voice="af_sarah",
    )

rendered.save_wav("hello.wav")

The WAV writer stores mono float32 audio. Model assets are provisioned lazily on first use.

Prepared requests and pronunciation context

For orchestration, create a SynthesisSegment with an opaque request ID, prepared text, an explicit pronunciation language, and a supported static or enrolled reference voice. Optional source-aligned pronunciation instructions and linguistic tokens use offsets into that exact text:

from pykokoro import (
    LinguisticToken,
    PronunciationOverride,
    SynthesisSegment,
)

request = SynthesisSegment(
    id="line-001",
    text="Hello Welt.",
    language="en-us",
    voice="af_sarah",
    pronunciation_overrides=(PronunciationOverride(6, 10, language="de"),),
    tokens=(LinguisticToken(0, 5, text="Hello", pos="INTJ"),),
)

Use synthesize() for one request or synthesize_segments() for an ordered iterable of independent requests. Each request yields its own RenderedSegment; PyKokoro does not join batch results or insert cross-request silence. The caller can save, play, or pass each waveform to a separate composition system.

Longer requests and optional discovery

long_text_split="none" is the default and raises SynthesisInputTooLongError if a prepared request exceeds model capacity. Opt into lazy sentence splitting for oversized requests; the engine still returns one result for the original request:

from pykokoro import GenerationConfig, KokoroSynthesizer, SynthesisConfig


long_text = "A prepared request with several sentences. " * 100
config = SynthesisConfig(
    voice="af_sarah",
    generation=GenerationConfig(lang="en-us"),
    long_text_split="sentence",
    long_text_use_spacy=False,
)
with KokoroSynthesizer(config) as synthesizer:
    rendered = synthesizer.synthesize_text(long_text, language="en-us")

To inspect installed/runtime model profiles without loading weights, use discover_models(offline=True). Profile data describes language/voice combinations; G2P language availability alone does not guarantee that every acoustic profile supports it.

Input text is prepared speech, not a document markup language. PyKokoro does not parse SSMD, YAML front matter, or say-as/voice/pause directives. GenerationConfig.speed is a Kokoro acoustic inference control, not editorial timeline-rate policy.

Engine behavior

The engine owns Kokoro-specific G2P integration, request-local voice/model/style selection, voice blends, token-capacity validation, explicitly configured short-sentence handling, inference, timing reconstruction, waveform validation, tracing, and optional voice-level calibration. discover_models() and discover_lexicons() inspect supported runtime capabilities and lexicon metadata without loading a synthesis session.

Each call returns one request-local RenderedSegment. By default, long_text_split="none" keeps the exact-text path and raises SynthesisInputTooLongError when the prepared text exceeds the model token limit. Set SynthesisConfig.long_text_split="sentence" to enable internal model-safe splitting only when the request is oversized. PhraseSplit is imported lazily for that path; it splits on sentence boundaries, then clauses or safe word boundaries as needed, and joins the audio chunks into one result while preserving the original request text and source-aligned context. long_text_use_spacy=False is the default, so spaCy is not required. Separate caller requests remain separate results, and cross-request composition stays with the caller. See long-text configuration for details.

Structured error diagnostics

Catch typed exceptions for normal control flow. For unexpected backend or enrollment failures, pykokoro.error_diagnostic(exc) provides a JSON-safe cause chain with a stable stage and native error reason:

import json
import pykokoro

with pykokoro.KokoroSynthesizer() as synthesizer:
    try:
        rendered = synthesizer.synthesize_text("Hello.", language="en-us")
    except pykokoro.PyKokoroError as exc:
        print(json.dumps(pykokoro.error_diagnostic(exc), indent=2))

Diagnostics omit raw request text, reference transcripts, audio arrays, and token arrays. See the troubleshooting guide.

Installation

Python 3.10 or newer is required. Choose one ONNX Runtime provider extra per environment:

pip install "pykokoro[cpu]"        # CPU
pip install "pykokoro[gpu]"        # NVIDIA CUDA
pip install "pykokoro[openvino]"   # OpenVINO
pip install "pykokoro[directml]"  # DirectML
pip install "pykokoro[coreml]"     # Apple CoreML

For optional direct playback, install pykokoro[cpu,playback]. PyKokoro writes WAV files through soundfile; RenderedSegment.play() uses the optional sounddevice dependency. Install espeak-ng when selecting an eSpeak frontend or fallback.

Feature guides

Basic usage, request reuse, cache configuration, and typed errors
[Pronunciation tokens, language routing, VoiceBlend, calibration, and result metadata] (docs/advanced_features.md)
Voice enrollment with Inno packs and AkinVox cloning
Language codes and model-profile discovery
Frontend, lexicon, asset-progress, and provider setup
Local/custom model artifacts and migration from pre-v0.10 and migration note
Short-sentence policy

Documentation and examples

Run the request-centric examples from the repository root with python examples/run_all.py.

Development

pip install -e ".[dev,cpu]"
python -m pytest

See AGENTS.md for the repository's test, lint, and type-check commands.

Metadata

Release files for pykokoro 0.10.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pykokoro 0.10.6
File	Size	Uploaded	Provenance
pykokoro-0.10.6.tar.gz	2.0 MB	Oct 23, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pykokoro 0.10.6
File	Interpreter	ABI	Platform	Reset
pykokoro-0.10.6-py3-none-any.whl 145.4 kB Oct 23, 2026 Without provenance	Python 3	none	any	Details

Total release size: 2.1 MB

Release files / pykokoro-0.10.6.tar.gz

Download URL	pykokoro-0.10.6.tar.gz
Size	2.0 MB
Tags	Source
SHA-256 checksum How to use checksums	`4c749e67824d41337b2c5c2fa9e96ab139a9937e4fa4d43968531d66d138f006`
BLAKE2b-256 checksum How to use checksums	`36453551d04fc994bed10adc148f3f82075af8d1d88359df842c03fd2a6ba548`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Release files / pykokoro-0.10.6-py3-none-any.whl

Download URL	pykokoro-0.10.6-py3-none-any.whl
Size	145.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`bd9a78fb3471f4a6d1014b606858294dce77704ec6823a0bcc726ec2e5dce824`
BLAKE2b-256 checksum How to use checksums	`1d82eb9d5b7ce15752571bff5162f9639bc55331fc2d583b7337138256040421`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.14`

Security for pykokoro 0.10.6

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.