--- description: 'Text input requirements for the ABR SDK TTS API: the built-in normalization pipeline, the model character set, and SSML markup.' --- # Input format The TTS API accepts raw UTF-8 text bytes. The backend normalizes pushed text itself, one sentence at a time, so numbers, dates, currency amounts, acronyms, and abbreviations can be pushed as-is. This page describes what that normalization does, the character set the model ends up speaking, and the SSML markup the model understands. The normalization steps and character set below are those of the **English** packages. Each language package ships its own normalizer for the conventions of that language; see {doc}`/models-tts` for the available languages. ## Pushing text ::::{lang-set} :::{lang} python Pass text as UTF-8-encoded `bytes` to {api}`Tts.push`: ```python tts.push("Dr. Smith owed $42 to the WHO.".encode("utf-8")) # spoken as "doctor Smith owed forty two dollars to the W H O." ``` ::: :::{lang} c Push the UTF-8 bytes of the text into the application's input buffer, here through the `session.h` helper: ```c const char text[] = "Dr. Smith owed $42 to the WHO."; abr_session_push(&session, (const uint8_t *)text, strlen(text), on_pcm, NULL); // spoken as "doctor Smith owed forty two dollars to the W H O." ``` ::: :::: ## What normalization does The backend runs these steps, in order, on the spoken text: | Step | Example | | ----------------------------- | ------------------------------------------------------------------------------------------ | | British to American spellings | `colour` → `color`, `realise` → `realize` | | Spell out acronyms | `WHO` → `W H O`, `HTTP2` → `H T T P two` | | Normalize dates and fractions | `12/25/2024` → `December twenty fifth, two thousand twenty four`, `3/4` → `three quarters` | | Numbers to words | `$42.50` → `forty two dollars and fifty cents`, `3.14` → `three point one four` | | Unicode normalization | `é` → `e`, `—` → `,`, `…` → `, , ,` | | Collapse repeated punctuation | `!!!!` → `!` | | Collapse whitespace | multiple spaces → single space | | Remove special characters | drops anything outside the model alphabet | | Expand abbreviations | `Dr.` → `doctor`, `St.` → `street`, `etc.` → `et cetera` | A trailing period is added when the utterance has no sentence-ending punctuation. The numbers step handles currency amounts, percentages, decimals, ordinals, and cardinals, and reads a leading minus as a sign (`-5` → `negative five`, `-$3.50` → `negative three dollars and fifty cents`). The minus reads as a sign only directly before a digit, at the start of the text or after whitespace; ranges (`5-10`), compounds (`COVID-19`), and list bullets (`- 5`) keep the hyphen. An all-caps token that the pronunciation dictionary knows as a word is spoken as that word rather than spelled out, so `NASA` is voiced. Tokens shorter than four characters are always spelled, so `US` and `IT` are not mistaken for the everyday words they spell. The result uses the restricted character set the model's phoneme dictionary operates on: | Accepted | Examples | | ----------------------------- | ---------------- | | Letters (upper and lowercase) | `a`–`z`, `A`–`Z` | | Space | ` ` | | Apostrophe | `'` | | Comma, period | `,` `.` | | Question mark, exclamation | `?` `!` | | Hyphen | `-` | ## SSML markup The model supports a subset of SSML (Speech Synthesis Markup Language) for controlling prosody and emotion. Well-formed tags pass through normalization untouched: only the spoken text between tags is normalized. Malformed tags (an unquoted attribute value, a missing closing quote) are dropped with a warning through the SDK log callback, so one bad tag cannot abort the utterance. Tags and attributes outside the table below are passed through and ignored by the model. ### Supported tags | Tag | Description | | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `` | Optional top-level wrapper. | | `` | Controls speech rate, pitch, and volume. Accepts named presets (`x-slow`, `slow`, `medium`, `fast`, `x-fast` for rate; `x-low` through `x-high` for pitch; `silent` through `x-loud` for volume) or percentage values. Tags are nestable. | | `` | Applies a composite prosody preset. Nestable with ``. | Supported `` types: `apologetic`, `calm`, `empathetic`, `firm`, `lively`. When SSML tags are present, no trailing period is added between or after the spoken runs, so end sentences with your own punctuation. The utterance ends when the input is flushed, for example by {api}`Tts.wait_for_completion`. :::{admonition} Next steps :class: hint - {doc}`/sdk/tts/examples`: full examples showing how to synthesize text. - {doc}`/sdk/tts/overview`: overview of the TTS streaming model and output format. :::