High-level API

Reusable facade

PiperG2P exposes both plain-string and structured-result methods. Its compatibility parameters for spaCy/Goruut do not activate those integrations: unsupported non-default values raise UnsupportedCompatibilityError.

.. py:class:: PiperG2P(language: str, config: ~piperg2p.config.VoiceConfig | str | ~pathlib.Path | ~collections.abc.Mapping[str, ~typing.Any], *, lexicons: str | ~collections.abc.Sequence[str] | None = None, use_espeak_fallback: bool = True, use_cli: bool = False, espeak_mode: ~typing.Literal[‘auto’, ‘native’, ‘cli’] | None = None, strict: bool = True, missing: ~piperg2p.codec.MissingPhonemePolicy | str = MissingPhonemePolicy.WARN, lexicon_store: ~typing.Any = None, lexicon_backend: ~typing.Any = None, use_spacy: bool | None = None, spacy_model: str | None = None, spacy_model_size: str | None = None, use_goruut_fallback: bool = False) :module: piperg2p :canonical: piperg2p.api.PiperG2P

Bases: :py:class:object

Reusable voice-config-driven facade over :class:PiperFrontend.

.. py:method:: PiperG2P.init(language: str, config: ~piperg2p.config.VoiceConfig | str | ~pathlib.Path | ~collections.abc.Mapping[str, ~typing.Any], *, lexicons: str | ~collections.abc.Sequence[str] | None = None, use_espeak_fallback: bool = True, use_cli: bool = False, espeak_mode: ~typing.Literal[‘auto’, ‘native’, ‘cli’] | None = None, strict: bool = True, missing: ~piperg2p.codec.MissingPhonemePolicy | str = MissingPhonemePolicy.WARN, lexicon_store: ~typing.Any = None, lexicon_backend: ~typing.Any = None, use_spacy: bool | None = None, spacy_model: str | None = None, spacy_model_size: str | None = None, use_goruut_fallback: bool = False) -> None :module: piperg2p

.. py:property:: PiperG2P.frontend :module: piperg2p :type: ~piperg2p.frontend.PiperFrontend

.. py:method:: PiperG2P.phonemize(text: str) -> str :module: piperg2p

.. py:method:: PiperG2P.phonemize_prepared(text: str, *, overrides: ~collections.abc.Sequence[~piperg2p.types.OverrideSpan | ~collections.abc.Mapping[str, ~typing.Any] | ~collections.abc.Sequence[~typing.Any]] | None = None, annotations: ~collections.abc.Sequence[~piperg2p.types.TokenAnnotation | ~collections.abc.Mapping[str, ~typing.Any]] | None = None, overlap: ~typing.Literal[‘snap’, ‘strict’, ‘split’] = ‘snap’, strict_stress: bool = False, language_routing: ~piperg2p.types.LanguageRoutingConfig | ~collections.abc.Mapping[str, ~typing.Any] | None = None) -> ~piperg2p.types.PhonemizeResult :module: piperg2p

.. py:method:: PiperG2P.lexicon_evidence(word: str, tag: str | None = None) :module: piperg2p

.. py:method:: PiperG2P.close() -> None :module: piperg2p

get_g2p() constructs a reusable facade and uses a bounded cache when no custom lexicon backend/store is injected. Repeated calls with the same cache identity may return the same object. The context-manager protocol closes the facade; clear_cache() closes cached values.

.. py:function:: get_g2p(language: str, *, config: ~piperg2p.config.VoiceConfig | str | ~pathlib.Path | ~collections.abc.Mapping[str, ~typing.Any], lexicons: str | ~collections.abc.Sequence[str] | None = None, use_espeak_fallback: bool = True, use_cli: bool = False, espeak_mode: ~typing.Literal[‘auto’, ‘native’, ‘cli’] | None = None, strict: bool = True, missing: ~piperg2p.codec.MissingPhonemePolicy | str = MissingPhonemePolicy.WARN, lexicon_store: ~typing.Any = None, lexicon_backend: ~typing.Any = None, use_spacy: bool | None = None, spacy_model: str | None = None, spacy_model_size: str | None = None, use_goruut_fallback: bool = False) -> ~piperg2p.api.PiperG2P :module: piperg2p

One-shot phonemization and IDs

.. py:function:: phonemize_prepared(text: str, language: str, *, config: ~piperg2p.config.VoiceConfig | str | ~pathlib.Path | ~collections.abc.Mapping[str, ~typing.Any] | None = None, overrides: ~collections.abc.Sequence[~piperg2p.types.OverrideSpan | ~collections.abc.Mapping[str, ~typing.Any] | ~collections.abc.Sequence[~typing.Any]] | None = None, annotations: ~collections.abc.Sequence[~piperg2p.types.TokenAnnotation | ~collections.abc.Mapping[str, ~typing.Any]] | None = None, return_ids: bool = True, return_phonemes: bool = True, overlap: ~typing.Literal[‘snap’, ‘strict’, ‘split’] = ‘snap’, lexicons: str | ~collections.abc.Sequence[str] | None = None, use_espeak_fallback: bool = True, use_cli: bool = False, espeak_mode: ~typing.Literal[‘auto’, ‘native’, ‘cli’] | None = None, strict: bool = True, strict_stress: bool = False, g2p: ~piperg2p.api.PiperG2P | None = None, language_routing: ~piperg2p.types.LanguageRoutingConfig | ~collections.abc.Mapping[str, ~typing.Any] | None = None, missing: ~piperg2p.codec.MissingPhonemePolicy | str = MissingPhonemePolicy.WARN) -> ~piperg2p.types.PhonemizeResult :module: piperg2p

Module-level phonemize() is an alias of phonemize_prepared() and returns PhonemizeResult. The compatibility parameters return_ids and return_phonemes are currently accepted but are no-ops; they do not alter the return type or omit fields.

.. py:function:: phonemize(text: str, language: str, *, config: ~piperg2p.config.VoiceConfig | str | ~pathlib.Path | ~collections.abc.Mapping[str, ~typing.Any] | None = None, overrides: ~collections.abc.Sequence[~piperg2p.types.OverrideSpan | ~collections.abc.Mapping[str, ~typing.Any] | ~collections.abc.Sequence[~typing.Any]] | None = None, annotations: ~collections.abc.Sequence[~piperg2p.types.TokenAnnotation | ~collections.abc.Mapping[str, ~typing.Any]] | None = None, return_ids: bool = True, return_phonemes: bool = True, overlap: ~typing.Literal[‘snap’, ‘strict’, ‘split’] = ‘snap’, lexicons: str | ~collections.abc.Sequence[str] | None = None, use_espeak_fallback: bool = True, use_cli: bool = False, espeak_mode: ~typing.Literal[‘auto’, ‘native’, ‘cli’] | None = None, strict: bool = True, strict_stress: bool = False, g2p: ~piperg2p.api.PiperG2P | None = None, language_routing: ~piperg2p.types.LanguageRoutingConfig | ~collections.abc.Mapping[str, ~typing.Any] | None = None, missing: ~piperg2p.codec.MissingPhonemePolicy | str = MissingPhonemePolicy.WARN) -> ~piperg2p.types.PhonemizeResult :module: piperg2p

.. py:function:: phonemes(*args: ~typing.Any, **kwargs: ~typing.Any) -> str :module: piperg2p

.. py:function:: phoneme_ids(*args: ~typing.Any, **kwargs: ~typing.Any) -> list[int] :module: piperg2p

Use the sentence.ids sequences as the normal Piper inference units; the flattened result IDs are convenience views. See result types.

Tokenization, cache, markers, and lexicon discovery

.. py:function:: tokenize(text: str, *, keep_punct: bool = True) -> list[~piperg2p.types.TokenSpan] :module: piperg2p

Tokenize prepared text without changing its source coordinate space.

.. py:function:: cache_info() -> ~piperg2p.cache.CacheInfo :module: piperg2p

.. py:function:: clear_cache(*, deep: bool = False) -> None :module: piperg2p

.. py:function:: parse_delimited(text: str, marker: str = ‘@’, escape: str = ‘') -> tuple[str, list[tuple[int, int]], list[str]] :module: piperg2p

Remove paired markers and return clean-text offsets and warnings.

.. py:function:: apply_marker_overrides(clean_text: str, marked_ranges: ~collections.abc.Sequence[tuple[int, int]], assignments: ~collections.abc.Sequence[~collections.abc.Mapping[str, str]] | ~collections.abc.Mapping[int, ~collections.abc.Mapping[str, str]]) -> list[~piperg2p.types.OverrideSpan] :module: piperg2p

Apply ordinal or sequence assignments to ranges from parse_delimited.

.. py:function:: available_lexicons(language: str, *, store: ~typing.Any = None) -> tuple[str, …] :module: piperg2p

Return installed pronunciation asset short names in stable order.

.. py:function:: lexicon_info(language: str, name: str, *, store: ~typing.Any = None) -> ~collections.abc.Mapping[str, ~typing.Any] :module: piperg2p

Return read-only metadata for an installed pronunciation asset.

Use ids_to_phonemes() for diagnostic/reverse inspection, not as a guaranteed lossless inverse: multiple phoneme symbols can share IDs or make a sequence ambiguous. See the usage guide, overrides, and lexicon guide.

.. py:function:: ids_to_phonemes(ids: ~collections.abc.Sequence[int], config: object) -> str :module: piperg2p

Decode framed Piper IDs using one explicit voice configuration.