Text-to-Speech (TTS)

Click on a section name below to jump to that section.

• Get Started with Text To Speech
• Text to Speech voices overview
• Available voices and languages
• Text to Speech settings
• Override default settings
• SSML
• Limits
• Pricing

You can provide text and Twilio will synthesize speech in real time and speak back the audio in any call or conference. TTS is available via the <Say> TwiML verb and Studio's Say/Play Widget.

The <Say> verb allows you to provide plain text that Twilio converts to synthesized speech.

For example, when Twilio executes the following TwiML during a call, the caller hears "Hello world!" The synthesized voice the caller hears is the default voice and language of the Twilio Account (configured in the Twilio Console).

1
<Response>
2
   <Say>Hello world!</Say>
3
</Response>

<Say> also allows you to modify the language, accent, and voice of the synthesized speech via the language and voice attributes. The example below uses Amazon Polly's "Joanna" voice and American English:

1
<Response>
2
   <Say language="en-US" voice="Polly.Joanna">Hello. I am Joanna and I speak American English!</Say>
3
</Response>

<Say> offers different options for voices, each with its own supported set of languages and genders, so you can customize your application with Text To Speech capabilities according to your needs and preferences.

To start using TTS, complete the following steps:

1. Configure your Account-wide Text To Speech Settings in the Twilio Console.
2. Use <Say> to programmatically define TTS instructions.

Twilio Studio is a visual, serverless tool that uses Widgets to represent various parts of Twilio's platform features and functionality to design and build applications with little or no code.

The Say/Play Widget allows you to add Text To Speech capabilities to your application with ease, including embedding SSML for supported voices.

To start using TTS with Studio, complete the following steps:

1. Configure your Account-wide Text To Speech Settings in the Twilio Console.
2. Use the Say/Play Widget to add TTS to your Studio Flow.

Twilio's Text To Speech offering has a variety of different voices in multiple languages and locales with their associated accents and pronunciations. There are three types of voices with different quality, language coverage and pricing: Basic, Standard, and Premium.

Basic voices are first-generation voices. They can be used to get started and familiarize yourself with Text To Speech capabilities using <Say>, but may not have enough human-like qualities to build conversational applications and deliver superior user experiences over a voice call. The voices in this tier are available in a limited number of languages at no cost.

Standard voices offer standard TTS technology and produce natural-sounding synthesized speech with a variety of lifelike voices. The voices in this tier are provided by Amazon (Amazon Polly) and Google (Standard), with support for SSML (Speech Synthesis Markup Language), which allows developers to control many aspects of the synthesized speech.

These voices are generated using the latest technology and innovation in synthesized speech, providing the most human-like, expressive and natural-sounding text-to-speech voices possible, with higher quality than Standard voices. The voices in this tier are provided by Amazon (Amazon Polly Neural) and Google (WaveNet, Neural2), with support for SSML, which allows developers to control many aspects of the synthesized speech.

See the Pricing section below for additional information.

The following table contains all voices available for each language and locale. You can test the different voices from the TTS Settings page in the Twilio Console.

Note: Invalid combination of voice and language attributes may result in error and <Say> instruction failure.

Voices listed with (*) are fully bilingual voices. At the moment only Amazon Polly has this capability for a limited number of voices. Learn more by visiting Amazon's Bilingual Voices documentation.

The Text To Speech page in the Twilio Console allows you to define a default voice and language for your Account. These defaults are used when no language or voice attribute is provided in your <Say> TwiML. If you are using Studio, the defaults are used when "Default" is selected.

You can test different voices and messages in this section of the Console.

Expand image

In the screenshot above, the DEFAULT PROVIDER is set to Basic and the DEFAULT VOICE is set to Man, en-US. With these TTS settings, Twilio uses the Man voice and the en-US (American English) accent and pronunciation when executing the following TwiML:

1
<Response>
2
  <Say>Hello. I am a man!</Say>
3
</Response>

On the Text to Speech page in the Console, you can set a voice for every locale. This means that you can specify the language without needing to specifying the voice when using TTS capabilities in your application.

To set a voice for a locale, complete the following:

Expand image

1. Under the Current Language Mapping heading, click on the language/locale you wish to configure, e.g. English (British)(en-GB).

2. In the Test & Configure Voices By Language modal, select the PROVIDER and VOICE you wish to use, e.g. Amazon Polly and Emma.

3. Click Save.

4. Repeat steps 1-3 for other languages/locales if necessary.

For example, if you configure English (British)(en-GB) to use Amazon Polly and Emma, Twilio uses the Amazon Polly Emma voice when executing <Say> with the language attribute set to en-GB and no voice attribute (see TwiML example below).

1
<Response>
2
  <Say language="en-GB">Hello. I am Emma!</Say>
3
</Response>

<Say>'s voice attribute allows you to override any default provider/voice settings that were configured in the Console (i.e. Account-level and Language Mapping defaults).

For example, if your Account's default TTS voice is Amazon Polly Salli but you want to use Amazon Polly Joanna for a specific call, set the voice attribute to Polly.Joanna:

1
<Response>
2
  <Say voice="Polly.Joanna">Hello. I am Joanna!</Say>
3
</Response>

You can also use the voice attribute to override a Language Mapping's defaults.

For example, if your Language Mapping for English (British)(en-GB) uses Amazon Polly and Emma but you want to use the Amazon Polly Joanna voice for a specific <Say> instruction, you would use the voice attribute set to Polly.Joanna. The TwiML below causes Twilio to use the Amazon Polly Joanna voice, which overrides your Account's default Language Mapping:

1
<Response>
2
  <Say language="en-GB" voice="Polly.Joanna">Hello. I am Joanna!</Say>
3
</Response>

<Say>'s language attribute allows you to override any default language/locale settings that were configured in the Console.

For example, if your Account's default TTS Language is English (US) (en-US), but wish to use German for a specific call, set the language attribute to de-DE in your TwiML:

1
<Response>
2
  <Say language="de-DE">Hallo. Ich spreche Deutsch!</Say>
3
</Response>

Speech Synthesis Markup Language (SSML) uses XML-based tags that allow you to fine-tune the synthesized speech generated by TTS. SSML functionality includes the ability to: specify where pauses should be, provide pronunciations for acronyms, abbreviations, dates and times, and increase or decrease the speed at which text is spoken.

While the W3C specification covers many capabilities, Twilio currently only supports a subset of them.

In addition, SSML support (including tags and accepted values) may differ between TTS providers and/or may be limited to specific voices. Review the provider-specific SSML documentation and test your application. Use of unsupported SSML tags with any TTS provider may result in error and <Say> instruction failure.

The table below lists the supported SSML tags, but you should refer to the appropriate, provider-specific documentation to ensure you're using the SSML tags correctly.

The SSML <prosody> tag allows you to control the volume, rate, and pitch of synthesized speech.

1
<Response>
2
  <Say voice="Polly.Joanna">
3
    Prosody can be used to change the way words sound. The following words are
4
    <prosody volume="x-loud"> quite a bit louder than the rest of this passage.
5
    </prosody> Each morning when I wake up, <prosody rate="x-slow">I speak slowly and
6
    deliberately until I have my coffee.</prosody> I can also change the pitch of my voice
7
    using prosody. Do you like <prosody pitch="+5%"> speech with a pitch higher,</prosody>
8
    or <prosody pitch="-10%"> is a lower pitch preferable?</prosody>
9
  </Say>
10
</Response>

The SSML <say-as> tag allows you to indicate specific categories of text, so that the synthesized speech pronounces the text correctly.

Without <say-as>, a phone number would be pronounced as a number, e.g. "four billion, one hundred fifty-five million, five hundred fifty-one thousand, two hundred twelve."

The TwiML example below uses <say-as> so that the synthesized speech reads the phone number as "four one five, five five five, one two one two."

1
<Response>
2
   <Say voice="Polly.Joanna">John's phone number is, <say-as interpret-as="telephone">4155551212</say-as></Say>
3
</Response>

You can generate TwiML with SSML within the <Say> verb using one of Twilio's helper libraries for C#, Java, Node.js, PHP, Python, Ruby, or Go.

The code sample below shows Helper Library code that generates the following SSML and TwiML:

1
<Response>
2
  <Say voice="Polly.Joanna">
3
    Hi
4
    <break strength="x-weak" time="100ms"/>
5
    <emphasis level="moderate">Words to emphasize</emphasis>
6
    <p>Words to speak</p>
7
    aaaaaa
8
    <phoneme alphabet="x-sampa" ph="pɪˈkɑːn">Words to speak</phoneme>
9
    bbbbbbb
10
    <prosody pitch="-10%" rate="85%" volume="-6dB">Words to speak</prosody>
11
    <s>Words to speak</s>
12
    <say-as interpret-as="spell-out">Words to speak</say-as>
13
    <sub alias="alias">Words to be substituted</sub>
14
    <w>Words to speak</w>
15
  </Say>
16
</Response>

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
const say = response.say({
5
    voice: 'Polly.Joanna'
6
}, 'Hi');
7
say.break({
8
    strength: 'x-weak',
9
    time: '100ms'
10
});
11
say.emphasis({
12
    level: 'moderate'
13
}, 'Words to emphasize');
14
say.p('Words to speak');
15
say.addText('aaaaaa')
16
say.phoneme({
17
    alphabet: 'x-sampa',
18
    ph: 'pɪˈkɑːn'
19
}, 'Words to speak');
20
say.addText('bbbbbbb')
21
say.prosody({
22
    pitch: '-10%',
23
    rate: '85%',
24
    volume: '-6dB'
25
}, 'Words to speak');
26
say.s('Words to speak');
27
say.sayAs({
28
    'interpret-as': 'spell-out',
29
    role: 'yyyymmdd'
30
}, 'Words to speak');
31
say.sub({
32
    alias: 'alias'
33
}, 'Words to be substituted');
34
say.w('Words to speak');
35

36
console.log(response.toString());

1
<Response>
2
  <Say voice="Polly.Joanna">
3
    Hi
4
    <break strength="x-weak" time="100ms"/>
5
    <emphasis level="moderate">Words to emphasize</emphasis>
6
    <p>Words to speak</p>
7
    aaaaaa
8
    <phoneme alphabet="x-sampa" ph="pɪˈkɑːn">Words to speak</phoneme>
9
    bbbbbbb
10
    <prosody pitch="-10%" rate="85%" volume="-6dB">Words to speak</prosody>
11
    <s>Words to speak</s>
12
    <say-as interpret-as="spell-out">Words to speak</say-as>
13
    <sub alias="alias">Words to be substituted</sub>
14
    <w>Words to speak</w>
15
  </Say>
16
</Response>

• There is a 4,000 character limit on text that <Say> can process with Basic voices (man and woman).
• Basic voices (man and woman) don't support SSML tags.
• There is a 3,000 character limit on text, non-SSML, that <Say> can process with Amazon Polly voices.
• Amazon-specific SSML tags such as <amazon:auto-breath> or <amazon:effect> among others are not currently supported.
• Lexicons are not supported in Amazon Polly voices.
• SSML support in Amazon TTS may vary between Polly and Polly Neural voices, refer to the Amazon Polly SSML documentation for detailed information
• SSML support in Google TTS may vary between Standard, WaveNet and Neural2 voices, refer to Google SSML documentation for detailed information
• There is a 5,000 character limit on text, including SSML, that <Say> can process with Google voices.
• SSML tags, newlines and spaces are included in the total character count by Google TTS hence billed.
• Google-specific SSML tags such as <par> or <seq> among others are not currently supported.

Basic voices (man and woman) are free of charge.

Standard voices (Amazon Polly and Google Standard) pricing starts at $0.0008 per 100 characters with the following volume discounts:

* Usage is rounded towards the end of call and priced in blocks of 100 characters. For example, if 546 characters are used on a call, then you're charged $0.004 for the use of Standard voices on that call. However, if less than 100 characters are used, you're charged $0.0008, even for using just one character.

Premium voices (Amazon Polly Neural, Google WaveNet and Google Neural2) price starts at $0.0032/100 characters with the following volume discounts:

* Usage is rounded towards the end of call and priced in blocks of 100 characters. For example, if 546 characters are used on a call, then you're charged $0.016 for the use of Premium voices on that call. However, if less than 100 characters are used, you're charged $0.0032, even for using just one character.