[Документация Yandex Cloud](../../../index.md) > [speechkit](../../index.md) > [Синтез речи](../index.md) > [Разметка текста](index.md) > Разметка SSML

# Разметка SSML


{% note warning %}

Функциональность доступна только в [регионе Россия](../../../overview/concepts/region.md).

{% endnote %}


Использование Speech Synthesis Markup Language (SSML) дает вам возможность контролировать, как SpeechKit синтезирует речь из текста.

{% note info %}

Сервис SpeechKit предназначен для синтеза естественной речи. Разметка данных для синтеза помогает настроить произношение отдельных слов, фраз и предложений, но не предназначена для генерации отдельных звуков и тишины.

Разметка в тексте будет служить подсказкой для синтеза, а не непосредственным указанием к действию.

{% endnote %}

Поддержка SSML доступна только при использовании [API v1](../request.md).

Чтобы передать текст в формате SSML, используйте параметр `ssml` в теле запроса, а сам текст оберните в тег `<speak>`:

```xml
<speak>
  Вот несколько примеров использования SSML.
  Вы можете добавить в текст паузу любой длины:<break time="2s"/> та-дааам!
  Или разметить текст на параграфы и предложения. Паузы между параграфами длиннее.
  <p><s>Первое предложение</s><s>Второе предложение</s></p>
  А еще вы можете подменять фразы.
  Например, чтобы произносить аббревиатуры и <sub alias="тому подобное">т.п.</sub>
</speak>
```

[Пример отправки запроса](../request.md#ssml).

## Поддерживаемые теги SSML {#supported-SSML-tags}

На данный момент SpeechKit поддерживает следующие теги SSML:

| Описание                                           | Тег         |
|----------------------------------------------------|-------------|
| [Добавить паузу](#break)                           | `<break>`   |
| [Добавить паузу между параграфами](#p)             | `<p>`       |
| [Использовать фонетическое произношение](#phoneme) | `<phoneme>` |
| [Корневой тег для текста в формате SSML](#speak)   | `<speak>`   |
| [Добавить паузу между предложениями](#s)           | `<s>`       |
| [Произношение аббревиатур](#sub)                   | `<sub>`     |

### break {#break}

Используйте тег `<break>`, чтобы добавить в речь паузу заданной длительности. Длительность указывается с помощью атрибутов `strength` и `time`. Если эти атрибуты не заданы, то по умолчанию используется `strength="medium"`.

Атрибут | Описание
----- | -----
`strength` | Длительность паузы, зависит от контекста. Допустимые значения:<br>* `weak` —  короткая пауза до 250 миллисекунд.<br>* `medium` — средняя пауза до 400 миллисекунд.<br>* `strong` — соответствует паузе после точки или [предложения](#s).<br>* `x-strong` — соответствует паузе после [параграфа](#p).<br>* `none` или `x-weak` — эти значения не добавляют паузу, а оставлены для совместимости с AWS API.
`time` | Длительность паузы в секундах или миллисекундах, например `2s` или `400ms`. Максимальная длительность паузы — 5 секунд.<br>При синтезе паузы указанной длительности может быть погрешность 100-200 миллисекунд.

```xml
<speak>Эй, секундочку<break time="1s"/> Что вы делаете?</speak>
```

Тег `<break>` добавляет паузу, даже если он идет после других элементов, добавляющих паузу, например после точки или запятой.

### p {#p}

Используйте тег `<p>`, чтобы добавить паузу между абзацами. Пауза добавляется после закрывающего тега.

Пауза после абзаца больше, чем пауза после [предложения](#s) или точки. Длительность паузы зависит от выбранного голоса, эмоциональной окраски, скорости и языка.

```xml
<speak>
  <p>Палач доказывал, что нельзя отрубить голову, у которой нет туловища, значит казнь не может состояться.</p>
  <p>Король доказывал, что все, имеющее голову, может быть обезглавлено, и что палач говорит пустяки.</p>
  <p>Королева тем временем вопила, что если кот не будет немедленно казнен, то казнены будут все присутствующие (замечание это удручающе подействовало на всех участников игры).</p>
</speak>
```

Все паузы внутри тега тоже учитываются. Например, на месте точки добавится дополнительная пауза, даже если она стоит перед закрывающим тегом.

### phoneme {#phoneme}

Используйте тег `<phoneme>`, чтобы контролировать правильность произношения с помощью фонем. Для воспроизведения будет использован текст, указанный в атрибуте `ph`. В атрибуте `alphabet` укажите используемый стандарт: `ipa` или `x-sampa`.

* Международный фонетический алфавит ([IPA](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet))

  ```xml
  <speak>
        В разных регионах России по-разному произносят букву
        <phoneme alphabet="ipa" ph="o">О</phoneme> в словах.
        Где-то говорят <phoneme alphabet="ipa" ph="məlɐko">молоко</phoneme>,
        а где-то <phoneme alphabet="ipa" ph="mələko">молоко</phoneme>.
  </speak>
  ```

* Extended Speech Assessment Methods Phonetic Alphabet ([X-SAMPA](https://en.wikipedia.org/wiki/X-SAMPA))

  ```xml
  <speak>
        В разных регионах России по-разному произносят букву
        <phoneme alphabet="x-sampa" ph="o">О</phoneme> в словах.
        Где-то говорят <phoneme alphabet="x-sampa" ph="m@l6ko">молоко</phoneme>,
        а где-то <phoneme alphabet="x-sampa" ph="m@l@ko">молоко</phoneme>.
  </speak>
  ```

[Список поддерживаемых фонем](ssml-supported-phonemes.md).

### speak {#speak}

Тег `<speak>` — это корневой тег. Весь текст должен быть внутри этого тега.

```xml
<speak>Мой текст в формате SSML.</speak>
```

### s {#s}

Используйте тег `<s>`, чтобы добавить паузу между предложениями. Пауза после предложения равна паузе после точки. Длительность паузы зависит от выбранного голоса, эмоциональной окраски, скорости и языка.

```xml
<speak>
  <s>Первое предложение</s>
  <s>Второе предложение</s>
</speak>
```

Все паузы внутри тега тоже учитываются. Например на месте точки добавится дополнительная пауза, даже если она стоит перед закрывающим тегом.

### sub {#sub}

Используйте тег `<sub>`, чтобы подменить текст на другой текст при произношении. Например, чтобы правильно произнести аббревиатуру или название химического элемента.

```xml
<speak>
  Мой любимый химический элемент — <sub alias="ртуть">Hg</sub>, потому что блестит.
</speak>
```

## Примеры использования {#examples}

* [Синтез речи из текста в формате SSML с помощью API v1](../api/tts-ssml.md)