voice_formatter

Configurable voice formatting bundle for TTS preprocessing.

class pipecat.utils.text.transforms.voice_formatter.VoiceFormatter(*, strip_markdown: bool = True, expand_phone_numbers: bool = True, normalize_acronyms: bool = True, expand_currency: bool = True, expand_numbers: bool = False, number_digit_cutoff: int | None = None, expand_percentages: bool = True, expand_units: bool = True, email_to_speech: bool = True, normalize_dates: bool = True, custom_replacements: list[tuple[str, str]] | None = None)[source]

Bases: object

Configurable bundle that applies a pipeline of voice-formatting transforms.

Each option enables or disables one transform. Transforms are applied in a deliberate order: structural cleanup first, language expansions second, user replacements last.

Example:

formatter = VoiceFormatter(
    strip_markdown=True,
    expand_currency=True,
    number_digit_cutoff=2025,
    custom_replacements=[(r"\bDr\.", "Doctor")],
)
tts = CartesiaTTSService(
    text_transforms=[("*", formatter)],
)
__init__(*, strip_markdown: bool = True, expand_phone_numbers: bool = True, normalize_acronyms: bool = True, expand_currency: bool = True, expand_numbers: bool = False, number_digit_cutoff: int | None = None, expand_percentages: bool = True, expand_units: bool = True, email_to_speech: bool = True, normalize_dates: bool = True, custom_replacements: list[tuple[str, str]] | None = None)[source]

Initialize the voice formatter.

Parameters:

  • strip_markdown – Strip Markdown formatting symbols (bold, italic, headers, code spans). Enabled by default.

  • expand_phone_numbers – Space out phone number digits for individual pronunciation. Enabled by default.

  • normalize_acronyms – Space out uppercase acronyms (e.g. "API" → "A P I"). Enabled by default.

  • expand_currency – Expand currency amounts to spoken form (e.g. "$42.50" → "forty two dollars and fifty cents"). Requires num2words.

  • expand_numbers – Expand numeric digits to spoken words. Disabled by default since it can affect numbers that are better read as digits. Requires num2words.

  • number_digit_cutoff – Numbers above this value are read digit-by-digit instead of as a quantity. Defaults to None (expand all numbers as words). Only used when expand_numbers=True.

  • expand_percentages – Expand percentage expressions (e.g. "50%" → "fifty percent"). Requires num2words.

  • expand_units – Expand unit abbreviations (e.g. "5km" → "5 kilometers"). Enabled by default.

  • email_to_speech – Transform email addresses to spoken form. Enabled by default.

  • normalize_dates – Expand date expressions to spoken form. Requires num2words.

  • custom_replacements – List of (regex_pattern, replacement) pairs applied after all other transforms.