Overview
TTS services read text literally, which is wrong for anything written to be seen rather than said. Left alone, a service reads:VoiceFormatter rewrites these before synthesis, so they come out as “forty-two dollars and fifty cents”, “A P I”, and “March 15th, twenty twenty-five”.
It bundles the individual transforms in pipecat.utils.text.transforms behind one object, applying them in a deliberate order: structural cleanup first, language expansions second, your own replacements last.
Example Implementation
Runnable bot with voice formatting applied
Usage
Attach it to any TTS service throughtext_transforms. The "*" aggregation type runs it on every text frame regardless of how the text was aggregated:
num2words, which the number-expanding transforms depend on, is a base dependency.
Configuration
Strip Markdown formatting symbols — bold, italic, headers, code spans. Text
inside inline code is kept as written, so
__init__, *args, and
[label](url) keep their symbols.Reduce a Markdown link or image to its label or alt text, so the URL isn’t
spoken. Only used when
strip_markdown=True.Expand currency amounts, so
"$42.50" becomes "forty two dollars and fifty cents". An amount followed by a scale word (thousand, million, billion,
or trillion) or its abbreviation (k, m/mn, b/bn, t/tn) is read
as one number, so "$2.5 billion" and "$2.5bn" become "two point five billion dollars". Trailing zeros in the fraction are dropped, so "$2.50 million" reads the same as "$2.5 million".Expand unit abbreviations, so
"5km" becomes "5 kilometers". The
single-letter units m and g and the unit in match only in lowercase, so
"5m" becomes "5 meters" but "5M" and "5G" are left as written. Liters
match l or L.Expand bare numeric digits into words. Off by default, because plenty of
numbers are clearer read as digits — a room number, a year, a version.
Numbers above this value are read digit by digit instead of as a quantity.
Only applies when
expand_numbers=True. None expands every number as words.(regex_pattern, replacement) pairs, applied after every other transform.Turning pieces off
Every option is independent, so a bundle can be narrowed to what a particular bot needs:number_digit_cutoff is the option worth knowing about: with expand_numbers=True and no cutoff, an account number is read as a single enormous quantity. Setting a cutoff keeps small numbers as words and switches longer ones to digit-by-digit.
Using transforms individually
VoiceFormatter is a convenience. Each transform is also an async callable you can register on its own:
strip_markdown reduces a Markdown link or image to its label or alt text. To keep link syntax as written, register a StripMarkdown instance instead, which takes strip_urls:
strip_markdown, normalize_acronyms, expand_currency, expand_percentages, expand_phone_numbers, expand_units, email_to_speech, and normalize_dates. expand_numbers and replace_text take configuration, so call them to get the transform: expand_numbers(digit_cutoff=2025) and replace_text([(r"\bDr\.", "Doctor")]).
A transform is any async callable with this signature, so your own slots in the same way:
Notes
- Order matters. The bundle applies structural cleanup first, then language expansions, then
custom_replacements. Registering transforms individually puts that order in your hands — list them in the order you want them applied. - Transforms run before synthesis, not before the context. What the bundle rewrites is what the TTS service is asked to say; the conversation context keeps the LLM’s original text.