Voice Formatting Plan

Voice Formatting Plan: Punctuation, Numbers & Replacements

Overview

Before your assistant's raw text response reaches the text-to-speech (TTS) provider, Sulus runs it through a formatting pipeline that rewrites punctuation, numbers, dates, and other text patterns so they sound natural when spoken aloud. This pipeline is enabled by default for every assistant. This page covers the full sequence of formatting steps, the two aspects you can customize, and how to disable formatting entirely if you want the model's raw output passed straight to the voice provider.

How the Formatting Pipeline Works

The formatter applies each of the following transformations in order:

Step	What it does	Example
Remove angle-bracket content	Strips tags like `<...>` from the output	`<pause>Hello` → `Hello`
Remove markdown symbols	Strips characters such as underscores, backticks, and tildes	`_bold_` → `bold`
Remove phrases in asterisks	Strips text wrapped in single or double asterisks	`note` → `(removed)`
Convert newlines to periods	Replaces line breaks with periods for smoother speech	`Hi.\nBye` → `Hi. Bye`
Convert colons to periods	Replaces colons with periods	`Note: call back` → `Note. call back`
Format acronyms	Adjusts casing of known acronyms for natural pronunciation	`NASA` → `nasa`
Format dollar amounts	Spells out currency values	`$42.50` → "forty two dollars and fifty cents"
Format emails	Spells out email symbols	`[email protected]` → "a at b dot com"
Format dates	Converts numeric dates to spoken form	`2023-05-10` → "Wednesday, May 10, 2023"
Format times	Adjusts numeric time expressions for speech	`14:00` → "14"
Format distances, units, percentages, and phone numbers	Spells out measurement and contact information	`5km` → "5 kilometers"; `50%` → "50 percent"; `123-456-7890` → digit-by-digit
Format numbers	Spells out negative numbers and decimals; years are read as digits	`-9` → "minus nine"; `2.5` → "two point five"
Remove remaining asterisks	Strips any leftover asterisk characters	`hi` → `hi`
Apply user-defined replacements	Runs your custom exact/regex substitutions last	`ST` → `STREET` (if configured)

Because these run in a fixed sequence, your custom replacements (the final step) see the already-formatted text, not the original raw output.

Customizing the Number-to-Digits Cutoff

The formatter needs a rule for deciding when a number should be read as individual digits (e.g., a year) versus spelled out as a full number. This is controlled by a single cutoff field, which defaults to 2025 (the current year at time of writing) — numbers at or below the cutoff tend to be read as digit sequences, while larger numbers are spelled out in full. If your assistant regularly discusses larger numeric values you want read digit-by-digit (for example, order or account numbers), raise the cutoff value accordingly.

Custom Replacements

The second customizable aspect is a list of user-defined replacements, applied as the final formatting step. Two replacement types are supported:

Exact — replaces an exact string match, useful for abbreviations your assistant should expand (e.g., ST → STREET)
Regex — replaces any text matching a regular expression pattern, useful for broader pattern-based substitutions

Replacements run in the order you define them, after every other formatting step has already run.

Disabling Formatting Entirely

If you want your assistant's raw model output sent directly to the voice provider with no transformation at all, formatting can be turned off at two levels using boolean fields:

Disabling the overall formatting pipeline turns off every step described above, including punctuation, number, and date formatting.
Disabling the formatting plan specifically (as opposed to the broader chunking behavior it lives under) has the same practical effect for formatting purposes — raw text passes straight through to TTS.

Turning formatting off is most useful when your system prompt already produces speech-ready text, or when you want full manual control over exactly what gets spoken.

In summary: the voice formatting plan is on by default and runs a fixed sequence of punctuation, number, and text-pattern transformations before your assistant speaks. You can fine-tune it with a numeric cutoff and your own replacement rules, or disable it entirely if you'd rather send raw model output straight to TTS.

On this page