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 !']

Author

Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui

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:
  • text (str) – The text to synthesise.

  • first_chunk_sentences (int, optional) – How many sentences to place in the first chunk. Keeping this at 1 (the default) minimises TTFA; larger values reduce per-chunk overhead at the cost of a slower first emission.

Returns:

Chunks of text to synthesise in order. The first chunk holds first_chunk_sentences sentences; 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 by merge_short_fragments(), which changes grouping only, never the words or their order.

Return type:

list[str]

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_chars into 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:
  • chunks (list of str) – Chunks in reading order.

  • min_chars (int, optional) – Length below which a chunk is folded into a neighbour.

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:

list of str

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:

list[str]

Examples

>>> split_sentences("Un. Deux. Trois.")
['Un.', 'Deux.', 'Trois.']
>>> split_sentences("no terminator here")
['no terminator here']
>>> split_sentences("   ")
[]