Backends API

kokorog2p supports multiple phonemization backends.

espeak-ng Backend

class kokorog2p.espeak_g2p.EspeakOnlyG2P(language: str = 'en-us', use_espeak_fallback: bool = True, use_goruut_fallback: bool = False, strict: bool = True, version: str = '1.0', use_cli: bool = False, **kwargs)[source]

Bases: G2PBase

G2P implementation using only espeak-ng.

This is used for languages that don’t have dedicated dictionaries or custom G2P logic. It provides basic phonemization via espeak.

Example:

>>> g2p = EspeakOnlyG2P("fr-fr")
>>> tokens = g2p("Bonjour le monde")

VOICE_MAP = {'ar': 'ar', 'ar-sa': 'ar', 'bn': 'bn', 'bn-in': 'bn', 'cs': 'cs', 'cs-cz': 'cs', 'da': 'da', 'da-dk': 'da', 'de': 'de', 'de-de': 'de', 'el': 'el', 'el-gr': 'el', 'es': 'es', 'es-es': 'es', 'fa': 'fa', 'fa-ir': 'fa', 'fi': 'fi', 'fi-fi': 'fi', 'fr': 'fr-fr', 'fr-fr': 'fr-fr', 'he': 'he', 'he-il': 'he', 'hi': 'hi', 'hi-in': 'hi', 'hu': 'hu', 'hu-hu': 'hu', 'id': 'id', 'id-id': 'id', 'it': 'it', 'it-it': 'it', 'ms': 'ms', 'ms-my': 'ms', 'nb': 'nb', 'nb-no': 'nb', 'nl': 'nl', 'nl-nl': 'nl', 'no': 'nb', 'pl': 'pl', 'pl-pl': 'pl', 'pt': 'pt', 'pt-br': 'pt-br', 'pt-pt': 'pt', 'ro': 'ro', 'ro-ro': 'ro', 'ru': 'ru', 'ru-ru': 'ru', 'sv': 'sv', 'sv-se': 'sv', 'ta': 'ta', 'ta-in': 'ta', 'th': 'th', 'th-th': 'th', 'tr': 'tr', 'tr-tr': 'tr', 'uk': 'uk', 'uk-ua': 'uk', 'vi': 'vi', 'vi-vn': 'vi'}

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

Initialize the espeak-only G2P.

Args:

language: Language code (e.g., ‘fr-fr’, ‘de-de’). use_espeak_fallback: Ignored (always uses espeak). strict: If True (default), raise exceptions on errors. If False,

log warnings and return empty results for backward compatibility.

version: Model version (default: “1.0”). **kwargs: Additional arguments (ignored).

property espeak_backend

Lazy initialization of espeak backend.

Raises:: RuntimeError: If espeak backend initialization or validation fails.

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

Convert text to tokens with phonemes.

Args:: text: Input text to convert.
Returns:: List of GToken objects with phonemes.

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

Look up a word using espeak.

Args:: word: The word to look up. tag: Optional POS tag (ignored for espeak).
Returns:: Phoneme string from espeak, or None if strict=False and error occurs.
Raises:: RuntimeError: If espeak backend fails and strict=True.

phonemize(text: str) → str[source]

Convert text to phonemes using espeak.

Args:: text: Input text to convert.
Returns:: Phoneme string, or empty string if strict=False and error occurs.
Raises:: RuntimeError: If espeak backend fails and strict=True.

close() → None[source]: Release resources owned by this G2P instance.

goruut Backend

Examples

espeak Backend

from kokorog2p.backends.espeak import EspeakBackend

backend = EspeakBackend(language="en-us")
phonemes = backend.phonemize("hello")
print(phonemes)

EspeakBackend delegates discovery and native/CLI lifecycle to espeakng-runtime. Default mode prefers native and falls back to CLI; use_cli=True forces CLI. Inspect the selected implementation after first use with backend.runtime_info, then call backend.close() when the instance is no longer needed.

The neutral runtime configuration variables are ESPEAKNG_RUNTIME_EXECUTABLE, ESPEAKNG_RUNTIME_LIBRARY, and ESPEAKNG_RUNTIME_DATA. The legacy KOKOROG2P_ESPEAK_EXECUTABLE, KOKOROG2P_ESPEAK_LIBRARY, and KOKOROG2P_ESPEAK_DATA variables remain compatibility aliases. This direct backend is distinct from the Lexphon eSpeak fallback selected with use_espeak_fallback=True.

Using espeak-only G2P

from kokorog2p.espeak_g2p import EspeakOnlyG2P

# Strict mode (default) - raises errors if espeak fails
g2p = EspeakOnlyG2P(language="es-es", strict=True)
tokens = g2p("Hola mundo")

for token in tokens:
    print(f"{token.text} -> {token.phonemes}")

# Lenient mode - returns empty on errors (backward compatible)
g2p_lenient = EspeakOnlyG2P(language="es-es", strict=False)
tokens = g2p_lenient("Hola mundo")

Using goruut Backend

from kokorog2p.goruut_g2p import GoruutOnlyG2P

# Strict mode (default)
g2p = GoruutOnlyG2P(language="en-us", strict=True)
tokens = g2p("Hello world")

for token in tokens:
    print(f"{token.text} -> {token.phonemes}")

# Lenient mode
g2p_lenient = GoruutOnlyG2P(language="en-us", strict=False)
tokens = g2p_lenient("Hello world")