API reference

Public root symbols

SynthesisSegment is an alias of SynthesisRequest, and PyKokoroError is a compatibility alias of KokoroError. AssetProgressCallback, LongTextSplitMode, VoiceConditioning, and VoiceEnrollmentEngine are type aliases; they describe accepted Python values rather than runtime record classes.

Request API compatibility contract

pykokoro.REQUEST_API_VERSION identifies the request API contract family. Call pykokoro.request_api_contract() to inspect its stable capability declaration before constructing an engine:

import pykokoro

contract = pykokoro.request_api_contract()
assert contract.version == pykokoro.REQUEST_API_VERSION == 1
assert contract.request_type == "SynthesisRequest"
assert contract.result_type == "RenderedSegment"

The declaration is dependency-light: it does not initialize a G2P frontend, model registry, ONNX session, or audio backend. Resolving pykokoro.KokoroSynthesizer loads the class without constructing its G2P adapter; constructing the synthesizer or rendering a request is a separate runtime operation. This versioned declaration gives integrations a stable compatibility probe instead of requiring them to infer a contract from implementation details.

Each SynthesisRequest is one caller-prepared atomic text boundary. Parsing, shaping, and splitting documents remain caller-owned; the default strict token-capacity behavior raises SynthesisInputTooLongError instead of silently changing that boundary.

Synthesizer

Use it as a context manager or call close() when finished. synthesize() renders one request, synthesize_text() constructs and renders one prepared string, and synthesize_segments() yields independent results in input order. prepare() runs the frontend and returns PreparedSynthesis (request ID, text, language, voice, phonemes, token IDs, alignment tokens, and diagnostics) without running ONNX inference.

Requests, results, and source alignment

SynthesisSegment is the supported compatibility spelling for SynthesisRequest. Request language and voice are explicit. PronunciationOverride and LinguisticToken offsets are half-open character ranges into the exact text carried by that request; tokens is the canonical SynthesisRequest field.

RenderedSegment contains one request’s waveform and metadata. save_wav() writes mono float32 WAV audio. play() uses the optional playback dependency. Results from a batch remain separate: this API does not join independent requests or insert silence between them.

Configuration

Voice enrollment and packs

KokoroSynthesizer.enroll_voice() defaults to engine="inno". It accepts reference audio without a transcript and returns a portable KokoroVoicePack for ordinary static Kokoro synthesis. The versioned NPZ save/load format is pickle-free. Inno enrollment requires a runtime-supported inno-v0.2 model capability. VoiceEnrollerSpec discovery metadata reports its requirements and output format without loading model weights.

AkinVox remains a separate, explicit path. Use engine="akinvox" and provide the exact transcript to return a model-bound ReferenceVoice. The voice pack and reference state are not interchangeable. See the voice enrollment guide for engine requirements, audio limits, persistence, calibration limitations, privacy, and examples.

LongTextSplitMode is "none" | "sentence". The default "none" path raises SynthesisInputTooLongError for an oversized request. "sentence" lazily loads PhraseSplit only when a request exceeds capacity, then returns one result for the original request. long_text_use_spacy=False selects PhraseSplit’s simple mode without spaCy.

GenerationConfig controls Kokoro acoustic speed, the default language for synthesize_text(), inference random seed, and the per-request short-sentence override. Short-sentence handling is disabled unless explicitly enabled with ShortSentenceConfig or GenerationConfig.enable_short_sentence.

Voice blending and calibration

A VoiceBlend combines supported voice IDs for one request/model profile. Voice-level calibration is an engine-local option; it is not whole-program loudness mastering.

Model and lexicon discovery

Discovery reports metadata and runtime capability, including VoiceEnrollerSpec, without loading synthesis weights or creating an ONNX session. Offline discovery uses available local metadata; it does not install model or lexicon assets. Use the inventory to select an available model/language/voice rather than inferring compatibility from a voice name.

Asset progress

AssetProgressCallback is a callable receiving AssetProgressEvent values. Pass a callback or ConsoleAssetProgress() with SynthesisConfig.asset_progress. Progress notifications cover managed model assets, not lexicon data provisioning.

Synthesis identity

The identity captures output-affecting synthesis settings and exposes a stable cache key. Building identity metadata does not run inference.

Exceptions

Catch the narrow exception that an application can act on; avoid treating every failure as a recoverable input error. PyKokoroError is the retained alias for KokoroError.

Version

pykokoro.__version__ is the package’s version string and pykokoro.__version_tuple__ is its parsed tuple. The package version is generated by setuptools-scm.

Related guides

• Quickstart

• Configuration and request behavior

• Prepared text, routing, and result metadata

• Languages and model profiles

• Installation and asset progress