> For the complete documentation index, see [llms.txt](https://docs.borndigital.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.borndigital.ai/for-advanced-users/conversation-design-tips/customizing-speech-synthesis.md).

# Customizing speech synthesis

How the voicebot turns the Speech text into a voice, which voice providers understand SSML, and the SSML tags you can use.

The voicebot reads out the **Speech** text of your nodes – in the [Message node](/digital-agent/conversation-flow/nodes-explained/message-node.md), turn on **Split** to write the speech separately from the chat text. The text goes to the voice (text-to-speech) **Provider** you choose when you [deploy the project](/digital-agent/workspace/deploy-project.md#voice).

You can improve how the text sounds in two ways:

* **Write for the ear** – word order, punctuation and spelling have the biggest effect on every provider. See [Writing for voice](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/writing-for-voice.md).
* **Use SSML tags** – pauses, speed, pitch and pronunciation, for the providers that support them (see below).

More in this section:

* [Writing for voice](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/writing-for-voice.md) – sentence structure, questions and their wording.
* [Intonation and pauses](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/intonation-and-pauses.md) – the melody of the sentence and the length of pauses.
* [Numbers, dates and pronunciation](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/numbers-dates-and-pronunciation.md) – how Azure voices read numbers, phone numbers, dates and times in Czech, Slovak, English and Polish.
* [Variables in speech](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/variables-in-speech.md) – values that are known only during the conversation.

## Which providers understand SSML

SSML (Speech Synthesis Markup Language) is a set of XML tags that control pauses, prosody and pronunciation. The platform passes the Speech text to the provider unchanged, so whether a tag works depends on the provider:

| Voice provider                                      | SSML in the Speech text                                                                                               |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Azure**                                           | Yes. Studio wraps your text in `<speak>`, `<voice>` and `<prosody>` with the voice, rate and pitch of the deployment. |
| **Google**                                          | Yes. Studio wraps your text in `<speak>` and splits it into sentences.                                                |
| **ElevenLabs**, **OpenAI**, **Cartesia**, **Piper** | No – the text is sent as plain text. Control pauses and pronunciation with punctuation and spelling.                  |
| **Azure Voice Live**                                | No – the text is sent as plain text; voice, rate and pitch are set in the deployment.                                 |

Which providers you can choose depends on your environment.

{% hint style="warning" %}

* Write only the inner tags – never your own `<speak>` or `<voice>` element; Studio adds them.
* [Realtime agents](/realtime-agent/introduction.md) speak with the voice of the realtime model and do not use SSML.
* If you change the provider of a project, check the Speech texts: tags that Azure or Google understood mean nothing to the others.
  {% endhint %}

When Studio checks the flow, it also checks the tags: `<prosody>`, `<phoneme>`, `<sub>` and `<say-as>` must have a closing tag and must not overlap, `<prosody>` must not be placed inside another tag, and attribute values must be in quotes.

## SSML tags

There are two kinds of tags:

* **Pair tags** surround the text they change: `<prosody rate="slow">This sentence is slower.</prosody>`
* **Self-closing tags** stand alone and end with `/>`: `Hello,<break time="500ms"/>how are you?`

Attributes are written inside the tag, in quotes: `<prosody pitch="+10%" rate="90%">`.

{% tabs %}
{% tab title="<break>" %}
Inserts a pause.

| Example                      | Meaning                                                              |
| ---------------------------- | -------------------------------------------------------------------- |
| `<break time="500ms"/>`      | A pause of 500 milliseconds.                                         |
| `<break time="2s"/>`         | A pause of 2 seconds.                                                |
| `<break strength="strong"/>` | A pause of a given strength: x-weak, weak, medium, strong, x-strong. |

A full stop already makes a pause of about 200–300 ms. To make it shorter, **replace** the full stop with a break – a break after the full stop makes the pause longer. See [Intonation and pauses](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/intonation-and-pauses.md).
{% endtab %}

{% tab title="<prosody>" %}
Changes the speed, pitch or volume of the text inside.

| Example                                                         | Meaning                                                    |
| --------------------------------------------------------------- | ---------------------------------------------------------- |
| `<prosody rate="+5%">…</prosody>`                               | 5 % faster. Also x-slow, slow, medium, fast, x-fast.       |
| `<prosody pitch="+5%">…</prosody>`                              | 5 % higher. Also x-low, low, medium, high, x-high.         |
| `<prosody volume="soft">…</prosody>`                            | Softer. Also x-soft, medium, loud, x-loud or a percentage. |
| `<prosody contour="(0%,+10%)(50%,+50%)(100%,+10%)">…</prosody>` | The pitch curve of the sentence (Azure).                   |

With Azure, your `<prosody>` works inside the rate and pitch set in the deployment.
{% endtab %}

{% tab title="<say-as>" %}
Tells the voice how to read a value.

| Example                                                         | Meaning                             |
| --------------------------------------------------------------- | ----------------------------------- |
| `<say-as interpret-as="digits">1234</say-as>`                   | Digit by digit: one two three four. |
| `<say-as interpret-as="spell" format="undefined">AB12</say-as>` | Character by character.             |
| `<say-as interpret-as="date" format="dm">1/11</say-as>`         | A date, here day and month.         |
| `<say-as interpret-as="telephone">…</say-as>`                   | A phone number.                     |

Support of the formats differs by language and voice – see [Numbers, dates and pronunciation](/for-advanced-users/conversation-design-tips/customizing-speech-synthesis/numbers-dates-and-pronunciation.md).
{% endtab %}

{% tab title="<phoneme>" %}
Sets the exact pronunciation in a phonetic alphabet.

`<phoneme alphabet="ipa" ph="bɔːrn ˈdɪdʒɪtəl">Born Digital</phoneme>`
{% endtab %}

{% tab title="<sub>" %}
Reads an alias instead of the written text.

`<sub alias="Born Digital">BD</sub>` is read as *Born Digital*.
{% endtab %}

{% tab title="<emphasis>" %}
Stresses a word or phrase: `<emphasis level="strong">today</emphasis>`. Levels: reduced, moderate, strong. Not every voice supports it.
{% endtab %}
{% endtabs %}

Example of a Speech text for an Azure or Google voice:

```
Hey there!<break time="300ms"/><prosody rate="-10%">I'm the virtual assistant of Born Digital.</prosody> How can I help you today?
```

## Tools that prepare text for speech

Some [tools](/digital-agent/tools-reference.md) turn a value into a form that reads well – on every provider, because they change the text itself:

* `pronounce_number` – digits separated by commas, for slow reading of numbers,
* `spell_out` – a string character by character,
* `to_readable_date` – a date in words (Czech and Slovak),
* `pronounce_job` – the phonetic pronunciation of a job name (Czech).

{% hint style="success" %}
For Azure voices, the [Audio Content Creation](https://speech.microsoft.com/audiocontentcreation) tool in Azure Speech Studio lets you try SSML, pauses and intonation and listen to the result before you put the text into Studio.
{% endhint %}