API Reference

KokoroPipeline

Basic Example:

from pykokoro import KokoroPipeline, PipelineConfig

pipe = KokoroPipeline(PipelineConfig(voice="af_bella"))
result = pipe.run("Hello, world!")
print(result.sample_rate)

Paragraph unit streaming

KokoroPipeline.prepare_units(text, unit="paragraph") parses, phonemizes, and preprocesses the complete document once, then exposes deterministic paragraph descriptors before any audio is generated. Rendered results own one final unit waveform and should be released after consumption:

with pipe.prepare_units(script) as prepared:
    for result in prepared.render(skip_indices=completed_indices):
        try:
            consume(result.audio, result.sample_rate)
        finally:
            result.release_audio()

PipelineConfig

GenerationConfig

class pykokoro.GenerationConfig(speed: float = 1.0, lang: str = 'en-us', is_phonemes: bool = False, pause_mode: Literal['tts', 'manual', 'auto'] = 'tts', pause_clause: float = 0.3, pause_sentence: float = 0.6, pause_paragraph: float = 1.0, pause_variance: float = 0.05, random_seed: int | None = None, enable_short_sentence: bool | None = None)[source]

Bases: object

Configuration for audio generation in the KokoroPipeline.

Groups all generation-time parameters for easier reuse and documentation. Instances are immutable (frozen) to prevent accidental modification.

This config groups generation parameters into a reusable configuration object for PipelineConfig. You can create a config once and reuse it across multiple runs, with the ability to override individual parameters using kwargs.

Priority order when using both config and kwargs:

1. kwargs (highest priority - explicit per-call overrides)

2. config (medium priority - structured configuration)

3. defaults (lowest priority - fallback values)

Attributes:

speed: Speech speed multiplier. 1.0 = normal speed, 0.5 = half speed,

2.0 = double speed. Must be > 0.0. Default: 1.0

lang: Default language code for text-to-phoneme conversion.

Examples: ‘en-us’, ‘en-gb’, ‘es’, ‘fr’, ‘de’, ‘it’, ‘pt’, ‘ja’, ‘ko’, ‘zh’, ‘hi’. Can be overridden per-segment with SSMD [text]{lang=”fr”} syntax. Default: “en-us”

is_phonemes: If True, treat input text as IPA phonemes instead of

regular text, bypassing text-to-phoneme conversion. Default: False

pause_mode: Pause handling strategy:

• “tts” (default): TTS generates pauses naturally at sentence boundaries. SSMD pauses are preserved. Best for natural speech.

• “manual”: PyKokoro controls pauses with precision. Silence is trimmed from segment boundaries and SSMD pauses are preserved. Best for precise timing control.

• “auto”: PyKokoro automatically inserts pauses at sentence and paragraph boundaries, and adds clause pauses when long sentences are split. Silence is trimmed from segment boundaries.

Default: “tts”

pause_clause: Duration in seconds for SSMD …c (comma) breaks and

automatic clause boundary pauses when pause_mode=”manual” or “auto”. Must be >= 0.0. Default: 0.3

pause_sentence: Duration in seconds for SSMD …s (sentence) breaks and

automatic sentence boundary pauses when pause_mode=”manual” or “auto”. Must be >= 0.0. Default: 0.6

pause_paragraph: Duration in seconds for SSMD …p (paragraph) breaks and

automatic paragraph boundary pauses when pause_mode=”manual” or “auto”. Must be >= 0.0. Default: 1.0

pause_variance: Standard deviation in seconds for Gaussian variance added

to automatic pauses. Only applies when pause_mode=”manual” or “auto”. Default 0.05 (±100ms at 95% confidence). Set to 0.0 to disable variance. Must be >= 0.0. Default: 0.05

random_seed: Optional random seed for reproducible pause variance.

If None, pauses will vary between runs. If set to an integer, pause variance will be reproducible. Default: None

enable_short_sentence: Override short sentence handling for this run.

• None (default): Use config setting from PipelineConfig

• True: Force enable short sentence handling

• False: Force disable short sentence handling

Default: None

Example:

Basic usage with config:

>>> from pykokoro import KokoroPipeline, PipelineConfig
>>> config = GenerationConfig(speed=1.2, pause_mode="manual")
>>> pipe = KokoroPipeline(PipelineConfig(voice="af_sarah", generation=config))
>>> res = pipe.run("Hello world")

Reuse config across multiple generations:

>>> config = GenerationConfig(
...     speed=1.2,
...     pause_mode="manual",
...     pause_clause=0.25,
...     pause_sentence=0.5,
... )
>>> res1 = pipe.run("First sentence.")
>>> res2 = pipe.run("Second sentence.")

Override specific parameters using kwargs:

>>> res = pipe.run(
...     "Fast speech",
...     generation=GenerationConfig(speed=2.0, pause_mode="manual"),
... )

speed: float = 1.0

lang: str = 'en-us'

is_phonemes: bool = False

pause_mode: Literal['tts', 'manual', 'auto'] = 'tts'

pause_clause: float = 0.3

pause_sentence: float = 0.6

pause_paragraph: float = 1.0

pause_variance: float = 0.05

random_seed: int | None = None

enable_short_sentence: bool | None = None

__post_init__() → None[source]

Validate configuration parameters after initialization.

merge_with_kwargs(**kwargs: Any) → dict[str, Any][source]

Merge config with kwargs, with kwargs taking priority.

This is used internally by KokoroPipeline to merge the config object with individual parameter overrides. Only non-None kwargs will override config values.

Args:

**kwargs: Individual parameter overrides (None values are ignored)

Returns:

Dictionary with merged parameters (non-None kwargs override config)

Example:

>>> config = GenerationConfig(speed=1.5, lang="en-gb")
>>> merged = config.merge_with_kwargs(speed=2.0, lang=None)
>>> merged["speed"]
2.0
>>> merged["lang"]  # Not overridden because kwarg was None
'en-gb'

ProsodyConfig

class pykokoro.ProsodyConfig(method: Literal['phase_vocoder', 'wsola', 'esola', 'td_psola', 'psola'] = 'wsola', fallback_methods: tuple[Literal['phase_vocoder', 'wsola', 'esola', 'td_psola', 'psola'], ...] = ('wsola', 'phase_vocoder'), strict: bool = False, clip: bool = False, n_fft: int = 2048, hop_length: int | None = None, filter_width: int = 32, rolloff: float = 0.945, boundary_blend_ms: float = 5.0)[source]

Bases: object

Configuration for post-synthesis SSMD prosody processing.

psola is accepted as a user-facing alias for AudioSig’s td_psola.

method: Literal['phase_vocoder', 'wsola', 'esola', 'td_psola', 'psola'] = 'wsola'

fallback_methods: tuple[Literal['phase_vocoder', 'wsola', 'esola', 'td_psola', 'psola'], ...] = ('wsola', 'phase_vocoder')

strict: bool = False

clip: bool = False

n_fft: int = 2048

hop_length: int | None = None

filter_width: int = 32

rolloff: float = 0.945

boundary_blend_ms: float = 5.0

ProsodyConfig(method="wsola") selects the production speech-oriented default. The supported methods are wsola, experimental esola and td_psola, compatibility phase_vocoder, and the psola alias for td_psola. Strict mode prevents fallback; non-strict mode follows fallback_methods. No method guarantees formant preservation.

AudioResult

AudioResult owns references to its final waveform and any raw or processed per-segment waveforms. AudioResult.release_segment_audio() destructively and idempotently releases only segment arrays, while AudioResult.release_audio() also replaces the final waveform with an empty array of the same dtype. Metadata, markers, trace data, segments, and sample rate remain available. Callers should copy or retain result.audio separately before releasing it if they need that array afterward.

Set PipelineConfig(retain_segment_audio=False) for compact results when segment waveforms are not needed. This reduces retained memory after generation, but whole-result concatenation still occurs and peak memory remains dependent on input duration. run() retains whole-result concatenation semantics; use prepare_units() or iter_units() when peak waveform memory should remain bounded to one paragraph.

Prepared unit descriptor hashes use the pykokoro-audio-unit-v1 schema. Store the schema alongside each hash for resumable exporters. Indices are zero-based source order, hashes include audio-semantic configuration, and advancing a render iterator releases the previous result’s waveform unless the caller copied or persisted it first.

Segment

PhonemeSegment

Trace

VoiceBlend

from pykokoro import KokoroPipeline, PipelineConfig
from pykokoro.onnx_backend import VoiceBlend

blend = VoiceBlend.parse("af_bella:60,af_sarah:40")
pipe = KokoroPipeline(PipelineConfig(voice=blend))
result = pipe.run("Blended voice example")

Tokenizer

TokenizerConfig

PhonemeResult

Tokenizer Example:

from pykokoro.tokenizer import Tokenizer

tokenizer = Tokenizer()
phonemes = tokenizer.phonemize("Hello", lang="en-us")
print(phonemes)