Speech Synthesis Markup Language (SSML) reference (Console)

• strength

Optional. Specifies the strength of the output’s prosodic break by relative terms.

Each strength value indicates a monotonically non-decreasing (conceptually increasing) break strength between tokens.

Strong boundaries are typically accompanied by pauses.

Valid values include:

• x-weak

• weak

• medium

• strong

• x-strong

• none

Example

Step 3, example of prosodic strength

<break strength="weak"/>

• verbatim

Configures the <say-as> tag to spell out the individual letters, numbers, and symbols of a word.

In the example below, the word would be spoken as “E D I F Y dash one”.

<say-as interpret-as="characters">Edify-1</say-as>

The <p> and <s> tags indicate paragraph and sentence elements, respectively.

The use of these tags is optional. The text-to-speech processor is capable of determining the structure of plain text that doesn’t include explicit paragraph or sentence tags.

However, these tags are useful when used in conjunction with other tags that might change prosody (like <break>, <emphasis>, or <say-as>). Providing these tags helps to explicitly instruct the system how to process the elements.

In the example below, the two <s> elements represent two sentences organized in a single paragraph <p>.

<p><s>This is sentence one.</s><s>This is sentence two.</s></p>

The <sub> tag is used to indicate that text contained in the alias attribute should replace the tagged text.

You can also use this tag to provide a simplified pronunciation for a difficult-to-read word.

<sub alias="California">CA</sub>

• pitch

Optional. The pitch attribute modifies the pitch of the contained text.

There are three ways to modify pitch:

• Specifying a relative value

  • • • • • low

          • medium (default)

          • high

• Semitones

  • • • • • Increase or decrease pitch by N semitones

          • Notation of “+Nst” or “-Nst”. Note that “+/-” and “st” are required.

• Percentage

  • • • • • Increase or decrease pitch by "N" percent by using "+N%" or "-N%" respectively.

          • Note that "%" is required but "+/-" is optional.

The <emphasis> tag provides or removes emphasis from the contained text. This functions similarly to <prosody>, but it doesn’t require any individual speech attributes.

Note: The <emphasis> tag should only be used around a full sentence. Enclosing individual words within a sentence may cause unwanted pauses in speech.

The following values are valid:

• strong

• moderate

• none

• reduced

In the example below, the sentence would have moderate emphasis applied to it when vocalized.

<emphasis level="moderate">This is an important announcement</emphasis>

The <par> tag defines parallel media elements to play simultaneously.

This tag creates a parallel media container that allows you to play multiple media elements at once. The only allowed content is a set of one or more <par>, <seq>, and <media> elements. The order of the <media> elements is not significant.

Unless a child element specifies a different begin time, the implicit begin time for the element is the same as that of the <par> container. If a child element has an offset value set for its begin or end attribute, the element's offset will be relative to the beginning time of the <par> container. 

For the root <par> element, the begin attribute is ignored and the beginning time is when SSML speech synthesis process starts generating output for the root <par> element (i.e. effectively time "zero").

In the example below, the <par> element contains two <media> elements. Each has an xml:id attribute that uniquely identifies the element. Each also has a begin attribute that defines when to start speaking the text.

In the second element, the begin time is “question.end+2.0s”, meaning that it should start speaking two seconds after the end of the media element with the id “question.”

   <par>

       <media xml:id="question" begin="0.5s">

           <speak>What is the largest land animal?</speak>

       </media>

       <media xml:id="answer" begin="question.end+2.0s">

           <speak>The largest land animal is the African elephant.</speak>

       </media>

   </par>

The <seq> tag defines sequential media that plays one after another.

The only allowed content is a set of one or more <seq>, <par>, and <media> elements. The order of the media elements is the order in which they are rendered.

The begin and end attributes of child elements can be set to offset values (see Time Specification below). Those child elements' offset values will be relative to the end of the previous element in the sequence or, in the case of the first element in the sequence, relative to the beginning of its <seq> container.

<seq>

   <media begin="0.5s">

       <speak>What is the largest land animal?</speak>

   </media>

   <media begin="1.0s">

       <speak>The largest land animal is the African elephant</speak>

   </media>

   <media begin="2.0s">

       <speak>What is the second largest land animal?</speak>

   </media>

   <media begin="3.0s">

       <speak>The Asian elephant.</speak>

   </media>

</seq>

The <media> tag represents a media layer within a <par> or <seq> element. 

The system supports <speak> elements within <media> tags.

• xml:id

Optional. A unique XML identifier for this element. Encoded entities are not supported. The allowed identifier values match the regular expression "([-_#]|\p{L}|\p{D})+". 

• begin

Optional. The beginning time for this media container. Ignored if this is the root media container element (treated the same as the default of "0"). See the Time specification section below for valid string values.

By default, this value is 0.

• end

Optional. A specification for the ending time for this media container. See the Time specification section below for valid string values.

• repeatCount

Optional. A Real Number specifying how many times to insert the media. Fractional repetitions aren't supported, so the value will be rounded to the nearest integer. Zero is not a valid value and is therefore treated as being unspecified and has the default value in that case.

By default, this value is 1.

• repeatDur

Optional. A TimeDesignation that is a limit on the duration of the inserted media. If the duration of the media is less than this value, then playback ends at that time.

• soundLevel

Optional. Adjusts the sound level of the audio by soundLevel decibels. Maximum range is +/-40dB but actual range may be effectively less, and output quality may not yield good results over the entire range.

By default, this value is +0dB.

• fadeInDur

Optional. A TimeDesignation over which the media will fade in from silent to the optionally-specified soundLevel. If the duration of the media is less than this value, the fade in will stop at the end of playback and the sound level will not reach the specified sound level.

By default, this value is 0s.

• fadeOutDur

Optional. A TimeDesignation over which the media will fade out from the optionally-specified soundLevel until it is silent. If the duration of the media is less than this value, the sound level is set to a lower value to ensure silence is reached at the end of playback.

By default, this value is 0s.

• Offset value - Time offset value is an SMIL Timecount-value that allows values that match the regular expression: "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

The first digit string is the whole part of the decimal number and the second digit string is the decimal fractional part. The default sign (i.e. "(+|-)?") is "+". The unit values correspond to hours, minutes, seconds, and milliseconds respectively. The default for the units is "s" (seconds).

• Syncbase value - A syncbase value is an SMIL syncbase-value that allows values that match the regular expression: "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

The digits and units are interpreted in the same way as an offset value.

The <phoneme> tag produces custom pronunciations of words inline. Text-to-Speech accepts the IPA and X-SAMPA phonetic alphabets. 

The example below shows how this tag is used for IPA and X-SAMPA:

<phoneme alphabet="ipa" ph="ˌmænɪˈtoʊbə">manitoba</phoneme>

<phoneme alphabet="x-sampa" ph='m@"hA:g@%ni:'>mahogany</phoneme>

<speak>And there it was <voice language="en-GB" gender="male" required="gender"

   ordering="gender language">a flying bird </voice>roaring in the skies for the

   first time.</speak>

<speak>Today is supposed to be <voice language="en-GB" gender="female"

   ordering="language gender">Sunday Funday.</voice></speak>

You can use the <lang> tag to include text in multiple languages within the same SSML request. All languages will be synthesized in the same voice unless you use the <voice> tag to explicitly change the voice. 

The xml:lang string must contain the target language in BCP-47 format. You can find the BCP-47 code for your language with the List Voices route of the API Platform. In the following example "chat" will be verbalized in French instead of the default language (English):

<speak>The french word for cat is <lang xml:lang="fr-FR">chat</lang></speak>

Text-to-Speech supports the <lang> tag on a best effort basis. Not all language combinations produce the same quality results if specified in same SSML request. In some cases, a language combination might produce an effect that is detectable but subtle or perceived as negative. Known issues:

• Japanese with Kanji characters is not supported by the <lang> tag. The input is transliterated and read as Chinese characters.

• Semitic languages such as Arabic, Hebrew, and Persian are not supported by the <lang> tag and will result in silence. If you want to use any of these languages we recommend using the <voice> tag to switch to a voice that speaks your desired language (if available).