SSML (Dialogflow)

向 Google 助理返回响应时，你可以使用 您的响应中包含语音合成标记语言 (SSML)。修改者 你可以使用 SSML，使对话的响应看起来更自然 语音。下面显示了 SSML 标记的示例，以及如何通过 Google 助理。

<ph type="x-smartling-placeholder">

</ph> <ph type="x-smartling-placeholder">

</ph>

SSML

。

function saySSML(conv) {
  const ssml = '<speak>' +
    'Here are <say-as interpret-as="characters">SSML</say-as> samples. ' +
    'I can pause <break time="3" />. ' +
    'I can play a sound <audio src="https://www.example.com/MY_WAVE_FILE.wav">your wave file</audio>. ' +
    'I can speak in cardinals. Your position is <say-as interpret-as="cardinal">10</say-as> in line. ' +
    '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. Your position in line is <say-as interpret-as="digits">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>';
  conv.ask(ssml);
}

JSON

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "<speak>Here are <say-as interpret-as=\"characters\">SSML</say-as> samples. I can pause <break time=\"3\" />. I can play a sound <audio src=\"https://www.example.com/MY_WAVE_FILE.wav\">your wave file</audio>. I can speak in cardinals. Your position is <say-as interpret-as=\"cardinal\">10</say-as> in line. 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. Your position in line is <say-as interpret-as=\"digits\">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>"
              }
            }
          ]
        }
      }
    }
  ]
}

音频

注意 ：对于 <audio> SSML 元素，您必须插入对托管的 音频文件。为帮助你提升 Action 的用户体验，Google 还 在声音库中提供一些托管的音频文件。

Actions 模拟器支持 SSML，但 Dialogflow 不支持 模拟器。

SSML 中的网址

定义仅包含网址的 SSML 响应时，该网址中的和号 可能会导致 XML 格式问题为了确保网址正确无误 将 & 的实例替换为 &。

即使您的 SSML 响应仅包含网址，Actions on Google 仍会要求 显示文本。由于 <audio> 标记内的文本 语音提示时，您可以在您的 <audio> 个代码以满足此要求。<audio> 标记内的文本将 Google 助理会在音频播放完毕后说出的内容，并且与 Action on Google 的 显示文本版本的 SSML 要求。

以下是有问题的 SSML 响应的示例：

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  </audio>
</speak>

上面的示例未转义 & 以实现正确的 XML 格式。

同一 SSML 响应的修复版本如下所示：

<speak>
  <audio src="https://firebasestorage.googleapis.com/v0/b/project-name.appspot.com/o/audio-file-name.ogg?alt=media&amp;token=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX">
  text
  </audio>
</speak>

对 SSML 元素的支持

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

请注意，并非 W3 SSML 规范中所述的所有元素和选项目前都受 Actions on Google 平台的支持。本页面详细介绍了可用于您的应用的元素和选项。下方的 W3 参考链接提供可能对您有帮助的其他上下文参考和示例。

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

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

属性

属性	必需	默认	值
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”。

<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 元素时，请遵循以下准则：

• 使用 START 和 END 标记，而不是在 SSML 的开头或结尾附近添加自定义标记。
• 请勿在 SSML 中添加连续标记。快速连续的标记可能不会生成事件。此外，如果在标记之间没有生成音频，则不会生成事件。例如，请避免执行以下操作：
  Sentence 1. <mark name=a><mark name=b> Sentence 2.
  

注意：为方便起见，互动画布的响应中会自动获取 START 和 END 事件。这些标记未包含在 W3 规范中。

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

示例

亲自尝试一下

<prosody>

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

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

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

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

属性	说明
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> 元素生成输出的时间（即生效时间为“零”）。

注意：此元素不是标准 SSML 元素，而是作为 Actions on Google 平台的额外功能提供。

示例

<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> 容器的开头。

注意：此元素不是标准 SSML 元素，而是作为 Actions on Google 平台的额外功能提供。

示例

<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> 元素的有效属性。

注意：此元素不是标准 SSML 元素，而是作为 Actions on Google 平台的额外功能提供。

属性

属性	必需	默认	值
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\*"

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

TTS 模拟器

Actions 控制台包含一个 TTS 模拟器，可用于测试 SSML 与上述任意元素相关联。您可以在控制台中找到 TTS 模拟器 在 Simulator >音频。在模拟器中输入文本和 SSML，然后点击 点击更新并收听即可收听 TTS 输出。

您也可以点击下载按钮，保存 TTS 的 .mp3 文件 输出。