Разметка синтеза речи SSML

Обновлено 20 апреля 2023

Использовать речевые технологии можно отдельно от инструментария Studio. Подробнее об этом в разделе SaluteSpeech.

SSML (Speech Synthesis Markup Language) — язык разметки синтеза речи. Позволяет разработчикам настраивать преобразование текста в речь и делает речь ассистентов более естественной и выразительной.

SSML базируется на спецификации от W3C.

Поддерживаемые теги:

Добавление паузы в текст — тег break.
Замена текста на более привычный — тег sub.
Вставка звуковых эффектов — тег audio.
Добавление фонового звука — тег extra.background-audio.
Правильное произнесение аббревиатур и фраз – тег say-as.
Изменение настроения и настройка шепота тег voice.
Управление тоном, интонацией, скоростью и громкостью – тег paint.
Полное произнесение года — тег extra.fulldate.

Также для синтезируемого текста внутри SSML-разметки поддерживаются различные символы. Подробнее в разделе Символы и междометия.

Если при использовании тегов SSML вы получили ошибку, проверьте корректность написания тегов в любом онлайн-валидаторе XML-файлов.

Описание тегов

Тег break

Тег используется для расстановки пауз в тексте. Тег используется с атрибутами:

time — продолжительность паузы в виде числа. Вместе с временным значением паузы указываются единицы измерения без пробелов в миллисекундах (ms) или секундах (s).
strength — продолжительность паузы в виде строки. Может принимать значения:
- x-weak;
- weak;
- medium;
- strong;
- x-strong (длительность совпадает со strong).

Атрибут time имеет приоритет перед атрибутом strength.

Если вы не укажете атрибуты, то тег по умолчанию получит значение strength="medium".

Пример:

    <speak>
    Привет!
    <break time="200ms" />
    Как прошёл день?
    <break strength="weak" />
    Всё хорошо?
    </speak>

Тег sub

Тег используется, чтобы исправить произношение на более привычное.

<sub alias="TEXT">REPLACED_TEXT</sub> , где:

TEXT — текст для генерации.
REPLACED_TEXT — заменяемый текст.

Пример:

<speak>Дни и ночи у <sub alias= "мартэновских">мартеновских</sub> печей</speak>

Тег audio

Тег предназначен только для использования в смартапах и пока не работает с API синтеза речи.

Есть несколько вариантов использования тега audio.

Добавление звуковых эффектов из Библиотеки звуков.
Синтез текста с предзаписанным междометием.

Чтобы добавить во фразу звук или предзаписанное междометие, используйте атрибуты:

text — в качестве значения добавьте наименование звука из Библиотеки звуков или междометие.
volume — укажите громкость добавляемого эффекта или междометия.

Пример:

<speak>приветствуем<audio text="sm-sounds-human-cheer-1" volume="0.5"/></speak>
<speak><audio text="sm-sounds-human-cheer-2"/>добро пожаловать</speak>

Также вы можете добавить текст, который синтезируется вместо звука или междометия, на случай их отсутствия в базе.

Например, «да» вместо междометия «угу» или «отлично» вместо междометия «ура!»:

<speak><audio text="угу">да</audio>соглашусь</speak>
<speak>вышел новый фильм<audio text="ура!">отлично</audio></speak>

У каждого ассистента есть свой набор междометий с несколькими вариантами произношения. Самые распространенные и популярные междометия имеют более 10 вариантов. Каждый раз при использовании таких междометий и восклицаний вариант произношения выбирается случайным образом. Такой способ делает речь ассистента более живой и эмоциональной.

Пример:

    <speak><audio text="кхм-кхм"/> Какая сегодня погода?</speak>
    <speak><audio text="ааааа!"/> Что узнать?</speak>
    <speak><audio text="кхм-кхм"/> Про погоду хочу послушать</speak>
    <speak><audio text="ааааа!"/> Сегодня солнышко</speak>

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

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

Тег extra.background-audio

Тег позволяет добавить фоновый звук в синтезированную речь. Список фоновых звуков смотрите в Библиотеки звуков.

<speak><extra.background-audio src="sm-sounds-nature-rain-2">Ну и погодка! Добрый хозяин собаку из дома не выгонит </extra.background-audio></speak>

Не размещайте внутри тега extra.background-audio такой же тег или тег audio.

У тега есть несколько атрибутов:

fade in — усиление. Плавное увеличение громкости звука. Укажите, через сколько секунд после начала воспроизведения фоновый звук должен набрать максимальную громкость. Например: fade_in="1.0".
fade out — затухание. Плавное уменьшение громкости звука. Укажите, за сколько до конца аудио фоновый звук должен начать затихать. Например: fade_out="2.0".
volume — регулировка громкости аудио. Может принимать значения от 0 до 2, где 0 — тишина, 1 — нормальная громкость звука, а 2 — удвоенная громкость. Например: volume="0.5".
loop — зацикливание звука. Используйте, если синтезированная речь длится дольше фонового звука — тогда фон будет воспроизводиться по кругу, снова и снова. Атрибут может принимать следующие значения:
- none — отсутствие зацикливания.
- join — зацикливание «встык». Фоновый звук снова начинает воспроизводиться сразу после окончания предыдущего фрагмента.
- crossfade — плавная склейка. В последнюю секунду фонового звука включается затухание и начинает звучать следующий фрагмент, у которого настроено плавное усиление в течение первой секунды.

<speak><extra.background-audio loop="crossfade" fade_out="2.0" src="sm-sounds-human-walking-dead-1">О, нет, это зомби! Они идут сюда. Надеюсь, они нас не найдут. На самом деле, это всё нужно только для того, чтобы услышать зацикленный кроссфэйд. Потому что звук зомби длится всего 4 секунды. В конце звук плавно затихает.</extra.background-audio> <extra.background-audio loop="crossfade" volume="0.5" fade_out="1.0" src="sm-sounds-human-walking-dead-1">Кстати, зомби могут реветь и потише.</extra.background-audio></speak>

Тег say-as

Тег <say-as> включает в себя атрибут interpret-as. Значение этого атрибута определяет дальнейшее произнесение синтезируемого текста.

Значение атрибута interpret-as тега say-as	Пример	Описание
cardinal	`<speak><say-as interpret-as="cardinal" format="feminine_nominative">1</say-as> пачка</speak>`	Произнесение количественного числительного
ordinal	`<speak><say-as interpret-as="ordinal" format="feminine_nominative">1</say-as> пачка</speak>`	Произнесение порядкового числительного
spell-out	`<speak><say-as interpret-as="spell-out">МКС</say-as></speak>`	Произнесение аббревиатур более привычным способом
telephone	`<speak><say-as interpret-as="telephone" detail="VAL_VAL">+7 (909) 2282424</say-as></speak>`	Произнесение номера мобильного телефона
money	`<speak><say-as interpret-as="money" detail="USD">21</say-as></speak>`	Произнесение денежной суммы
date	`<speak><say-as interpret-as="date" detail="d.m.y">25.01.2000</say-as></speak>`	Произнесение даты

Cardinal и ordinal

Значения cardinal и ordinal атрибута interpret-as отвечают за произнесение порядкового и количественного числительных соответственно.

<say-as interpret-as="VALUE" format="GENDER_CASE"></say-as>

Строковый параметр VALUE принимает следующие значения:

cardinal — порядковое числительное;
ordinal — количественное числительное.

Значения атрибута format определяют, какой род и падеж использовать для синтезирования текста. Строковый параметр GENDER принимает следующие значения:

masculine — мужской род;
feminine — женский род;
neuter — средний род;
plural — множественное число.

Строковый параметр CASE принимает следующие значения:

nominative — именительный;
genitive — родительный;
dative — дательный;
accusative — винительный для одушевленных;
accusative_dead — винительный для неодушевленных;
ablative — творительный;
prepositional — предложный.

По умолчанию атрибут format принимает значения GENDER = masculine и CASE = nominative. Также атрибут format можно указывать в формате CASE_GENDER или GENDER_CASE.

В качестве значений тега <say-as> можно использовать отрицательные числа и начинать числа с нуля. Для обоих видов числительных поддерживаются числа не выше миллиардов. Если для cardinal указать число больше, в ответе будет количество миллиардов. Например: 1 000 000 000 000 — «тысяча миллиардов». Если для ordinal указать больше, то в ответ придет ошибка.

Пример произношения числа 1 в женском роде родительном падеже — «одной»:

    <speak><say-as interpret-as="cardinal" format="feminine_genitive">1</say-as></speak>

Spell-out

Значение spell-out атрибута interpret-as отвечает за правильное произнесение аббревиатур. Вместе с этим значением не используются дополнительные параметры. Аббревиатура пишется в теге say-as и указывается значение атрибута interpret-as="spell-out".

<speak><say-as interpret-as="spell-out">МКС</say-as></speak>

Telephone

Значение telephone атрибута interpret-as отвечает за произнесение номеров телефонов.

    <speak><say-as interpret-as="telephone" detail="VAL_VAL">+7 (909) 2282424</say-as></speak>

Группировка цифр

Если есть код страны, его можно указать в формате +7, 7 или 8.

Вы можете указать номер телефона без разделителей, система сгруппирует цифры самостоятельно, например:

+79651873118 — XX-XXX-XXX-XX-XX;
89651873118 — X-XXX-XXX-XX-XX;
9651873118 — XXX-XXX-XX-XX.

Для указания кода оператора или кода города можно, но необязательно, использовать скобки. Код будет сгруппирован в следующем формате:

(123) — XXX;
(1234) — XX-XX;
(12345) — XXX-XX;
(123456) — XX-XX-XX;
(1234567) — XXX-XX-XX.

Если код города не указан, будет обработан только номер.

В примерах произнесения номера телефона дефис играет роль паузы, а X - роль цифры.

Если указать дефисы между группами цифр номера, то он будет произнесен по группам цифр между дефисом. Нельзя делать группы более трех цифр, иначе синтез закончится ошибкой. При использовании разделителя можно указывать номер любого формата. Также можно использовать скобки в написании номера и знак + в начале номера.

Настройка пауз

С помощью атрибута detail="phone_pause:VALUEms" можно настроить паузу между группами цифр, где VALUE — число в формате integer, указывающее паузу в миллисекундах.

Пример:

    <speak><say-as interpret-as="telephone" detail="phone_pause:400ms">+7 (999) 123-45-67</say-as></speak>

В этом примере пауза в 400ms расставлена следующим образом:

+7 pause 999 pause 123 pause 45 pause 67.

Произношение слова «ровно» для круглого числа

С помощью атрибута detail="use-round-word" ассистент может произносить слово «ровно», если в номере есть круглое трехзначное число в шаблоне XXX-XX-XX.

Пример:

    <speak><say-as interpret-as="telephone" detail="use-round-word">+7 (800) 500-45-60</say-as></speak>

Результат: плюс семь восемьсот пятьсот ровно сорок пять шестьдесят.

Также в атрибуте detail можно одновременно указывать паузу и использование слова «ровно» через знак _.

Пример:

    <speak><say-as interpret-as="telephone" detail="use-round-word_phone_pause:400ms">+7 (800) 500-45-60</say-as></speak>

Money

Значение money атрибута interpret-as отвечает за произнесение денежных сумм в заданной валюте.

<say-as interpret-as="money" format="CASE" detail="CURRENCY_short-form_say-null-cents">VALUE</say-as>

Атрибут format имеет строковый параметр CASE с указанием падежа:

nominative — именительный;
genitive — родительный;
dative — дательный;
accusative — винительный;
ablative — творительный;
prepositional — предложный.

Параметры в атрибуте detail необходимо указывать через знак _.

Строковый параметр CURRENCY указывает валюту (по умолчанию используется рубль). Доступные варианты:

RUB — рубль;
USD — доллар США;
EUR — евро;
GBP — фунт стерлинг;
CAD — канадский доллар;
CHF — швейцарский франк;
SEK — шведская крона;
DKK — датская крона;
NOK — норвежская крона;
JPY — японская йена;
CNY — китайский юань;
PLN — польский злотый.

Можно дополнить произнесение денежных сумм следующими вариантами:

full-form — полные формы названий валют. Например, «японская йена».
short-form — короткие формы названий валют. Например, «доллар» вместо «доллар США».
say-null-cents — «центы» будут произнесены в любом случае, даже если их ноль. Например, «десять долларов, ноль центов».

Примеры:

    <speak><say-as interpret-as="money" format="genitive" detail="say-null-cents">10</say-as></speak>

Результат: десяти рублей, ноля копеек.

    <speak><say-as interpret-as="money" detail="USD">21</say-as></speak>

Результат: Двадцать один доллар США.

    <speak><say-as interpret-as="money" detail="USD_short-form">21,15</say-as></speak>

Результат: Двадцать один доллар, пятнадцать центов.

Date

Значение date атрибута interpret-as отвечает за произнесение дат.

<say-as interpret-as="date" format="CASE" detail="TEMPLATE">VALUE</say-as>

Атрибут format имеет строковый параметр CASE с указанием падежа:

nominative — именительный;
genitive — родительный;
dative — дательный;
accusative — винительный для одушевленных;
accusative_dead — винительный для неодушевленных;
ablative — творительный;
prepositional — предложный.

Параметр TEMPLATE атрибута detail задает порядок, в котором указаны число, месяц и год. Можно указать только два или только одну часть, например, число и месяц без года или только год. Допускаются только символы, указанные ниже, которые должны иметь любой из разделителей: ., - или /.

d — шаблон для числа месяца;
m — шаблон для месяца;
y — шаблон для года;
yw (вместо y) — в этом случае будет опущено слово год («двухтысячный» вместо «двух тысячный год»).

Дата VALUE представляет собой числа с одним из разделителей: ., - или /. Порядок и наличие числа, месяца и года должен соответствовать TEMPLATE. Если TEMPLATE не указан, используется по умолчанию формат даты d.m.y. День и месяц даты можно указывать одной или двумя цифрами. Год можно указывать от одной до четырех цифр.

Примеры:

    <speak><say-as interpret-as="date" detail="d.m.y">25.01.2000</say-as></speak>

Результат: Двадцать пятое января двухтысячного года.

    <speak><say-as interpret-as="date" detail="m.yw">01.2000</say-as></speak>

Результат: Январь двухтысячного.

    <speak><say-as interpret-as="date" format="accusative" detail="y">2000</say-as></speak>

Результат: Двухтысячный год.

Тег voice

Тег предназначен только для использования в смартапах и пока не работает с API синтеза речи.

Используйте тег с атрибутом mode, чтобы придать речи настроение или произнести фразу шепотом.

Может принимать значения:

whisper,
sad,
annoyed,
happy.

<speak><voice mode="whisper">мама спит, она устала, ну и я играть не стала</voice></speak>

Тег paint

Тег используется для указания характеристик, с которыми нужно прочитать текст.

Атрибуты тега

У тега есть несколько атрибутов:

Атрибут	Пример	Описание
pitch	`<speak><paint pitch="value">текст</paint></speak>`	Управление тоном голоса
slope	`<speak><paint slope="value">текст</paint></speak>`	Управление интонацией: нисходящая, ровная, восходящая
speed	`<speak><paint speed="value">текст</paint></speak>`	Управление скоростью
loudness	`<speak><paint loudness="value">текст</paint></speak>`	Управление громкостью

Value может быть цифрой от 1 до 5 или принимать значение default. Кроме того, вы можете использовать значения x-low, low, medium, high и x-high.

Вложенные теги

Поддерживаются вложенные и множественные теги, например:

<speak>
    <paint pitch="5" speed="4">высоко и быстро,
        <paint loudness="5">а еще и громко</paint>
    </paint>
</speak>

Расстановка акцентов

Тегом можно выделять отдельные слова, фрагмент текста или весь текст целиком.

Вы можете использовать тег paint для расстановки акцентов в вопросах. Например, в вопросе «Любишь песиков?» сервис по умолчанию сделает акцент на «любишь».

Чтобы изменить это, используйте стандартный паттерн: <paint pitch="5" slope="5" loudness="4">. Например:

<speak>любишь <paint pitch="5" slope="5" loudness="4">пёсиков?</paint></speak>

Предложение звучит не очень естественно, потому что остался акцент на слове «любишь». Это можно исправить, если сделать интонацию более нейтральной:

<speak><paint pitch="3" slope="1">любишь</paint> <paint pitch="5" slope="5" loudness="4">пёсиков?</paint></speak>

В утвердительных предложениях тег paint поможет сделать речь ассистента более живой и естественной, повысить интонацию для важных слов или, наоборот, сделать некоторые слова более нейтральными. Например:

<speak>я <paint pitch="5" loudness="5" speed="1">рада</paint> приветствовать <paint slope="4" pitch="4" speed="2">уважаемых</paint> гостей на этой <paint pitch="4" slope="3" speed="2">встрече</paint></speak>

Тег extra.fulldate

Тег используется, чтобы год в дате произносился полностью — дата формата DD.MM.YY преобразуется в формат DD.MM.20YY.

Нельзя использовать с другими тегами

Пример:

<speak><extra.fulldate>Следующие президентские выборы в России ожидаются 17.03.24</extra.fulldate></speak>

Результат: Следующие президентские выборы в России ожидаются семнадцатого марта две тысячи двадцать четвертого года.

Выделение слова

Чтобы с помощью интонации выделить конкретное слово в речи ассистента, используйте символ *. Звездочка ставится вплотную к слову.

Пример с выделением слова «большая»:

    <speak>Сахара — самая *большая пустыня</speak>

Пример без выделения всех слов:

    <speak>Сахара — самая большая пустыня</speak>

Обработка букв е и ё

По умолчанию речь ассистента синтезируется с учетом контекста. Слова с буквой «ё» ассистент произносит правильно независимо от того, как они написаны. Например, слово «елка» будет звучать правильно, даже если буква «ё» не указана.

Для принудительного использования «ё» просто пишите ее там, где она нужна. Если в слове буква «е» произносится ошибочно как «ё», тогда поставьте ударение в слове на ударный слог с буквой «е», используя апостроф — '. Обратите внимание, что апостроф ставится после ударной буквы.

Пример с ударением:

<speak>бере'т</speak>

Пример без ударения:

<speak>берет</speak>

Разметка синтеза речи SSML

Описание тегов﻿

Тег break﻿

Тег sub﻿

Тег audio﻿

Тег extra.background-audio﻿

Тег say-as﻿

Cardinal и ordinal﻿

Spell-out﻿

Telephone﻿

Money﻿

Date﻿

Тег voice﻿

Тег paint﻿

Атрибуты тега﻿

Вложенные теги﻿

Расстановка акцентов﻿

Тег extra.fulldate﻿

Выделение слова﻿

Обработка букв е и ё﻿

Описание тегов

Тег break

Тег sub

Тег audio

Тег extra.background-audio

Тег say-as

Cardinal и ordinal

Spell-out

Telephone

Money

Date

Тег voice

Тег paint

Атрибуты тега

Вложенные теги

Расстановка акцентов

Тег extra.fulldate

Выделение слова

Обработка букв е и ё