SSML (Dialogflow)

向 Google 助理返回响应时,您可以在响应中使用语音合成标记语言 (SSML) 的子集。通过使用 SSML,您可以使对话的响应看起来更接近自然语音。下例展示了一个 SSML 标记以及 Google 助理如何读回该标记。

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>"
              }
            }
          ]
        }
      }
    }
  ]
}

音频

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

SSML 中的网址

在定义仅包含网址的 SSML 响应时,该网址中的 & 字符可能会因 XML 格式设置而导致出现问题。为了确保正确引用网址,请将 & 的实例替换为 &amp;

即使您的 SSML 响应仅包含网址,Actions on Google 也需要提供响应的显示文本。由于 Google 助理不会读出 <audio> 标记中的文本,因此您可以在 <audio> 标记中插入填充文本或简短说明以满足此要求。音频播放后,Google 助理不会说出 <audio> 标记中的文本,并且符合 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 元素和选项。

<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 属性支持以下值:

  • 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>
        
  • 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>
        
  • 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>
        
  • 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>
        
  • 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 小时制。

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

<audio>

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

属性

属性 必需 默认
src 不适用 指向音频媒体源的 URI。支持的协议为 https
clipBegin 0 一个TimeDesignation,这是从音频源开始到播放开始点的偏移量。如果此值大于或等于音频源的实际持续时间,则不插入音频。
clipEnd 无限 一个TimeDesignation,这是音频源开始到播放结束点的偏移量。如果音频源的实际持续时间小于此值,则播放在音频源持续时间结束时结束。如果 clipBegin 的值大于或等于 clipEnd,则不插入音频。
speed 100% 输出播放率相对于正常输入率的比率,以百分比表示。格式为正实数,后跟百分号。目前支持的范围为 [50%(慢速 - 半倍速),200%(快速 - 双倍速)]。超出该范围的值不一定能调整到该范围内。
repeatCount 1,如果设置了 repeatDur 则为 10 一个实数,指定插入音频(如果是剪辑后,按 clipBegin 和/或 clipEnd 确定)的次数。零不是有效值,因此视为未指定,并且在该情况下具有默认值。
repeatDur 无限 一个TimeDesignation,指定在源视频针对 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 没有值 一个TimeDesignation,是对插入媒体持续时间的限制。如果媒体的持续时间小于该值,则播放在该时间结束。
soundLevel +0dB 将音频的音量调整 soundLevel 分贝。最大范围为 +/- 40dB,但实际有效范围可能更小,并且输出质量可能无法在整个范围内产生良好的结果。
fadeInDur 0 秒 一个TimeDesignation,在此时间范围内,媒体将从静音渐强至可选的指定 soundLevel。如果媒体的持续时间小于此值,渐强将在播放结束时停止,并且音量不会达到指定的音量。
fadeOutDur 0 秒 一个TimeDesignation,在此时间范围内,媒体将从可选的指定 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 模拟器。在模拟器中输入文本和 SSML,然后点击 Update and Listen 即可收听 TTS 输出。

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