Core API

Routing and target-model options

phonemize and phonemize_prepared accept the same routing and target-model controls:

• overlap="split" applies partial language spans to exact source-aligned fragments. The default "snap" behavior remains compatible.

• language_routing={"mode": "auto", "languages": ["de", "en"]} enables optional pronunciation-language routing with a hard candidate allowlist. Any supported factory language, including pt-pt, may be listed; the allowlist is never expanded implicitly.

• LanguageRoutingConfig is also accepted.

• g2p_resolver(language) supplies and caches a configured frontend per canonical language for one call. Without a custom resolver, foreign frontends use their own defaults and do not inherit the default frontend’s lexicons, version, or language-specific kwargs.

• target_model="1.0" makes the caller-supplied Kokoro vocabulary authoritative for routed phonemes and token IDs.

The document/default language is always explicit. Automatic routing does not detect the document language. It inspects positive membership in the effective selected lexical resources through G2PBase.lexicon_evidence(). Externally provisioned G2Lex evidence is available for English US/GB and French. Provisioned Lexphon evidence is available for German, Portuguese BR/PT, Russian, Thai, Vietnamese, Japanese, Korean, and Swedish when NST is selected. Spanish, Italian, Czech, Hebrew, Arabic, Chinese, Kazakh, and Hindi remain pronounceable but have no selected evidence provider in this release.

Generic lookup, proper-noun spelling, eSpeak, Goruut, pypinyin, Phonikud, g2pK, pyopenjtalk, and rule fallback are not evidence. Lexicon collisions and ambiguity stay in the default language. Candidate failures are isolated and warned. Explicit ph, phonemes, lang, and language spans take precedence.

Language routing changes G2P frontend selection only. KokoroG2P does not select an acoustic model or ONNX model. Routing decisions are available as structured LanguageRoute objects in PhonemizeResult.language_routes, with selected lexicon provenance. Do not pass arbitrary written text when number, date, unit, currency, or abbreviation expansion is expected.

kokorog2p.tokenize(text: str, language: str, keep_punct: bool = True) → list[TokenSpan][source]

Convert text to a list of tokens with phonemes.

Args:

text: Input text to convert. language: Language code (e.g., ‘en-us’, ‘en-gb’). keep_punct: Whether to include punctuation tokens.

Returns:

List of TokenSpan objects with char offsets.

Example:

>>> tokens = tokenize("Hello world!", language="en-us")
>>> for t in tokens:
...     print(f"{t.text} [{t.char_start}:{t.char_end}]")
Hello [0:5]
world [6:11]
! [11:12]

kokorog2p.get_g2p(language: str, use_espeak_fallback: bool | None = None, use_goruut_fallback: bool = False, use_cli: bool = False, use_spacy: bool | None = None, backend: Literal['kokorog2p', 'espeak', 'goruut'] = 'kokorog2p', lexicons: str | Sequence[str] | None = None, version: str = '1.0', phoneme_quotes: str = 'curly', strict: bool = True, spacy_model: str | None = None, spacy_model_size: SpacyModelSize | None = None, **kwargs: Any) → G2PBase[source]

Get a G2P instance for the specified language.

This factory function returns an appropriate G2P instance based on the

Args:

language: Language code (e.g., ‘en-us’, ‘en-gb’, ‘zh’, ‘ja’, ‘fr’, etc.). use_espeak_fallback: Whether to use espeak for out-of-vocabulary words

when using the dictionary-based “kokorog2p” backend. Ignored when backend is set to “espeak” (espeak is the primary backend).

use_goruut_fallback: Whether to use goruut for out-of-vocabulary words

when using the dictionary-based “kokorog2p” backend. Ignored when backend is set to “goruut” (goruut is the primary backend).

use_spacy: Whether to use spaCy for tokenization and POS tagging. If

None, the highest-quality installed and loadable local model is attempted for languages with spaCy defaults and the native path is used when no model is available. True requires a loadable model; False forces the native path. No model is downloaded automatically.

spacy_model: Concrete spaCy model package name, or "auto" for the

highest installed loadable tier. Concrete names are strict.

spacy_model_size: Exact model tier ("trf", "lg", "md", or

"sm") to select when spacy_model is unset.

use_cli: If True, force use of CLI espeak phonemizer instead of

library bindings. Only applies when backend=”espeak”.

backend: Phonemization backend to use: “kokorog2p”, “espeak”, “goruut”.

The goruut backend requires pygoruut to be installed. Only applies to languages with dictionaries (English, French, German).

lexicons: A named lexicon or ordered sequence of named lexicons for the

language. When omitted, the language default stack is used. In an explicit sequence, the first lexicon wins collisions. Use available_lexicons(language) to inspect registered names.

version: Model version to use. Default: “1.0” (base model).

• “1.0”: Base model

• “1.1”: Chinese/English model

Different languages may have different behavior: - Chinese: “1.0” = IPA output, “1.1” = Zhuyin output

phoneme_quotes: Quote character style in phoneme output. Options:

• “curly”: Use curly quotes (”, “) - default, backward compatible

• “ascii”: Use ASCII double quotes (“)

• “none”: Remove quote characters from phoneme output

Only applies to English currently.

strict: If True (default), raise exceptions when backend initialization

or phonemization fails. If False, log errors and return empty results for backward compatibility with older versions that silently failed. Recommended: True for production use to catch configuration issues.

**kwargs: Additional arguments passed to the G2P constructor.

Returns:

A G2PBase instance for the specified language.

Raises:

ValueError: If the language is not supported and no fallback is available,

or if version is not “1.0” or “1.1”.

ImportError: If backend=”goruut” but pygoruut is not installed.

Example:

>>> g2p = get_g2p("en-us")
>>> tokens = g2p("Hello world!")
>>> # Disable silver for better performance
>>> # Fallback-only mode without a dictionary
>>> # Chinese
>>> g2p_zh = get_g2p("zh")
>>> # Japanese
>>> g2p_ja = get_g2p("ja")
>>> # French (uses espeak fallback)
>>> g2p_fr = get_g2p("fr")
>>> # Using goruut backend
>>> g2p_goruut = get_g2p("en-us", backend="goruut")

kokorog2p.clear_cache(*, deep: bool = False) → None[source]

Clear the G2P instance cache.

Args:

deep: Also clear language dictionary resource caches. This can be

useful when a long-running process must release parsed lexicons.

G2PBase

class kokorog2p.G2PBase(language: str = 'en-us', use_espeak_fallback: bool = True, use_goruut_fallback: bool = False, use_cli: bool = False, strict: bool = True)[source]

Bases: ABC

Abstract base class for grapheme-to-phoneme converters.

Subclasses must implement the __call__ method to convert text to phonemes.

__init__(language: str = 'en-us', use_espeak_fallback: bool = True, use_goruut_fallback: bool = False, use_cli: bool = False, strict: bool = True) → None[source]

Initialize the G2P converter.

Args:

language: Language code (e.g., ‘en-us’, ‘en-gb’). use_espeak_fallback: Whether to use espeak for OOV words. use_goruut_fallback: Whether to use goruut for OOV words. use_cli: If True, use the CLI only for direct backend implementations. strict: If True, raise exceptions on errors. If False, log warnings

and return empty results (backward compatible mode).

property is_british: bool

Check if this is British English.

abstractmethod __call__(text: str) → list[GToken][source]

Convert text to a list of tokens with phonemes.

Args:

text: Input text to convert.

Returns:

List of GToken objects with phonemes assigned.

phonemize(text: str) → str[source]

Convert text to a phoneme string.

This is a convenience method that calls __call__ and joins the results.

Args:

text: Input text to convert.

Returns:

Phoneme string with word boundaries.

word_to_phonemes(word: str, tag: str | None = None) → str | None[source]

Convert a single word to phonemes.

Args:

word: The word to convert. tag: Optional POS tag for disambiguation.

Returns:

Phoneme string or None if conversion failed.

abstractmethod lookup(word: str, tag: str | None = None) → str | None[source]

Look up a word in the dictionary.

Args:

word: The word to look up. tag: Optional POS tag for disambiguation.

Returns:

Phoneme string or None if not found.

lexicon_evidence(word: str, tag: str | None = None) → LexiconEvidence | None[source]

Return positive membership evidence from selected lexical resources.

has_lexicon_evidence() → bool[source]

Return whether this frontend can query a selected evidence resource.

close() → None[source]

Release resources owned by this G2P instance.

__repr__() → str[source]

Return a string representation.

GToken

class kokorog2p.GToken(text: str, tag: str = '', whitespace: str = ' ', phonemes: str | None = None, start_ts: float | None = None, end_ts: float | None = None, rating: str | None = None, _: dict[str, ~typing.Any]=<factory>)[source]

Bases: object

A token representing a word or text unit with optional phoneme information.

Attributes:

text: The original text of the token. tag: Part-of-speech tag (e.g., ‘NN’, ‘VB’, ‘JJ’). whitespace: Trailing whitespace after this token. phonemes: The phonemic transcription of the token. start_ts: Start timestamp for audio alignment. end_ts: End timestamp for audio alignment. rating: Quality rating of the phoneme transcription. _: Extension dictionary for custom attributes.

text

The original text of this token.

phonemes

The IPA phoneme string for this token.

tag

Part-of-speech tag (if available).

whitespace

Whitespace following this token.

text: str

tag: str = ''

whitespace: str = ' '

phonemes: str | None = None

start_ts: float | None = None

end_ts: float | None = None

rating: str | None = None

property has_phonemes: bool

Check if this token has phonemes assigned.

property is_punctuation: bool

Check if this token is punctuation.

property is_word: bool

Check if this token is a word (not punctuation or whitespace).

get(key: str, default: Any = None) → Any[source]

Get a custom attribute from the extension dict.

set(key: str, value: Any) → None[source]

Set a custom attribute in the extension dict.

copy() → GToken[source]

Create a shallow copy of this token.

__repr__() → str[source]

Return a string representation of the token.

Vocabulary

kokorog2p.get_vocab(british: bool = False) → frozenset[str][source]

Get the phoneme vocabulary for a dialect.

Args:

british: Whether to get British or US vocabulary.

Returns:

Frozen set of valid phonemes.

kokorog2p.validate_phonemes(phonemes: str, british: bool = False) → bool[source]

Check if all phonemes in a string are valid Kokoro phonemes.

Args:

phonemes: Phoneme string to validate. british: Whether to validate against British or US vocabulary.

Returns:

True if all phonemes are valid.

kokorog2p.US_VOCAB

Build an immutable unordered collection of unique elements.

kokorog2p.GB_VOCAB

Build an immutable unordered collection of unique elements.

kokorog2p.VOWELS

Build an immutable unordered collection of unique elements.

kokorog2p.CONSONANTS

Build an immutable unordered collection of unique elements.

Conversion

kokorog2p.from_espeak(phonemes: str, british: bool = False) → str[source]

Convert espeak IPA output to Kokoro phonemes.

Args:

phonemes: The espeak phoneme string (with tie character ^ or ͡). british: Whether to use British English mappings.

Returns:

Kokoro-compatible phoneme string.

Example:

>>> from_espeak("mˈɜːt͡ʃənt͡ʃˌɪp", british=False)
'mˈɜɹʧəntʃˌɪp'

kokorog2p.from_goruut(phonemes: str, british: bool = False) → str[source]

Convert goruut/pygoruut IPA output to Kokoro phonemes.

Goruut outputs standard IPA without tie characters for diphthongs and affricates, which requires different handling than espeak.

Args:

phonemes: The goruut phoneme string (standard IPA). british: Whether to use British English mappings.

Returns:

Kokoro-compatible phoneme string.

Example:

>>> from_goruut("həlˈoʊ wˈɜɹld", british=False)
'həlˈO wˈɜɹld'
>>> from_goruut("sˈeɪ", british=False)
'sˈA'

kokorog2p.to_espeak(phonemes: str) → str[source]

Convert Kokoro phonemes to standard IPA (espeak-compatible).

Args:

phonemes: Kokoro phoneme string.

Returns:

Standard IPA phoneme string.

Example:

>>> to_espeak("hˈA")
'hˈeɪ'

Encoding/Decoding

kokorog2p.encode(text: str, add_spaces: bool = True, model: str = '1.0') → list[int][source]

Convert a phoneme string to token indices.

Args:

text: Phoneme string to encode. add_spaces: Whether to include space tokens (default True). model: Model variant to encode for (default: “1.0”).

Returns:

List of token indices.

Example:

>>> encode("hˈɛlO")
[50, 156, 86, 54, 31]

kokorog2p.decode(indices: list[int], skip_special: bool = True, model: str = '1.0') → str[source]

Convert token indices back to a phoneme string.

Args:

indices: List of token indices. skip_special: Whether to skip padding/unknown tokens. model: Model variant to decode from (default: “1.0”).

Returns:

Phoneme string.

Example:

>>> decode([50, 156, 86, 54, 31])
'hˈɛlO'

kokorog2p.phonemes_to_ids(phonemes: str, model: str = '1.0') → list[int][source]

Convert phoneme string to model input IDs.

This is the main function used to prepare text for the Kokoro model.

Args:

phonemes: Phoneme string from G2P conversion. model: Model variant to encode for (default: “1.0”).

Returns:

List of token IDs ready for model input.

Example:

>>> phonemes_to_ids("hˈɛlO wˈɜɹld!")
[50, 156, 86, 54, 31, 16, 65, 156, 87, 123, 54, 46, 5]

kokorog2p.ids_to_phonemes(ids: list[int], model: str = '1.0') → str[source]

Convert model output IDs back to phoneme string.

Args:

ids: List of token IDs from model. model: Model variant to decode from (default: “1.0”).

Returns:

Phoneme string.

Example:

>>> ids_to_phonemes([50, 156, 86, 54, 31])
'hˈɛlO'

Validation

kokorog2p.validate_for_kokoro(text: str, model: str = '1.0') → tuple[bool, list[str]][source]

Validate that all characters in text are in Kokoro vocabulary.

Args:

text: Phoneme string to validate. model: Model variant to validate against:

• “1.0”: Base multilingual model (default)

• “1.1”: Chinese-specific model with Zhuyin

Returns:

Tuple of (is_valid, list_of_invalid_chars).

Example:

>>> validate_for_kokoro("hˈɛlO")
(True, [])
>>> validate_for_kokoro("hˈɛlO§")
(False, ['§'])
>>> validate_for_kokoro("ㄋㄧ2ㄏㄠ3", model="1.1")
(True, [])

kokorog2p.filter_for_kokoro(text: str, replacement: str = '', model: str = '1.0') → str[source]

Remove characters not in Kokoro vocabulary.

Args:

text: Phoneme string to filter. replacement: String to replace invalid characters with. model: Model variant to filter for (same options as validate_for_kokoro).

Returns:

Filtered phoneme string.

Example:

>>> filter_for_kokoro("hˈɛlO§")
'hˈɛlO'

Configuration

kokorog2p.get_kokoro_vocab(model: str = '1.0') → dict[str, int]

Get the Kokoro vocabulary mapping (token -> index).

Args:

model: Model variant to load vocab for:

• “1.0”: Base multilingual Kokoro model (default)

• “1.1”: Chinese-specific Kokoro v1.1 model with Zhuyin

Returns:

Dictionary mapping tokens to their indices.

kokorog2p.get_kokoro_config() → dict

Get the full Kokoro model configuration.

Returns:

Dictionary containing the full model config.

kokorog2p.N_TOKENS

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4

kokorog2p.PAD_IDX

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating-point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer iteral. >>> int(‘0b100’, base=0) 4