buchwandler

Result and span types

PiperG2P returns structured phonemization results and sentence-scoped model IDs. Source offsets throughout this API use half-open character ranges [start, end) into the exact input text.

PhonemizeResult

The high-level result contains:

  • clean_text: source text after the facade’s preparation boundary (PiperG2P does not perform semantic verbalization).

  • tokens: source-aligned TokenSpan entries.

  • extended_text: current extended text view; for PiperG2P it is the prepared source text.

  • phonemes: flattened phoneme-string convenience view.

  • token_ids: flattened ID list convenience view.

  • warnings: phonemization/encoding warning messages.

  • language_routes: routing decisions, when routing is requested.

  • sentences: authoritative sentence-level phonemes and IDs.

  • diagnostics: frontend/backend and optional lexicon diagnostics.

  • missing_phonemes: absent symbols recorded during encoding.

  • ids: tuple convenience view of token_ids.

  • phoneme_symbols: tuple of characters from the flattened phonemes string; use sentence phoneme data when symbol grouping matters.

Do not use the flattened token_ids/ids as the normal model-inference unit. Process each sentence.ids independently.

.. py:class:: PhonemizeResult(clean_text: str = ‘’, tokens: list[~piperg2p.types.TokenSpan] = , extended_text: str = ‘’, phonemes: str = ‘’, token_ids: list[int] = , warnings: list[str] = , language_routes: list[~piperg2p.types.LanguageRoute] = , sentences: tuple[~piperg2p.types.PhonemeSentence, …] = (), diagnostics: ~piperg2p.diagnostics.FrontendDiagnostics | None = None, missing_phonemes: tuple[str, …] = ()) :module: piperg2p :canonical: piperg2p.types.PhonemizeResult</p>

Bases: :py:class:object

High-level result with flattened convenience views and Piper sentence data.

.. py:attribute:: PhonemizeResult.clean_text :module: piperg2p :type: str :value: ‘’

.. py:attribute:: PhonemizeResult.tokens :module: piperg2p :type: list[~piperg2p.types.TokenSpan]

.. py:attribute:: PhonemizeResult.extended_text :module: piperg2p :type: str :value: ‘’

.. py:attribute:: PhonemizeResult.phonemes :module: piperg2p :type: str :value: ‘’

.. py:attribute:: PhonemizeResult.token_ids :module: piperg2p :type: list[int]

.. py:attribute:: PhonemizeResult.warnings :module: piperg2p :type: list[str]

.. py:attribute:: PhonemizeResult.language_routes :module: piperg2p :type: list[~piperg2p.types.LanguageRoute]

.. py:attribute:: PhonemizeResult.sentences :module: piperg2p :type: tuple[~piperg2p.types.PhonemeSentence, …] :value: ()

.. py:attribute:: PhonemizeResult.diagnostics :module: piperg2p :type: ~piperg2p.diagnostics.FrontendDiagnostics | None :value: None

.. py:attribute:: PhonemizeResult.missing_phonemes :module: piperg2p :type: tuple[str, …] :value: ()

.. py:property:: PhonemizeResult.text :module: piperg2p :type: str

.. py:property:: PhonemizeResult.ids :module: piperg2p :type: tuple[int, …]

.. py:property:: PhonemizeResult.phoneme_symbols :module: piperg2p :type: tuple[str, …]

</section>

PhonemeSentence

Each sentence records phonemes, phoneme_string (the joined string view), ids, missing_phonemes, and warnings. Its metadata field is a tuple of extra key/value pairs. Piper model inference should normally receive each sentence’s ids separately.

.. py:class:: PhonemeSentence(phonemes: ‘tuple[str, …]’, ids: ‘tuple[int, …]’, missing_phonemes: ‘tuple[str, …]’ = (), warnings: ‘tuple[str, …]’ = (), metadata: ‘tuple[tuple[str, Any], …]’ = ()) :module: piperg2p :canonical: piperg2p.types.PhonemeSentence

Bases: :py:class:object

.. py:attribute:: PhonemeSentence.phonemes :module: piperg2p :type: tuple[str, …]

.. py:attribute:: PhonemeSentence.ids :module: piperg2p :type: tuple[int, …]

.. py:attribute:: PhonemeSentence.missing_phonemes :module: piperg2p :type: tuple[str, …] :value: ()

.. py:attribute:: PhonemeSentence.warnings :module: piperg2p :type: tuple[str, …] :value: ()

.. py:attribute:: PhonemeSentence.metadata :module: piperg2p :type: tuple[tuple[str, ~typing.Any], …] :value: ()

.. py:property:: PhonemeSentence.phoneme_string :module: piperg2p :type: str

Source spans and caller annotations

TokenSpan preserves the original token text, half-open char_start/char_end offsets (also available as start/end), optional lang, extended_text, and caller metadata. TokenAnnotation records source-aligned optional text, pos, tag, lemma, language, and morph fields.

.. py:class:: TokenSpan(text: str, char_start: int, char_end: int, lang: str | None = None, extended_text: str | None = None, meta: dict[str, ~typing.Any] = ) :module: piperg2p :canonical: piperg2p.types.TokenSpan</p>

Bases: :py:class:object

A source-preserving token using half-open character offsets.

.. py:attribute:: TokenSpan.text :module: piperg2p :type: str

.. py:attribute:: TokenSpan.char_start :module: piperg2p :type: int

.. py:attribute:: TokenSpan.char_end :module: piperg2p :type: int

.. py:attribute:: TokenSpan.lang :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenSpan.extended_text :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenSpan.meta :module: piperg2p :type: dict[str, ~typing.Any]

.. py:property:: TokenSpan.start :module: piperg2p :type: int

.. py:property:: TokenSpan.end :module: piperg2p :type: int

.. py:class:: TokenAnnotation(start: ‘int’, end: ‘int’, text: ‘str | None’ = None, pos: ‘str | None’ = None, tag: ‘str | None’ = None, lemma: ‘str | None’ = None, language: ‘str | None’ = None, morph: ‘str | None’ = None) :module: piperg2p :canonical: piperg2p.types.TokenAnnotation

Bases: :py:class:object

.. py:attribute:: TokenAnnotation.start :module: piperg2p :type: int

.. py:attribute:: TokenAnnotation.end :module: piperg2p :type: int

.. py:attribute:: TokenAnnotation.text :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenAnnotation.pos :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenAnnotation.tag :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenAnnotation.lemma :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenAnnotation.language :module: piperg2p :type: str | None :value: None

.. py:attribute:: TokenAnnotation.morph :module: piperg2p :type: str | None :value: None

.. py:property:: TokenAnnotation.char_start :module: piperg2p :type: int

.. py:property:: TokenAnnotation.char_end :module: piperg2p :type: int

OverrideSpan contains char_start, char_end, and immutable attrs; its start and end properties are aliases. Common attributes are ph for explicit phoneme content, lang for an eSpeak voice override, and stress for structured stress after pronunciation resolution. See overrides.

.. py:class:: OverrideSpan(char_start: ‘int’, char_end: ‘int’, attrs: ‘Mapping[str, Any]’ = ) :module: piperg2p :canonical: piperg2p.types.OverrideSpan</p>

Bases: :py:class:object

.. py:attribute:: OverrideSpan.char_start :module: piperg2p :type: int

.. py:attribute:: OverrideSpan.char_end :module: piperg2p :type: int

.. py:attribute:: OverrideSpan.attrs :module: piperg2p :type: ~collections.abc.Mapping[str, ~typing.Any]

.. py:property:: OverrideSpan.start :module: piperg2p :type: int

.. py:property:: OverrideSpan.end :module: piperg2p :type: int

</section>

Routing types

LanguageRoute records a half-open source span, selected language, optional requested_language, decision reason, and evidence. LanguageRoutingConfig accepts mode="explicit" or mode="auto"; automatic routing changes the default only on unambiguous configured evidence. Explicit spans are supplied by the caller as overrides.

.. py:class:: LanguageRoute(char_start: ‘int’, char_end: ‘int’, language: ‘str’, requested_language: ‘str | None’ = None, reason: ‘str | None’ = None, evidence: ‘tuple[str, …]’ = ()) :module: piperg2p :canonical: piperg2p.types.LanguageRoute

Bases: :py:class:object

.. py:attribute:: LanguageRoute.char_start :module: piperg2p :type: int

.. py:attribute:: LanguageRoute.char_end :module: piperg2p :type: int

.. py:attribute:: LanguageRoute.language :module: piperg2p :type: str

.. py:attribute:: LanguageRoute.requested_language :module: piperg2p :type: str | None :value: None

.. py:attribute:: LanguageRoute.reason :module: piperg2p :type: str | None :value: None

.. py:attribute:: LanguageRoute.evidence :module: piperg2p :type: tuple[str, …] :value: ()

.. py:class:: LanguageRoutingConfig(mode: ‘str’ = ‘explicit’, languages: ‘tuple[str, …]’ = (), lexicons: ‘Mapping[str, Sequence[str]]’ = ) :module: piperg2p :canonical: piperg2p.types.LanguageRoutingConfig</p>

Bases: :py:class:object

.. py:attribute:: LanguageRoutingConfig.mode :module: piperg2p :type: str :value: ‘explicit’

.. py:attribute:: LanguageRoutingConfig.languages :module: piperg2p :type: tuple[str, …] :value: ()

.. py:attribute:: LanguageRoutingConfig.lexicons :module: piperg2p :type: ~collections.abc.Mapping[str, ~collections.abc.Sequence[str]]

The runtime currently accepts per-language evidence mappings, lookup-capable objects, or callables even though LanguageRoutingConfig.lexicons is annotated more narrowly. This reference records behavior without changing that contract. See language routing.

</section> </section> </div>