SSML

Also known as: Speech Synthesis Markup Language

On this page 7

SSML, the Speech Synthesis Markup Language, is a W3C XML vocabulary that annotates text with instructions for a text-to-speech engine, controlling pronunciation, pauses, emphasis, pitch, rate and volume of the synthesized voice. Within the Speech & language AI area of artificial intelligence, SSML is the standard bridge between written content and the acoustic decisions a synthesis system would otherwise make on its own.

A plain string leaves every choice to the engine’s text normalization and prosody prediction. SSML lets an author override those predictions where they fail: reading a date correctly, spelling out an acronym, inserting a dramatic pause or switching to a different voice in the middle of a sentence.

How SSML controls a speech synthesis pipeline

SSML works by attaching explicit hints to stages of the synthesis pipeline that would otherwise be inferred automatically. A typical engine first normalizes text, then converts graphemes to phonemes, predicts prosody and finally renders a waveform with an acoustic model and a neural vocoder. Each SSML element targets one of these stages.

The document root is the speak element, which declares the version (1.0 or 1.1), the XML namespace and the default language through xml:lang. Inside it, plain text is spoken normally, while child elements such as say-as, phoneme, break and prosody modify how particular spans are processed. Because SSML is XML, the markup must be well formed: unescaped ampersands or unclosed tags usually cause the whole request to be rejected.

The table below maps the main pipeline stages to the SSML elements that influence them.

Pipeline stageWhat the engine decidesSSML elements
Text normalizationHow numbers, dates and symbols become wordssay-as, sub
PronunciationWhich phonemes represent each wordphoneme, lexicon
StructureSentence and paragraph boundariess, p, break
ProsodyPitch, speaking rate, loudness and stressprosody, emphasis
Voice selectionWhich speaker model renders the audiovoice, xml:lang
Media mixingPrerecorded clips and event markersaudio, mark
Synthesis stages and the SSML elements that affect them

Core SSML elements and their parameters

The core elements of SSML cover pauses, interpretation, pronunciation and prosody, and most production engines support this common subset. Attribute values follow the specification, but vendor engines differ in ranges, defaults and which values they honor.

ElementPurposeTypical attributes and values
breakInserts a pausetime such as 300ms or 1s; strength from none to x-strong
say-asSets how a token is interpretedinterpret-as such as date, cardinal, characters, telephone
phonemeGives an exact pronunciationalphabet IPA or x-sampa; ph with the phoneme string
subSpeaks a substitute for written textalias, for example the full form of an abbreviation
prosodyAdjusts pitch, rate and volumerate such as 90%, pitch such as +2st, volume such as -3dB
emphasisAdds or reduces stresslevel strong, moderate, reduced or none
voiceSwitches the speakername, gender, age or engine-specific identifiers
Frequently used SSML elements

Two details cause frequent confusion. First, the say-as values beyond the basics are not fully standardized; a companion W3C note lists common ones, yet engines implement their own sets. Second, relative prosody values such as +10% or +2st are applied on top of the voice’s natural contour, so the same markup sounds different with different voices.

SSML is an input format for text-to-speech, not a synthesis method, which separates it from neighboring concepts in speech technology. It describes what should be said and how, while models and other standards handle recognition, dialogue or the acoustic rendering itself.

ConceptRoleRelationship to SSML
Text-to-speechConverts text into audioConsumes SSML as its richest input format
Prosody predictionInfers melody and timing from textSSML overrides or nudges its output
Grapheme-to-phoneme conversionDerives pronunciations automaticallyphoneme and lexicons bypass it for listed words
PLS lexiconsW3C pronunciation dictionariesReferenced from SSML via the lexicon element
VoiceXMLDescribes voice dialoguesEmbeds SSML for its spoken prompts
Style prompts in neural TTSNatural language direction of toneComplementary; less precise but more expressive
How SSML relates to neighboring concepts

Modern neural text-to-speech models predict prosody far better than older concatenative systems, which reduces the need for heavy markup. However, natural language style prompts cannot guarantee that a drug name, part number or legal citation is pronounced exactly one way, and that deterministic control remains the main reason teams keep using SSML.

Practical use of SSML in production systems

In practice, SSML is most valuable where pronunciation accuracy and timing matter more than spontaneity. Voice assistants, interactive voice response menus, audiobook pipelines, navigation prompts and accessibility readers all generate SSML, usually from templates rather than by hand.

SituationRecommended markupReason
Brand or product namesphoneme with IPA, or a shared lexiconGuarantees one consistent pronunciation
Phone numbers and codessay-as telephone or charactersPrevents reading digits as one large number
Menu prompts in IVRShort break elements between optionsGives callers time to process each choice
Long-form narrationp and s structure, sparing prosodyKeeps natural flow while marking boundaries
Multilingual contentlang or voice switches per spanApplies correct phonology to foreign words
Choosing SSML features by situation

A sound workflow generates SSML programmatically, escapes user text before inserting it, validates the result against the engine’s supported tags and keeps a central pronunciation lexicon instead of scattering phoneme tags through templates. Teams also listen to samples after every voice upgrade, because markup tuned for one voice can sound unnatural with the next.

Limitations and common SSML mistakes

The main limitation of SSML is inconsistent engine support: a document that renders well in one service may be partly ignored or rejected by another. Some engines silently drop unknown elements, others return an error, and several cap the length of a single request or the maximum break duration.

  • Over-marking prosody makes speech sound robotic; neural voices usually need only targeted corrections.
  • Unescaped special characters such as the ampersand break XML parsing and fail the whole request.
  • Assuming portable say-as values leads to wrong readings when content moves to another engine.
  • Absolute pitch values in hertz ignore the voice’s natural range and can produce strained output.
  • Ignoring expressive extensions: speaking styles and emotions are vendor-specific, not part of the standard.

Finally, SSML cannot fix poor source text. Ambiguous sentences, missing punctuation and badly structured content still produce awkward speech, so editing the text itself is often the most effective improvement.

Understanding it simply

When a computer reads text aloud, it has to guess many things: how to say a name, whether 5/6 is a date or a fraction, and where to pause. SSML is a set of simple tags written around the text that answer those questions in advance.

Think of it as stage directions in a script. The actor still performs the lines, but the notes say speak slowly here, stress this word, pause for half a second, or say this name exactly like this. The result is speech that sounds clearer and more predictable for listeners.

Applied in practice

A regional pharmacy chain runs an automated phone line that reads prescription status to callers. Early tests with plain text produced problems: the synthetic voice read the order number 40217 as forty thousand two hundred seventeen, mispronounced several generic drug names and rushed through the pickup time.

The development team rebuilt the prompt templates in SSML. Order numbers are wrapped in say-as with the characters value, so each digit is spoken separately. Drug names come from a shared pronunciation lexicon with IPA entries checked by a pharmacist, pickup times use the time interpretation, and a 400 ms break separates each piece of information. The speaking rate for the summary sentence is reduced to 90%.

After rollout, the share of callers who asked an agent to repeat their order details dropped noticeably, and mispronunciation complaints largely disappeared. When the provider later released a new neural voice, the team only had to retest the lexicon rather than rewrite every prompt.