SSML

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

Node.js

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);
}

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

音訊

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

根據相關字詞,設定輸出內容的韻律停頓強度。有效值為「x-weak」、「weak」、「medium」、「strong」和「x-strong」。如果這個值為「none」,表示系統不應輸出行政中斷界線,這項設定可用於防止處理器產生前配中斷。其他值則表示符記之間的破裂強度,為非遞增 (在概念上增加)。強度越大的界限通常會搭配停頓。

範例

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

    以下範例的讀法是「四十二美元和一美元」。如果省略語言屬性,系統會使用目前的語言代碼。

    <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 做為字母 O。

    「google:style='zero-as-zero'」屬性目前僅支援英文。

          <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 of9, 996ty」:

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

    以下範例的語音讀法是「9 月十次,九十六十六」:

    <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

    以下範例的語音讀法是「12 萬三百四十五」(美國英文) 或「十二千三百四十五 (英國英文)」:

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

    <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 n/a 參照音訊媒體來源的 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 符號位元,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>

句子和段落元素。

如要進一步瞭解 ps 元素,請參閱 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>

用於自訂元素所含文字的音調、朗讀速率和音量。目前支援 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> 類似的語音內容,但無需設定個別語音屬性。

此元素支援選用的「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> 元素的輸出內容 (即有效時間為「零」)。

注意:這個元素不是標準 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> 元素的組合。媒體元素的順序是這些元素的轉譯順序。

子元素的「begin」和「end」屬性可設為偏移值 (請參閱下方的時間規格)。這些子項元素的偏移值會與序列中前一個元素的結尾相關,或者若為序列中的第一個元素,相對於其 <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 ID。不支援已編碼的實體。允許的 ID 值符合規則運算式 "([-_#]|\p{L}|\p{D})+"。詳情請參閱 XML-ID
開始 0 此媒體容器的開始時間。如果這是根媒體容器元素 (與預設值「0」相同),系統會忽略這個參數。如要瞭解有效的字串值,請參閱下方的時間規格一節。
結束 沒有值 此媒體容器的結束時間規格。如要瞭解有效的字串值,請參閱下方的時間規格一節。
repeatCount 1 實數,用於指定插入媒體的次數。不支援非小數,因此該值會四捨五入至最接近的整數。零不是有效值,因此系統會將零視為未指定,而使用預設值。
repeatDur 沒有值 TimeDesignation,限制插入媒體的時間長度。如果媒體的長度少於此值,則會在該時間結束播放。
soundLevel +0dB 根據 soundLevel 分貝調整音訊的音量。最大範圍是 +/-40dB,但實際範圍可能效率較小,且輸出品質可能無法在整個範圍都產生良好的結果。
fadeInDur 0 秒 TimeDesignation,超過此值,媒體淡入到選擇性指定的 soundLevel。如果媒體的時間長度小於這個值,系統會在播放結束時停止淡入,且音量不會達到指定的聲音等級。
fadeOutDur 0 秒 TimeDesignation,超過此值,媒體從選擇性指定的 soundLevel 淡出,直到無聲。如果媒體的時間長度小於這個值,系統會將音量設為較低的值,確保在播放結束時達到靜音狀態。

時間規格

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

  • 偏移值 - 時間偏移值是一個 SMIL 時間計數值,允許符合規則運算式的值: "\s\*(+|-)?\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

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

  • Syncbase value - 同步基礎值是 SMIL 同步基礎值,允許符合規則運算式的值: "([-_#]|\p{L}|\p{D})+\.(begin|end)\s\*(+|-)\s\*(\d+)(\.\d+)?(h|min|s|ms)?\s\*"

    數字和單位的解釋方式與偏移值相同。

TTS 模擬工具

動作主控台提供 TTS 模擬工具,可用來測試 SSML 與上述任一元素。您可以在主控台的「Simulator」>「Audio」下找到 TTS 模擬工具。在模擬器中輸入文字和 SSML,然後按一下「Update and Listen」聆聽 TTS 輸出內容。

您也可以點選下載按鈕,儲存 TTS 輸出內容的 .mp3 檔案。