向 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.ask(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,但 Dialogflow 模擬器不支援。
SSML 中的網址
定義只包含網址的 SSML 回應時,該網址中的 & 可能會因為 XML 格式造成問題。為確保網址正確參照,請將 &
的執行個體替換為 &
。
即使您的 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&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
值而定,可以使用選用屬性 format
和 detail
。
範例
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>
-
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 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>
-
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>
支援插入錄製的音訊檔案,以及插入其他音訊格式和合成語音輸出。
屬性
屬性 | 需要 | 預設 | 值 |
---|---|---|---|
src |
是 | n/a | 參照音訊媒體來源的 URI。支援的通訊協定為 https 。 |
clipBegin |
否 | 0 | TimeDesignation,從音訊來源的開頭到開始播放之間的偏移值。如果這個值大於或等於音訊來源的實際時間長度,則不會插入任何音訊。 |
clipEnd |
否 | 無限 | TimeDesignation,從音訊來源的開頭到結束播放的偏移值。如果音訊來源的實際時間長度小於這個值,則會在該時間結束播放。如果 clipBegin 大於或等於 clipEnd ,則不會插入任何音訊。 |
speed |
否 | 100% | 輸出播放率與正常輸入率相對的比率,以百分比表示。格式為正實數,後面接著 %,目前支援的範圍為 [50% (慢 - 半速) 和 200% (快速 - 雙倍速)]。範圍外的值可能會 (或無法) 調整到範圍內。 |
repeatCount |
否 | 1,如果設定 repeatDur ,則為 10 |
是一個實數,指定要插入多少次音訊 (如果有剪輯的話,會加上 clipBegin 和/或 clipEnd )。不支援小數重複次數,因此值會四捨五入至最接近的整數。零不是有效值,因此系統會將零視為未指定,而使用預設值。 |
repeatDur |
否 | 無限 | TimeDesignation,限制 clipBegin 、clipEnd 、repeatCount 和 speed 屬性 (而非一般播放時間長度) 處理來源後,插入音訊的時間長度上限。如果處理的音訊長度低於此值,則播放會在該時間點結束。 |
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>
句子和段落元素。
如要進一步瞭解 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
屬性的值:
屬性 | 說明 |
---|---|
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>
元素的輸出內容 (即有效時間為「零」)。
範例
<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>
元素的有效屬性。
屬性
屬性 | 需要 | 預設 | 值 |
---|---|---|---|
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
檔案。