SSML

將回應傳回 Google 助理時，您可以在回應中使用部分語音合成標記語言 (SSML)。使用 SSML 可讓對話的回應看起來更自然。以下範例顯示 SSML 標記和來自 Google 助理的對應音訊：

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.add(ssml);
}

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

音訊

SSML 中的網址

定義只包含網址的 SSML 回應時，在網址加上連接號會導致 XML 格式發生問題。為確保系統可正確參照網址，請將 & 執行個體替換為 &。

即使您的 SSML 回應僅包含網址，Actions on Google 仍會要求顯示說明文字。由於 Google 不會朗讀 <audio> 標記內的文字，因此您可以在 <audio> 標記中插入填充文字或簡短說明。播放音訊後，Google 助理不會聽到 <audio> 標記中的文字，並且符合「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 規格。

屬性

範例

以下範例說明如何使用 <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

  以下範例使用的名稱為「42 美元 1 美分」。如果省略語言屬性，則會使用目前的語言代碼。

  <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' 說明。

  以下範例使用的語音語言是「一八零零二零二二二一二」。如果省略「google:style」屬性，它則會將零顯示為 O。

  「google:style='zero-as-zero'」屬性目前僅適用於英文地區。

        <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'，只有日欄位以及月或年欄位之一，但也可以同時提供。如果所有欄位都少於三個欄位，則此為預設值。朗讀的表單為 {year} 年 {month} 的 {ordinal day}。

  以下範例可說「九月九十六十」：

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

  以下範例可說「九十九九十六」：

  <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

  以下範例使用的語言是「十二萬三百四十五」(美國英文) 或「十二萬三百四十五 (英國英文)」：

  <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 英尺」：

  <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 符號位元，little endian 位元組順序
  • 每秒取樣 24K
• 所有格式：
  • 建議使用單聲道，但也可以接受立體聲。
  • 長度上限為 240 秒。如要播放較長的音訊，請考慮導入媒體回應。
  • 檔案大小上限 5 MB。
  • 來源網址必須使用 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> 標記來包裝完整句子，尤其是包含會改變原型的 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> 類似，差別在於前者不需要修改個別語音屬性。

這個元素支援下列有效值的「level」屬性：

• strong
• moderate
• none
• reduced

如要進一步瞭解 emphasis 元素，請參閱 W3 規格。

範例

以下範例使用 <emphasis> 元素來發布公告：

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

<par>

可同時播放多個媒體元素的平行媒體容器。唯一允許的內容是由一或多個 <par>、<seq> 和 <media> 元素所組成。<media> 元素的順序並不重要。

除非子項元素指定不同的開始時間，否則元素的隱含開始時間與 <par> 容器相同。如果子項元素的 begin 或 end 屬性設定了偏移值，則元素的偏移值會與 <par> 容器的開始時間相對。對於根 <par> 元素，系統會忽略 start 屬性，而開始時間則是 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> 元素所組成。媒體元素的順序就是元素的顯示方式。

子項元素的 begin 和 end 屬性可設為偏移值 (請參閱下方的時間規格)。這些子元素的偏移值是相對於序列中前一個元素的結尾，如果是序列中的第一個元素，則會相對於其 <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> 元素的有效屬性。

屬性

時間規格

用於 <media> 元素和媒體容器 (<par> 和 <seq> 元素) 的「begin」和「end」屬性值的時間規格可以是偏移值 (例如 +2.5s) 或 syncbase 值 (例如 foo_id.end-250ms)。

• 偏移值 - 時間偏移值是 SMIL Timecount 值，允許符合規則運算式的值： "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

  第一個數字字串是小數的整個部分，第二個數字字串則是小數部分。預設符號 (亦即「(+|-)?」) 為「+」。單位值分別對應小時、分鐘、秒和毫秒，單位的預設值是「s」(秒)。

• Syncbase 值 - Syncbase 值是一個 SMIL syncbase 值，允許符合規則運算式的值： "([-_#]|\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 檔案。