SSML语音合成标记语言详解

SSML（Speech Synthesis Markup Language）语音合成标记语言，提供有关暂停以及首字母缩写词、日期、时间、缩写或应予以屏蔽的文本的音频格式等详细信息，以在音频响应中实现更多自定义功能。

<speak>Here are <say-as interpret-as="characters">SSML</say-as> samples.I can pause <break time="3s"/>.I can play a sound<audio src="https://www.example.com/MY_MP3_FILE.mp3">didn't get your MP3 audio file</audio>.I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line.Or I can even speak in digits. The digits for ten are <say-as interpret-as="characters">10</say-as>.I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>.Finally, I can speak a paragraph with two sentences.<p><s>This is sentence one.</s><s>This is sentence two.</s></p>
</speak>

预留字符

避免在要转换为音频的文本中使用 SSML 保留字符。如果需要使用 SSML 预留字符，请使用字符的转义代码防止将字符作为代码读取。下表显示了预留的 SSML 字符及其关联的转义代码。

字符	转义码
”	`"`
&	`&`
’	`'`
<	`<`
>	`>`

SSML根元素

what you want to speak content

空元素:(属性：time毫秒为单位设置中断时长，strength:用相对概念设置输出韵律中断的强度。有效值包括“极弱”、“弱”、“中等”、“强”和“极强”。值“无”表示不应输出韵律中断边界，这可用于防止处理器以其他方式产生韵律中断。其他值表示标记之间存在单调非递减（概念上增加）的中断强度。较强的边界通常伴随着停顿。)

<speak>Step 1, take a deep breath. <break time="200ms"/>Step 2, exhale.Step 3, take a deep breath again. <break strength="weak"/>Step 4, exhale.
</speak>

`<say‑as>`

借助此元素，您可以指明元素中包含的文本构造类型的相关信息。它也有助于指定呈现所含文本的详细程度。

<say‑as> 元素具有必要属性 interpret-as，它决定值的读出方式。可以根据特定的 interpret-as 值选用属性 format 和 detail。

示例

interpret-as 属性支持以下值：

```
currency
```
以下示例读作“forty two dollars and one cents”。如果省略语言属性，则会使用当前语言区域。
```
<speak><say-as interpret-as='currency' language='en-US'>$42.01</say-as>
</speak>
```
```
telephone
```
请参阅 W3C SSML 1.0 say-as 属性值 WG 注释中的 interpret-as='telephone' 说明。

以下示例读作“one eight zero zero two zero two one two one two”。如果省略“google:style”属性，则会将数字零读作字母 O。

“google:style=‘zero-as-zero’”属性目前仅适用于 EN 语言区域。
```
 <speak><say-as interpret-as='telephone' google:style='zero-as-zero'>1800-202-1212</say-as></speak>
```

verbatim

或

spell-out

以下示例会逐个读出字母：

<speak><say-as interpret-as="verbatim">abcdefg</say-as>
</speak>

```
date
```
format 属性是一系列日期字段字符代码。format 支持的字段字符代码包括 {y、m、d}，分别代表年、月、日（日期）。如果该字段代码针对年、月或日显示一次，则预期的年月日位数分别为 4、2 和 2。如果该字段代码重复出现，则预期位数是代码重复的次数。日期文本中的字段可用标点符号和/或空格分隔。

detail 属性控制日期的口语形式。对于 detail='1'，只需说出日期字段和月或年字段之一，尽管两者都可能提供。这是没有给出所有三个字段时的默认值。口语形式为“The {ordinal day} of {month}, {year}”。

以下示例读作“The tenth of September, nineteen sixty”：
```
<speak><say-as interpret-as="date" format="yyyymmdd" detail="1">1960-09-10</say-as>
</speak>
```
以下示例读作“The tenth of September”：
```
<speak><say-as interpret-as="date" format="dm">10-9</say-as>
</speak>
```
对于 detail='2'，日、月和年字段均为必需，这是所有三个字段都提供时的默认值。口语形式为“{month} {ordinal day}, {year}”。

以下示例读作“September tenth, nineteen sixty”：
```
<speak><say-as interpret-as="date" format="dmy" detail="2">10-9-1960</say-as>
</speak>
```
以下示例读作“C A N”：
```
<speak><say-as interpret-as="characters">can</say-as>
</speak>
```
以下示例读作“Twelve thousand three hundred forty five”（美式英语）或“Twelve thousand three hundred and forty five”（英式英语）：
```
<speak><say-as interpret-as="cardinal">12345</say-as>
</speak>
```
以下示例读作“First”：
```
<speak><say-as interpret-as="ordinal">1</say-as>
</speak>
```
以下示例读作“five and a half”：
```
<speak><say-as interpret-as="fraction">5+1/2</say-as>
</speak>
```
```
bleep
```
以下示例发出哔哔声，就像已经被屏蔽了：
```
<speak><say-as interpret-as="expletive">censor this</say-as>
</speak>
```
根据数字将单位转换为单数或复数。以下示例读作“10 feet”：
```
<speak><say-as interpret-as="unit">10 foot</say-as>
</speak>
```
以下示例读作“Two thirty P.M.”：
```
<speak><say-as interpret-as="time" format="hms12">2:30pm</say-as>
</speak>
```
format 属性是一系列时间字段字符代码。format 中支持的字段字符代码为 {h、m、s、Z、12、24}，分别表示时、（这个小时的）分、（这个分钟的）秒、时区、12 小时制和 24 小时制。如果该字段代码针对时、分或秒显示一次，则预期的位数分别为 1、2 和 2。如果该字段代码重复出现，则预期位数是代码重复的次数。时间文本中的字段可以用标点符号和/或空格分隔。如果未在格式中指定时、分或秒，或者没有匹配的位数，则该字段将被视为零值。默认 format 为“hms12”。

detail 属性控制时间的口语形式是 12 小时制还是 24 小时制。如果 detail='1' 或者 detail 省略，则口语形式为 24 小时制，时间格式为 24 小时制。如果 detail='2' 或者 detail 省略，则口语形式为 12 小时制，时间格式为 12 小时制。

`<audio>`

支持在合成语音输出中插入录制的音频文件和其他音频格式。

属性

属性	必需	默认	值
`src`	是	无	指向音频媒体源的 URI。支持的协议为 `https`。
`clipBegin`	否	0	一个时间指定值，这是从音频源开始到播放开始点的偏移量。如果此值大于或等于音频源的实际持续时间，则不插入音频。
`clipEnd`	否	无限	一个时间指定值，这是音频源开始到播放结束点的偏移量。如果音频源的实际持续时间小于此值，则播放在音频源持续时间结束时结束。如果 `clipBegin` 的值大于或等于 `clipEnd`，则不插入音频。
`speed`	否	100%	输出播放率相对于正常输入率的比率，以百分比表示。格式为正实数，后跟百分号。目前支持的范围为 [50％（慢速 - 半倍速），200％（快速 - 双倍速）]。超出该范围的值不一定能调整到该范围内。
`repeatCount`	否	1，如果设置了 `repeatDur` 则为 10	一个实数，指定插入音频（如果是剪辑后，按 `clipBegin` 和/或 `clipEnd` 确定）的次数。零不是有效值，因此视为未指定，并且在该情况下具有默认值。
`repeatDur`	否	无限	一个时间指定值，指定在源视频针对 `clipBegin`、`clipEnd`、`repeatCount` 和 `speed` 属性进行处理之后插入的音频持续时间（而不是正常播放时长）的限制。如果处理后的音频持续时间小于此值，则播放在该时间结束。
`soundLevel`	否	+0dB	将音频的音量调整 `soundLevel` 分贝。最大范围为 +/- 40dB，但实际有效范围可能更小，并且输出质量可能无法在整个范围内产生良好的结果。

以下是当前支持的音频设置：

格式：MP3 (MPEG v2)
- 每秒 24K 样本
- 每秒 24K ~ 96K 位，固定速率
格式：Ogg 中的 Opus
- 每秒 24K 样本（超宽带）
- 每秒 24K - 96K 位，固定速率
格式（已弃用）：WAV (RIFF)
- PCM 16 位签名，小端
- 每秒 24K 样本
适用于所有格式：
- 首选单声道，但立体声也可接受。
- 最长持续时间 240 秒。如果您想播放持续时间更长的音频，请考虑执行媒体响应。
- 5 兆字节文件大小限制。
- 来源网址必须使用 HTTPS 协议。
- 提取音频时，我们的 UserAgent 是“Google-Speech-Actions”。

src 网址也必须是 https 网址（Google Cloud Storage 可以在 https 网址上托管您的音频文件）。

如需详细了解媒体响应，请参阅响应指南中的媒体响应部分。

如需详细了解 audio 元素，请参阅 W3 规范。

示例

<speak><audio src="cat_purr_close.ogg"><desc>a cat purring</desc>PURR (sound didn't load)</audio>
</speak>

`,<s>`

句子和段落元素。

如需详细了解 p 和 s 元素，请参阅 W3 规范。

示例

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

``

指示在发音时用别名属性值中的文本替换所包含的文本。

您还可以使用 sub 元素来提供难读单词的简化发音。下面的最后一个示例演示了这个用例在日语中的应用。

如需详细了解 sub 元素，请参阅 W3 规范。

示例

<sub alias="World Wide Web Consortium">W3C</sub>

``

将标记置于文本或标记序列中的空元素。它可用于引用序列中的特定位置，或将标记插入输出流以进行异步通知。

<speak>
Go from <mark name="here"/> here, to <mark name="there"/> there!
</speak>

`<prosody>`

用于自定义元素中所包含文本的音高、语速和音量。目前支持 rate、pitch 和 volume 属性。

您可以根据 W3 规范设置 rate 和 volume 属性。以下三个选项可用于设置 pitch 属性的值：

注意：<prosody> 标记只能用于完整句子。将字词包含在句子中可能会导致语音中不希望出现的停顿。

属性	说明
`name`	每个标记的字符串 ID。

选项	说明
相关	请指定一个相对值（例如“低”、“中”、“高”等），其中“中”是默认音高。
半音	分别使用“+Nst”或“-Nst”来按“N”半音来增加或降低音高。请注意，“+/-”和“st”为必需。
百分比	分别使用“+N％”或“-N％”来按“N”增加或降低音高。请注意，“％”为必需，但“+/-”为可选。

如需详细了解 prosody 元素，请参阅 W3 规范。

示例

以下示例使用 <prosody> 元素以低于正常值 2 个半音的音高缓慢说话：

<prosody rate="slow" pitch="-2st">Can you hear me now?</prosody>

`<emphasis>`

用于添加或移除元素所含文本中的重音。<emphasis> 元素修改语音的方式与 <prosody> 类似，但不需要设置单独的语音属性。

注意：<emphasis> 标记只能用于完整句子。将字词包含在句子中可能会导致语音中不希望出现的停顿。

此元素支持可选的“等级”属性，其中包含以下有效值：

strong
moderate
none
reduced

如需详细了解 emphasis 元素，请参阅 W3 规范。

示例

以下示例使用 <emphasis> 元素发布公告：

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

`<par>`

允许您一次播放多个媒体元素的并行媒体容器。唯一允许的内容是一个或多个 <par>、<seq> 和 <media> 元素构成的序列。<media> 元素的顺序并不重要。

除非子元素指定不同的开始时间，否则元素的隐式开始时间与 <par> 容器的隐式开始时间相同。如果子元素具有为其开始或结束属性设置的偏移值，则元素的偏移量将是相对于 <par> 容器开始时间的值。对于根 <par> 元素，开始属性会被忽略，开始时间是 SSML 语音合成过程开始为根 <par> 元素生成输出的时间（即生效时间为“零”）。

<speak><par><media xml:id="question" begin="0.5s"><speak>Who invented the Internet?</speak></media><media xml:id="answer" begin="question.end+2.0s"><speak>The Internet was invented by cats.</speak></media><media begin="answer.end-0.2s" soundLevel="-6dB"><audiosrc="https://actions.google.com/.../cartoon_boing.ogg"/></media><media repeatCount="3" soundLevel="+2.28dB"fadeInDur="2s" fadeOutDur="0.2s"><audiosrc="https://actions.google.com/.../cat_purr_close.ogg"/></media></par>
</speak>

`<seq>`

允许您一个接着一个播放媒体元素的依序媒体容器。唯一允许的内容是一个或多个 <seq>、<par> 和 <media> 元素构成的序列。媒体元素的顺序是它们的呈现顺序。

子元素的开始和结束属性可以设置为偏移值（请参阅下面的时间规范）。这些子元素的偏移值将是相对于序列中前一个元素结尾的值，序列中第一个元素则是相对于其 <seq> 容器的开头。

<speak><seq><media begin="0.5s"><speak>Who invented the Internet?</speak></media><media begin="2.0s"><speak>The Internet was invented by cats.</speak></media><media soundLevel="-6dB"><audiosrc="https://actions.google.com/.../cartoon_boing.ogg"/></media><media repeatCount="3" soundLevel="+2.28dB"fadeInDur="2s" fadeOutDur="0.2s"><audiosrc="https://actions.google.com/.../cat_purr_close.ogg"/></media></seq>
</speak>

`<media>`

表示 <par> 或 <seq> 元素中的媒体层。<media> 元素的允许内容是 SSML <speak> 或 <audio> 元素。下表说明了适用于 <media> 元素的有效属性。

属性

属性	必需	默认	值
xml:id	否	没有值	此元素的唯一 XML 标识符。不支持编码实体。允许的标识符值与正则表达式 `"([-_#]
begin	否	0	此媒体容器的开始时间。如果这是根媒体容器元素，则忽略（处理方式与默认值“0”相同）。如需详细了解有效的字符串值，请参阅下面的时间规范部分。
end	否	没有值	此媒体容器的结束时间规范。如需详细了解有效的字符串值，请参阅下面的时间规范部分。
repeatCount	否	1	一个实数，指定插入媒体的次数。重复计数不支持小数，因此该值将四舍五入为整数。零不是有效值，因此视为未指定，并且在该情况下具有默认值。
repeatDur	否	没有值	一个时间指定值，是对插入媒体持续时间的限制。如果媒体的持续时间小于该值，则播放在该时间结束。
soundLevel	否	+0dB	将音频的音量调整 `soundLevel` 分贝。最大范围为 +/- 40dB，但实际有效范围可能更小，并且输出质量可能无法在整个范围内产生良好的结果。
fadeInDur	否	0 秒	一个时间指定值，在此时间范围内，媒体将从静音渐强至可选的指定 `soundLevel`。如果媒体的持续时间小于此值，渐强将在播放结束时停止，并且音量不会达到指定的音量。
fadeOutDur	否	0 秒	一个时间指定值，在此时间范围内，媒体将从可选的指定 `soundLevel` 渐弱，直至静音。如果媒体的持续时间小于此值，则音量会设置为较低的值，以确保在播放结束时达到静音。

时间规范

用于 <media> 元素和媒体容器（<par> 和 <seq> 元素）的“开始”和“结束”属性值的时间规范，要么是偏移值（例如 +2.5s），要么是 syncbase 值（例如 foo_id.end-250ms）。

偏移值

- 时间偏移值是 SMIL Timecount-value，允许值匹配以下正则表达式：
```
"\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"
```
第一个数字字符串是十进制数的整数部分，第二个数字字符串是小数部分。默认符号（即“(+|-)?”）是“+”。单位值分别对应于时、分、秒和毫秒。单位的默认值为“s”（秒）。
Syncbase 值

- Syncbase 值是 SMIL syncbase-value，允许值匹配以下正则表达式：
```
"([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"
```
数字和单位的解释方式与偏移值相同。

`<phoneme>`

您可使用 <phoneme> 标记以内嵌方式生成单词的自定义发音。Text-to-Speech 接受 IPA 和 X-SAMPA 语音字母。请参阅 Phones 页面，查看受支持的语言和音素的列表。

每个 <phoneme> 标记的每个应用都指向单个字词的发音：

  <phoneme alphabet="ipa" ph="ˌmænɪˈtoʊbə">manitoba</phoneme><phoneme alphabet="x-sampa" ph='m@"hA:g@%ni:'>mahogany</phoneme>

时长

Text-to-Speech 支持 <say-as interpret-as="duration"> 以适当地读取时长。例如，以下示例会被读作“5 小时 30 分钟”：

<say-as interpret-as="duration" format="h:m">5:30</say-as>

格式字符串支持以下值：

缩写词	值
h	小时
m	分钟
s	秒
ms	毫秒

`<voice>`

借助 <voice> 标记，您可以在单个 SSML 请求中使用多个语音。在以下示例中，默认语音是英语男声。除“quest-ce t’améne ici”之外，所有单词都合成到此语音中，它将用法语女声而不是默认语言（英语）和性别（男性）读出来。

<speak>And then she asked, <voice language="fr-FR" gender="female">qu'est-ce qui
t'amène ici</voice><break time="250ms"/> in her sweet and gentle voice.</speak>

或者，您可以使用 <voice> 标记指定单个语音（支持的语音页面上的语音名称），而不用指定language 和/或 gender：

<speak>The dog is friendly<voice name="fr-CA-Wavenet-B">mais la chat est
mignon</voice><break time="250ms"/> said a pet shop
owner</speak>

使用 <voice> 标记时，Text-to-Speech 会接收 name（您要使用的语音名称）或下列属性的组合。全部 3 个属性都是可选属性，如果您未提供 name，则必须提供至少一个属性。

gender：“男性”、“女性”或“中性”。
variant：如果根据您的配置确定使用哪种语音时有多种可能性，则用作裁定。
language：您所需的语言。一个给定的 <voice> 标记中只能指定一种语言。以 BCP-47 格式指定您的语言。您可以在支持的语音和语言页面上的语言代码列中找到与您的语言对应的 BCP-47 代码。

您还可以使用两个附加标记 required 和 ordering 控制每个 gender、variant 和 language 特性的相对优先级。

required：如果属性被指定为 required 且配置不正确，则请求将失败。
ordering：ordering 标记后列出的任何属性都被视为首选属性，而非必需属性。Text-to-Speech API 会尽量按属性在 ordering 标记后面列出的顺序考虑首选属性。如果任何首选属性配置不正确，Text-to-Speech 仍可能返回有效的语音，但丢弃错误的配置。

使用 required 和 ordering 标记的配置示例：

<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>

`<lang>`

您可以使用 <lang> 在同一 SSML 请求中包括多种语言的文本。所有语言都将合成到同一语音中，除非您使用 <voice> 标记明确更改语音。xml:lang 字符串必须包含 BCP-47 格式的目标语言（此值在支持的语音表中列为“语言代码”）。在下面的例子中，“chat”用法语读出来，而不是用默认语言（英语）：

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

Text-to-Speech 会尽量支持 <lang> 标记。如果在同一 SSML 请求中指定了所有语言组合，则并非所有语言组合都会产生相同的质量结果。在某些情况下，某个语言组合可能会产生可检测到但具有微妙或负面感知性的影响。已知问题：

<lang> 标记不支持带有汉字字符的日语。输入会被直译且读作中文字符。
<lang> 标记不支持闪米特语（如阿拉伯语、希伯来语和波斯语），这些语音导致不读出任何内容。如果要使用上述任一语言，我们建议您使用 <voice> 标记切换到使用能读出您想使用的语言的语音（如果有）。

SSML 时间点

Text-to-Speech API 支持在您创建的音频数据中使用时间点。时间点是与脚本中指定点对应的时间戳（以秒为单位，从生成音频时开始计算）。您可以使用  标记在脚本中设置时间点。生成音频后，API 会返回音频开始时和时间点之间的时间偏移。

设置时间点需要执行两个步骤：

将  SSML 标记添加到脚本中您希望其获取时间戳的位置。
将 TimepointType 设置为 SSML_MARK。如果未设置此字段，则默认情况下不返回时间点。

以下示例返回两个时间点：

timepoint_1：表示生成的音频中“Mark”一词出现的时间（以秒为单位）。
timepoint_2：表示生成的音频中“word”一词出现的时间（以秒为单位）。

<speak>Hello <mark name="timepoint_1"/> Mark. Good to <mark
name="timepoint_2"/> see you.</speak>