SSML reference
The Speech Synthesis Markup Language (SSML) is an XML-based markup language for speech synthesis. Its essential role is to provide authors of synthesizable content a standard way to control aspects of speech such as pronunciation, volume, pitch, rate, etc. across different synthesis-capable platforms.
Note that not all of the elements and options described in the W3 SSML specification are currently supported by all providers. This page details which elements are available for each provider.
Reserve characters
Avoid using SSML reserve characters in the text that is to be converted to audio. When you need to use an SSML reserve character, prevent the character from being read as code by using its escape code. The following table shows reserved SSML characters and their associated escape codes.
Character | Escape code |
---|---|
" |
|
& |
|
' |
|
< |
|
> |
|
Markups
Audio CERENCE VOXYGEN READSPEAKER
Audio SSML Markup is used to insert a recorded audio file. If the audio file cannot be retrieved, the element's contents are synthesized. The content is the fallback text used when the audio file is not supported.
Example:
<audio src="file:laugh">
haha
</audio>
Attribute | Description |
---|---|
src | The URI of a document with an appropriate MIME type. URIs may be absolute or relative to the base:uri specified in <speak> element. Audio files may be local ( Supported audio files:
READSPEAKER CERENCE READSPEAKER |
mode READSPEAKER | It is a custom attribute. If it is set as |
fetchtimeout VOXYGEN READSPEAKER (SSML 1.1) | Signed or unsigned positive number or zero followed by VOXYGEN READSPEAKER |
fetchhint VOXYGEN (SSML 1.1) | This tells the synthesis processor whether or not it can attempt to optimize rendering by pre-fetching audio. Available values:
|
maxage VOXYGEN (SSML 1.1) | A positive integer or zero. |
maxstale VOXYGEN (SSML 1.1) | A positive integer or zero. |
clipBegin VOXYGEN (SSML 1.1) | Signed or unsigned positive number or zero followed by |
clipEnd VOXYGEN (SSML 1.1) | Signed or unsigned positive number or zero followed by |
repeatCount VOXYGEN (SSML 1.1) | Signed or unsigned positive number or zero. Default VOXYGEN |
repeatDur VOXYGEN (SSML 1.1) | Signed or unsigned positive number or zero followed by VOXYGEN |
soundLevel READSPEAKER VOXYGEN (SSML 1.1) | Signed number followed by VOXYGEN |
speed READSPEAKER VOXYGEN (SSML 1.1) | Unsigned positive number or zero followed by VOXYGEN |
vox:gain VOXYGEN | Signed number followed by |
vox:fadelevel VOXYGEN | Signed number followed by |
vox:fadein VOXYGEN | Signed or unsigned positive number or zero followed by VOXYGEN |
vox:fadeout VOXYGEN | Signed or unsigned positive number or zero followed by VOXYGEN |
vox:fadeinAttack VOXYGEN | Signed or unsigned positive number or zero followed by |
vox:fadeinRelease VOXYGEN | Signed or unsigned positive number or zero followed by |
vox:fadeoutAttack VOXYGEN | Signed or unsigned positive number or zero followed by |
vox:fadeoutRelease VOXYGEN | Signed or unsigned positive number or zero followed by |
vox:tempo VOXYGEN | The tempo attribute can be used to speed up or slow down the rate of the audio file without changing the pitch level. VOXYGEN |
Audio Mix VOXYGEN
Audiomix SSML Markup is used to insert a recorded audio file, and mix it with the element content. If the audio file is longer than the speech, it is truncated. If he is shorter, he is repeatedly read.
Attributes of the <audiomix>
element have the same meaning and restrictions as those of the <audio>
element, but the default fade attack and release durations may differ.
Example:
<vox:audiomix src="file:laugh" fetchtimeout="3ms">
haha
</vox:audiomix>
Attribute | Description |
---|---|
src | Name of file (absolute or relative URI) |
fetchtimeout | Signed or unsigned positive number or zero followed by |
fetchhint | This tells the synthesis processor whether or not it can attempt to optimize rendering by pre-fetching audio. Available values:
|
maxage | A positive integer or zero. |
maxstale | A positive integer or zero. |
clipBegin | Signed or unsigned positive number or zero followed by |
clipEnd | Signed or unsigned positive number or zero followed by |
soundLevel | Signed number followed by VOXYGEN |
speed | Unsigned positive number or zero followed by VOXYGEN |
gain | Signed number followed by |
fadelevel | Signed number followed by |
fadein | Signed or unsigned positive number or zero followed by VOXYGEN |
fadeout | Signed or unsigned positive number or zero followed by VOXYGEN |
fadeinAttack | Signed or unsigned positive number or zero followed by |
fadeinRelease | Signed or unsigned positive number or zero followed by |
fadeoutAttack | Signed or unsigned positive number or zero followed by |
fadeoutRelease | Signed or unsigned positive number or zero followed by |
Break CERENCE READSPEAKER VOXYGEN
Break SSML Markup is used to temporarily pause the speech.
It is inserted at cursor position as an empty element, and can be used with milliseconds or seconds.
Example:
<break time="300ms"/>
Attribute | Description | |||
---|---|---|---|---|
time | Signed or unsigned positive number or zero followed by VOXYGEN Extension: percentage values are also accepted. | |||
strength | Value | CERENCE | VOXYGEN | READSPEAKER |
none | 0ms | ≅ 0ms | ≅ 0ms | |
x-weak | 20ms | ≅ 50ms | ≅ 200ms | |
weak | 100ms | ≅ 100ms | ≅ 450ms | |
medium | 500ms | ≅ 500ms | ≅ 700ms | |
strong | 1000ms | ≅ 1000s | ≅ 900ms | |
x-strong | 1500ms | ≅ 2000s | ≅ 1200ms |
Checksum VOXYGEN
Enable a cyclic-redundancy check to be performed on the signal and events in the most recent breath group (delimited by silence) rendered from the content of the current document.
Example:
<vox:checksum crc32="2016915618"></vox:checksum>
Attribute | Description | |||
---|---|---|---|---|
crc32 | Unsigned positive number or zero. |
Computed duration VOXYGEN
Example:
<prosody vox:computedduration="on"></prosody>
Attribute | Description | |||
---|---|---|---|---|
vox:computedduration |
|
Computed pitch VOXYGEN
Example:
<prosody vox:computedpitch="on"></prosody>
Attribute | Description | |||
---|---|---|---|---|
vox:computedpitch |
|
Contour VOXYGEN
Contour SSML Markup is used to set different pitch values at different timestamps.
In each pair (time, pitch)
, the first value is a percentage of the period of the contained text and the second value is the value of the pitch attribute.
Example:
<prosody contour="(0%, +10%) (50%, +50%) (100%, +90%)">
I am speaking.
</prosody>
DurationVOXYGEN
Duration SSML Markup is used to set the duration of the marked speech. Signed or unsigned positive number or zero followed by s
for seconds or ms
for milliseconds.
Example:
<prosody duration="5s">I'm speaking very slow.</prosody>
Emphasis CERENCE READSPEAKER VOXYGEN
Emphasis SSML Markup is used to request that the contained text be spoken with emphasis. Please note that the realization of emphasis is voice dependent.
Example:
That is a <emphasis> big </emphasis> car!
VOXYGEN
The realization of emphasis is voice dependent.
Attribute | Description | |
---|---|---|
level |
|
Lang CERENCE READSPEAKER VOXYGEN
With the lang SSML makup it is possible to switch language. Changing the language also changes the voice, if there is a voice available.
The lang
element can only contain text to be rendered and the following elements: audio
, break
, emphasis
, lang
, lookup
, mark
, p
, phoneme
, prosody
, say-as
, sub
, s
, token
, voice
and w
.
Example:
English, <lang xml:lang="de">Deutsch</lang>, English.
Attribute | Description | |
---|---|---|
xml:lang | A required attribute specifying the language of the element. | |
onlangfailure | An optional attribute specifying the desired behavior upon language speaking failure. READSPEAKER | |
Value | Description | |
ignoretext | The synthesis processor will not attempt to render the text that is in the failed language. | |
ignorelang | The synthesis processor will ignore the change in language and speak as if the content were in the previous language. | |
changevoice | If a voice exists that can speak the language, the synthesis processor will switch to that voice and speak the content. Otherwise, the processor chooses another behavior (either | |
processorchoice | The synthesis processor chooses the behavior (either |
Lexicon READSPEAKER VOXYGEN
Lexicon SSML markup is used to reference a lexicon document.
READSPEAKER
Supported format: PLS (Pronunciation Lexicon Specification 1.0) and CSV (User-Dictionary of ReadSpeaker).
VOXYGEN
Supported format: PLS (Pronunciation Lexicon Specification 1.0).
Example:
<lexicon xml:id="myLexiconDoc"></lexicon>
Attribute | Description |
---|---|
uri | Location of the lexicon document. |
xml:id | A unique identifier for the lexicon document. |
type | VOXYGEN |
fetchtimeout | VOXYGEN |
maxage | VOXYGEN |
maxstale | VOXYGEN |
Lookup READSPEAKER VOXYGEN
Example:
<lookup ref="myLexiconDoc"></lookup>
Attribute | Description | |
---|---|---|
ref | The |
Mark READSPEAKER VOXYGEN
The mark element specifies a named event which is triggered by the TTS engine when that location in the text is encountered in the generated audio stream. (What effect this event has is application specific, but it doesn’t affect the audion being generated)
The mark event must have a name attribute. The given name doesn’t have any meaning to the TS engine, but is included in the generated event.
Note that built-in normalization rules might, in some particular contexts such as date and currency expressions, cause adjacent words and numbers to be reordered. The TTS engine will generally try to preserve the association between marks and adjacent words in such cases, meaning that the mark events are not necessarily triggered in the exact order in which they occur in the SSML input but rather in a way that is more true to the reading order.
Example:
<mark name="item1"/>First item, <mark name="item2"/>second item.
Attribute | Description | |
---|---|---|
name | Marker name | |
vox:typeVOXYGEN | Value | Description |
sync (default) | The voice synthesis engine will trigger an event when that location in the text is encountered in the generated audio stream. | |
wait | A wait marker allows rendering of the audio signal to be deferred until the duration of the immediately following content has been determined. The end of the content whose duration is to be determined is marked by either the end of the root <speak> element or a <mark> element, of any type, that bears the same name (case-sensitive).
XML
When Baratinoo processes the above markup, notification is first made by a |
Paragraph CERENCE READSPEAKER VOXYGEN
Paragraph SSML markup is used to indicate a paragraph in your text.
While the TTS engine already recognize paragraphs automatically, it can help it to better understand and render your text.
Example:
<p>
You have 4 new messages.
</p>
ReadSpeaker adds a sentence break before and after the element.
Attribute | Description | |
---|---|---|
xml:lang | An optional attribute specifying the language of the element. | |
onlangfailure | An optional attribute specifying the desired behavior upon language speaking failure. Not supported by READSPEAKER. | |
Value | Description | |
ignoretext | The synthesis processor will not attempt to render the text that is in the failed language. | |
ignorelang | The synthesis processor will ignore the change in language and speak as if the content were in the previous language. | |
changevoice | If a voice exists that can speak the language, the synthesis processor will switch to that voice and speak the content. Otherwise, the processor chooses another behavior (either | |
processorchoice | The synthesis processor chooses the behavior (either |
Phoneme CERENCE READSPEAKER VOXYGEN
Phoneme SSML Markup is used to provide a phonetic pronunciation for the contained text.
Example:
<phoneme alphabet="ipa" ph="vivo͡ʊkə">
Vivoka
</phoneme>
Support of the alphabet is limited to sounds that map to the phonetic symbols of the current voice.
VOXYGEN
The value of the ph
attribute is ignored for unsupported alphabets and a warning is issued.
Attribute | Description | |
---|---|---|
alphabet | Provider | Values |
CERENCE |
| |
READSPEAKER |
| |
VOXYGEN |
| |
ph | List of phonetic symbols. Separated by underscore | |
type | VOXYGEN READSPEAKER | |
vox:idl | VOXYGEN Control the inclusion or exclusion of specific acoustic units as candidate realizations for each part of the given phonetic pronunciation.
|
Pitch CERENCE READSPEAKER VOXYGEN
Pitch SSML Markup is used to set the pitch of the voice.
It accepts predefined values as well as relative percentages numbers followed by %.
Example:
<prosody pitch="x-low">Oh my voice</prosody>
Value | VOXYGEN | CERENCE | READSPEAKER | |
---|---|---|---|---|
| 50% of | -30% | 50 | |
| 75% of | -15% | 75 | |
| 100% of | 0% | 100 | |
| 133% of | +35% | 150 | |
| 200% of | +60% | 200 | |
| Initial value for current voice | 0% | 100 | |
Relative percentage | [+/-] number followed by |
Prompt CERENCE
Prompt SSML Markup is used to insert an ActivePrompt at a specific location in the text.
Example:
<prompt id="myPrompt"></prosody>
Attribute | Description | |
---|---|---|
id | The prompt id. |
Range VOXYGEN
Range SSML Markup is used to set the range of the voice.
It accepts predefined values as well as relative percentages numbers followed by %.
Example:
I'm going <prosody range="x-low">far</prosody>
Value | Description |
---|---|
| 50% of |
| 75% of |
| 100% of |
| 133% of |
| 200% of |
| Initial value for current voice |
Relative percentage | [+/-] number followed by |
Relative change | [+/-] number followed by |
Absolute value in Hertz | Unsigned number followed by |
Rate CERENCE READSPEAKER VOXYGEN
Rate SSML Markup is used to set speech rate of the voice.
It accepts predefined values as well as relative percentages numbers followed by %.
Example:
<p>
<s>
The subject is <prosody rate="-20%">ski trip</prosody>
</s>
</p>
Value | VOXYGEN | CERENCE | READSPEAKER |
---|---|---|---|
| 50% of | 50 | 50 |
| 75% of | 75 | 75 |
| 100% of | 100 | 100 |
| 125% of | 150 | 125 |
| 150% of | 200 | 150 |
| Initial value for current voice | 100 | 100 |
Relative percentage | [+/-] number followed by |
Rate subject VOXYGEN
Example:
<prosody vox:rate-subject="pause"></prosody>
Value | Description |
---|---|
vox:rate-subject |
|
Say as CERENCE READSPEAKER VOXYGEN
Say-as SSML Markup is used to indicate the type of text construct contained within the element.
Multiple format values are available for each interpret-as values, but their realization is voice-dependant.
The attribute values that may have an effect on rendering depend on the current voice.
Example: Will be read as "third"
<say-as interpret-as="ordinal">3</say-as>
Attribute | Description | |
---|---|---|
format | The date format may be optionally specified via format attribute, to supersede the language defaults, e.g. | |
interpret-as | Indicates the content type of the contained text construct. | |
Value | Description | |
address CERENCE | Expand text as an address, including street names and numbers, zip codes, state names, etc. | |
boolean READSPEAKER | Reads as a boolean. | |
cardinal CERENCE | Reads as a cardinal number. | |
characters VOXYGEN READSPEAKER | Spells out letters, reads digits one by one, and expands | |
code CERENCE | Expand numbers or codes reading them digit by digit | |
currencyCERENCEREADSPEAKER | Expand text as a decimal currency including currency abbreviations. | |
date CERENCE VOXYGEN READSPEAKER | Read digits as date. | |
decimal CERENCE | Same as number but including comma/dot normalization. | |
digits CERENCEREADSPEAKER | Expand numbers or codes reading them digit by digit. | |
distance CERENCE | Expand text as a distance measurement. | |
normal CERENCE | Default text normalization | |
number CERENCE READSPEAKER | Expand cardinal/ comma formatted numbers up to 15 digits. | |
ordinal CERENCE | Reads as an ordinal number. | |
phone CERENCE READSPEAKER | Expand text as a telephone number including country codes, prefixes, tel. word indicators, etc. | |
rational CERENCE | Same as number but including comma/dot normalization. | |
real CERENCE | Same as number but including comma/dot normalization. | |
sms CERENCE | Expand text as a sms message, reading web addresses, smileys, email addresses, etc. | |
spell CERENCE | Spell out the input text that follows. | |
telephone CERENCE | Reads as a telephone number. | |
time CERENCE VOXYGEN READSPEAKER | Expand text as a clock reading (hour, minutes, am, pm), a duration or a time range. | |
zip CERENCE | Expand text as a zip code. | |
detailREADSPEAKER | An optional attribute, a value changes, depending on the interpret-as. | |
typeREADSPEAKER | A custom attribute, the interpret-as can be bypassed. it renders by defining a duration format. ( |
Sentence CERENCE READSPEAKER VOXYGEN
Sentence SSML markup is used to indicate a sentence in your text.
While the TTS engine already recognize sentences automatically, it can help it to better understand and render your text. You can place multiple sentences in a paragraph.
Example:
<p>
<s>This is the first sentence of the paragraph.</s>
<s>Here's another sentence.</s>
</p>
Attribute | Description | |
---|---|---|
xml:lang | An optional attribute specifying the language of the element. | |
onlangfailure | An optional attribute specifying the desired behavior upon language speaking failure. Not supported by READSPEAKER. | |
Value | Description | |
ignoretext | The synthesis processor will not attempt to render the text that is in the failed language. | |
ignorelang | The synthesis processor will ignore the change in language and speak as if the content were in the previous language. | |
changevoice | If a voice exists that can speak the language, the synthesis processor will switch to that voice and speak the content. Otherwise, the processor chooses another behavior (either | |
processorchoice | The synthesis processor chooses the behavior (either |
Style CERENCE
Style SSML Markup is used to set an alternative speaking style instead of the normal one.
Please note that a particular style can be incompatible with some voices.
Example:
Sorry <break time="300ms"/>
<style name="lively">sorry</style>
Not all styles are supported by all Cerence voices.
Attribute | Description |
---|---|
name | The speaking style name to use. You can check this page to get the supported values for each voice. |
Sub CERENCE READSPEAKER VOXYGEN
Sub SSML Markup is used to substitute text for the purposes of pronunciation. The sub element can contain only text (no elements).
Example:
<sub alias="Voice Development Kit">VDK</sub>
Attribute | Description |
---|---|
alias | The content that the voice synthesis will read instead of the content of the element. |
Timbre CERENCE VOXYGEN
Timbre SSML Markup is a rate/pitch warping coefficient that maintains the duration of phonemes and enables voice timbre to be modified.
It accepts predefined values as well as relative percentages numbers followed by %.
Cerence example:
<prosody timbre="+100%">
I am speaking with a different voice timber.
</prosody>
Voxygen example:
<prosody vox:timbre="+100%">
I am speaking with a different voice timber.
</prosody>
Attribute | Description | |
---|---|---|
timbreCERENCE | x-young | +35% |
x-young | +20% | |
medium | 0% | |
old | -20% | |
x-old | -35% | |
default | 0% | |
Relative percentage | [+/-] number followed by | |
vox:timbreVOXYGEN | Relative percentage | [+/-] number followed by |
Relative value | [+/-] number with no units | |
Absolute value | Multiplier of the initial timbre value for the current voice (unsigned number with no units or followed by |
Token READSPEAKER VOXYGEN
Token SSML Markup can be used to disambiguate heteronyms.
Example:
<token xml:id="myToken">VDK</token>
Attribute | Description |
---|---|
xml:lang | An optional attribute specifying the language of the element. |
role | A QName used in conjunction with lexicons. |
onlangfailure | VOXYGEN |
xml:id | VOXYGEN |
Voice CERENCE READSPEAKER VOXYGEN
Voice SSML Markup is used to change the language and voice applied to the text for rendering.
Example:
<voice xml:lang="de">Deutsch</voice>
Attribute | Description |
---|---|
name | CERENCE READSPEAKER VOXYGEN |
gender | CERENCE READSPEAKER VOXYGEN |
xml:lang | CERENCE VOXYGEN |
age | CERENCE VOXYGEN |
languages | READSPEAKER VOXYGEN |
required | VOXYGEN |
ordering | VOXYGEN |
onvoicefailure | VOXYGEN
|
variant | VOXYGEN |
Volume CERENCE READSPEAKER VOXYGEN
Volume SSML Markup is used to set the volume of the voice. It accepts predefined values as well as positive numbers.
Example:
<prosody volume="+100%">
I am speaking this at approximately twice the original signal amplitude.
</prosody>
Value | VOXYGEN | CERENCE | READSPEAKER |
---|---|---|---|
| Initial value for current voice (60) | 80 | 100 |
| 0 relative to | 0 | 0 |
| 20 relative to | 26 | 32 |
| 40 relative to | 52 | 66 |
| 60 relative to | 80 | 100 |
| 80 relative to | 90 | 200 |
| 100 relative to | 100 | 300 |
Relative percentage | [+/-] number followed by | ||
Relative value | [+/-] number with no units | ||
Absolute value | Multiplier of the initial timbre value for the current voice (unsigned number with no units or followed by |
Word CERENCE READSPEAKER VOXYGEN
Word SSML Markup can be used to express segmentation of a word.
Example:
<w>Apple</w>
Attribute | Description |
---|---|
xml:lang | An optional attribute specifying the language of the element. |
role | A QName used in conjunction with lexicons. |
onlangfailure | VOXYGEN |
xml:id | VOXYGEN |
vox:modes | VOXYGEN |