语音合成标记语言 (SSML)

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

下面展示了一个 SSML 标记的示例，以及 Cloud TTS 如何合成文本：

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

Cloud TTS 支持一部分可用的 SSML 标记，本主题将对此进行说明。

如需详细了解如何使用 Cloud TTS 通过 SSML 输入创建音频数据，请参阅创建语音音频文件。

有关使用 SSML 的提示

根据您的实现，您可能需要在发送到 Cloud TTS 的 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'
    }
  }"

预留字符

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

选择语音

您可以在 VoiceSelectionParams 对象中设置语音。请参阅 Text-to-Speech SSML 教程，查看演示 VoiceSelectionParams 对象用法的代码示例。

您可以使用 <voice> 标记以多种声音读取 SSML，但必须将 VoiceSelectionParams 名称设置为兼容的声音：

对 SSML 元素的支持

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

<speak>

SSML 响应的根元素。

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

示例

<speak>
  my SSML content
</speak>

<break>

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

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

属性

示例

以下示例展示了如何使用 <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 值选用属性 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>
      

• characters

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

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

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

• fraction

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

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

• expletive 或 bleep

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

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

• time

  以下示例读作“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 小时制。

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

<audio>

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

属性

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

• 格式：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>

句子和段落元素。

如需详细了解 p 和 s 元素，请参阅 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>

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

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

如需详细了解 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> 元素的有效属性。

属性