speaker_helper.text module
Text segmentation for low-latency streaming synthesis.
Module summary
In streaming mode the time to first audio (TTFA) is dominated by how much text the engine must synthesise before it can emit anything. Splitting a paragraph into sentence-sized units lets speaker-helper synthesise and emit the first unit quickly while later units are still being produced. This module holds the deterministic, dependency-free splitter used for that.
Usage example
>>> from speaker_helper.text import split_sentences
>>> split_sentences("Bonjour. Comment ça va ? Bien !")
['Bonjour.', 'Comment ça va ?', 'Bien !']
- speaker_helper.text.MIN_CHUNK_CHARS = 4
Chunks shorter than this many characters are folded into a neighbour by
merge_short_fragments().Why a character count, in a module that knows nothing about engines: the chatterbox multilingual tokenizer is a grapheme tokenizer, so its token count tracks characters almost exactly — “Un.” is 3 of each, “Oui.” is 4 of each. That is the boundary measured on 2026-10-28 (chatterbox-tts 0.1.7): below 4 tokens, upstream’s AlignmentStreamAnalyzer has no alignment window and dies in step() with “max(): Expected reduction dim 1 to have non-zero size”. “Un.” and “A.” fail there; “Oui.” and “Non.” succeed.
The value sits exactly on the measured boundary rather than above it, so the merge changes grouping only where synthesis would otherwise break. If a fragment ever slips through, the chatterbox backend still refuses it with a diagnosis, so a miss is loud rather than silent — which is why no safety margin is baked in here.
- speaker_helper.text.chunk_for_streaming(text, first_chunk_sentences=1)[source]
Group sentences into synthesis chunks, keeping the first one small.
- Parameters:
- Returns:
Chunks of text to synthesise in order. The first chunk holds
first_chunk_sentencessentences; every remaining sentence is its own chunk so downstream audio keeps flowing steadily — except that fragments too short to synthesise are folded into a neighbour bymerge_short_fragments(), which changes grouping only, never the words or their order.- Return type:
Examples
>>> chunk_for_streaming("Bonjour. Ça va ? Très bien.", first_chunk_sentences=1) ['Bonjour.', 'Ça va ?', 'Très bien.'] >>> chunk_for_streaming("Bonjour. Ça va ? Très bien.", first_chunk_sentences=2) ['Bonjour. Ça va ?', 'Très bien.'] >>> chunk_for_streaming("Bonjour. Un. Et voilà.") # too short to stand alone ['Bonjour. Un.', 'Et voilà.']
- speaker_helper.text.merge_short_fragments(chunks, min_chars=4)[source]
Fold chunks below
min_charsinto a neighbour, leaving words untouched.A three-character chunk is a poor synthesis unit for any engine — there is not enough context for sensible prosody — and for chatterbox’s multilingual model it is an outright crash (see
MIN_CHUNK_CHARS). Merging is the conservative repair: the words spoken, and their order, are identical; only the grouping changes, so a short sentence is said in the breath of its neighbour instead of alone.A fragment merges into the chunk before it when there is one, so the first chunk stays small and time-to-first-audio is unaffected. A short first chunk has no predecessor, so it merges forward into the second.
- Parameters:
- Returns:
Chunks in the same order, with short fragments absorbed. A lone chunk is always returned as-is: with no neighbour there is nothing to merge into, and inventing words to pad it would change what is spoken.
- Return type:
Examples
>>> merge_short_fragments(["Bonjour.", "Un.", "Et voilà."]) ['Bonjour. Un.', 'Et voilà.'] >>> merge_short_fragments(["Un.", "Bonjour tout le monde."]) ['Un. Bonjour tout le monde.'] >>> merge_short_fragments(["A.", "B.", "C."]) ['A. B. C.'] >>> merge_short_fragments(["Un."]) ['Un.']
- speaker_helper.text.split_sentences(text)[source]
Split text into sentence-sized, non-empty, stripped units.
- Parameters:
text (str) – Arbitrary text, possibly multi-sentence and multi-line.
- Returns:
Sentences in order, each stripped of surrounding whitespace, with their terminating punctuation preserved. Text without any terminator returns a single-element list (the whole stripped input); empty or whitespace-only input returns an empty list.
- Return type:
Examples
>>> split_sentences("Un. Deux. Trois.") ['Un.', 'Deux.', 'Trois.'] >>> split_sentences("no terminator here") ['no terminator here'] >>> split_sentences(" ") []