语音合成标记语言 (SSML)

您可以在 Text-to-Speech 请求中发送语音合成标记语言 (SSML),提供有关暂停以及首字母缩写词、日期、时间、缩写或应予以屏蔽的文本的音频格式等详细信息,以在音频响应中实现更多自定义功能。如需了解详情和代码示例,请参阅 Speech-to-Text SSML 教程

以下示例展示了一个 SSML 标记和 Text-to-Speech 合成文本:

<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 文档的合成文本:

Here are S S M L samples. I can pause [3 second pause]. I can play a sound [audio file plays].
I can speak in cardinals. Your number is ten.
Or I can speak in ordinals. You are tenth in line.
Or I can even speak in digits. The digits for ten are one oh.
I can also substitute phrases, like the World Wide Web Consortium.
Finally, I can speak a paragraph with two sentences. This is sentence one. This is sentence two.

Text-to-Speech 支持一部分可用的 SSML 标记,本主题将对此进行说明。

如需详细了解如何使用 Text-to-Speech 通过 SSML 输入创建音频数据,请参阅创建语音音频文件

有关使用 SSML 的提示

根据您的实现,您可能需要在发送到 Text-to-Speech 的 SSML 载荷中转义引号。以下示例展示了如何设置 JSON 对象中包含的 SSML 输入的格式。

"{
    'input':{
     'ssml':'<speak>The <say-as interpret-as=\"characters\">SSML</say-as>
          standard <break time=\"1s\"/>is defined by the
          <sub alias=\"World Wide Web Consortium\">W3C</sub>.</speak>'
    },
    'voice':{
      'languageCode':'en-us',
      'name':'en-US-Standard-B',
      'ssmlGender':'MALE'
    },
    'audioConfig':{
      'audioEncoding':'MP3'
    }
  }"

在要转换为音频的文本中,您还应该避免使用“<”、“>”、“&”和引号等 XML 控制字符。 当然,在输入 SSML 中设置 XML 元素和实体的格式时,您可以使用这些字符。

使用 SSML 时,只能通过单个语音读取整个 SSML 输入。您可以在 VoiceSelectionParams 对象中设置语音。请参阅 Text-to-Speech SSML 教程,查看演示 VoiceSelectionParams 对象用法的代码示例

SSML 时间点(Beta 版)

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

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

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

对 SSML 元素的支持

以下部分介绍了可在“操作”中使用的 SSML 元素和选项。

<speak>

SSML 响应的根元素。

如需详细了解 speak 元素,请参阅 W3 规范

示例

<speak>
  my SSML content
</speak>

<break>

一个空元素,控制字词之间的停顿或其他韵律边界。可以选择在任何一对标记之间使用 <break>。如果字词之间没有此元素,系统会根据语境自动确定中断。

如需详细了解 break 元素,请参阅 W3 规范

属性

属性 说明
time

以秒或毫秒为单位设置中断的时长(如“3 秒”或“250 毫秒”)。

strength

用相对概念设置输出韵律中断的强度。有效值包括“极弱”、“弱”、“中等”、“强”和“极强”。值“无”表示不应输出韵律中断边界,这可用于防止处理器以其他方式产生韵律中断。其他值表示标记之间存在单调非递减(概念上增加)的中断强度。较强的边界通常伴随着停顿。

示例

以下示例展示了如何使用 <break> 元素在步骤之间停顿:

<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 值选用属性 formatdetail

示例

interpret-as 属性支持以下值:

  • cardinal

    以下示例读作“Twelve thousand three hundred forty five”(美式英语)或“Twelve thousand three hundred and forty five”(英式英语):

    <speak>
      <say-as interpret-as="cardinal">12345</say-as>
    </speak>
        
  • ordinal

    以下示例读作“First”:

    <speak>
      <say-as interpret-as="ordinal">1</say-as>
    </speak>
        
  • characters

    以下示例读作“C A N”:

    <speak>
      <say-as interpret-as="characters">can</say-as>
    </speak>
        
  • fraction

    以下示例读作“five and a half”:

    <speak>
      <say-as interpret-as="fraction">5+1/2</say-as>
    </speak>
        
  • expletivebleep

    以下示例发出哔哔声,就像已经被屏蔽了:

    <speak>
      <say-as interpret-as="expletive">censor this</say-as>
    </speak>
        
  • unit

    根据数字将单位转换为单数或复数。以下示例读作“10 feet”:

    <speak>
      <say-as interpret-as="unit">10 foot</say-as>
    </speak>
        
  • verbatimspell-out

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

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

    format 属性是一系列日期字段字符代码。format 支持的字段字符代码包括 {ymd},分别代表年、月、日(日期)。如果该字段代码针对年、月或日显示一次,则预期的年月日位数分别为 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>
        
  • time

    以下示例读作“Two thirty P.M.”:

    <speak>
      <say-as interpret-as="time" format="hms12">2:30pm</say-as>
    </speak>
        

    format 属性是一系列时间字段字符代码。format 中支持的字段字符代码为 {hmsZ1224},分别表示时、(这个小时的)分、(这个分钟的)秒、时区、12 小时制和 24 小时制。如果该字段代码针对时、分或秒显示一次,则预期的位数分别为 1、2 和 2。如果该字段代码重复出现,则预期位数是代码重复的次数。时间文本中的字段可以用标点符号和/或空格分隔。如果未在格式中指定时、分或秒,或者没有匹配的位数,则该字段将被视为零值。默认 format 为“hms12”。

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

  • telephone

    请参阅 W3C SSML 1.0 say-as 属性值 WG 注释中的 interpret-as='telephone' 说明。

如需详细了解 say-as 元素,请参阅 W3 规范

<audio>

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

属性

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

<audio> 元素的内容可选,可以在音频文件无法播放或者输出设备不支持音频时使用。内容可以包括 <desc> 元素,在这种情况下,该元素的文本内容用于显示。如需了解详情,请参阅响应核对清单中的“录制音频”部分。

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>

<p>,<s>

句子和段落元素。

如需详细了解 ps 元素,请参阅 W3 规范

示例

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

最佳做法

  • 使用 <s>...</s> 标记来封装完整的句子,尤其是当它们包含用于改变 prosody 的 SSML 元素(即 <audio>、<break>、<emphasis>、<par>、<prosody>、<say-as>、<seq> 和 <sub>)。
  • 如果您希望语音中断的时间足够长,这样您就可以听到它,请使用 <s>...</s> 标记并在句子之间插入该中断。

<sub>

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

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

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

示例

<sub alias="World Wide Web Consortium">W3C</sub>
<sub alias="にっぽんばし">日本橋</sub>

<mark>

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

如需详细了解 mark 元素,请参阅 W3 规范

示例


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

<prosody>

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

您可以根据 W3 规范设置 ratevolume 属性。以下三个选项可用于设置 pitch 属性的值:

属性 说明
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> 类似,但不需要设置单独的语音属性。

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

  • 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">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="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">
      <audio
        src="https://actions.google.com/.../cartoon_boing.ogg"/>
    </media>
    <media repeatCount="3" soundLevel="+2.28dB"
      fadeInDur="2s" fadeOutDur="0.2s">
      <audio
        src="https://actions.google.com/.../cat_purr_close.ogg"/>
    </media>
  </seq>
</speak>

<media>

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

属性

属性 必需 默认
xml:id 没有值 此元素的唯一 XML 标识符。不支持编码实体。允许的标识符值与正则表达式 "([-_#]|\p{L}|\p{D})+" 匹配。如需了解详情,请参阅 XML-ID
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\*"

    数字和单位的解释方式与偏移值相同。