語音合成標記語言 (SSML)

您可以在 Text-to-Speech 要求中傳送語音合成標記語言 (SSML)，藉此提供關於語音停頓的細節、必須消音處理的首字母縮略字、日期、時間、縮寫或文字的音訊格式設定，讓音訊回應有更多可彈性調整的空間。如需詳細資訊和程式碼範例，請參閱 Text-to-Speech 的 SSML 教學課程。

以下是 SSML 標記以及 Text-to-Speech 如何合成文字的範例：

<speak>
  Here are <say-as interpret-as="characters">SSML</say-as> samples.
  I can pause <break time="3s"/>.
  I can play a sound
  <audio src="https://www.example.com/MY_MP3_FILE.mp3">didn't get your MP3 audio file</audio>.
  I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.
  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. The digits for ten are <say-as interpret-as="characters">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 範例文件：

Here are S S M L samples. I can pause [3 second pause]. I can play a sound [audio file plays].
I can speak in cardinals. Your number is ten.
Or I can speak in ordinals. You are tenth in line.
Or I can even speak in digits. The digits for ten are one oh.
I can also substitute phrases, like the World Wide Web Consortium.
Finally, I can speak a paragraph with two sentences. This is sentence one. This is sentence two.

Text-to-Speech 支援部分可用的 SSML 標記，本主題將說明這些標記。

如要進一步瞭解如何使用 Text-to-Speech，根據 SSML 輸入內容來建立音訊資料，請參閱建立語音的音訊檔案一文。

SSML 使用提示

根據您實作的情況，將 SSML 酬載發送到 Text-to-Speech 時，可能會需要在 SSML 酬載中逸出引號。以下範例顯示了如何設定 JSON 物件內 SSML 輸入的格式。

"{
    'input':{
     'ssml':'<speak>The <say-as interpret-as=\"characters\">SSML</say-as>
          standard <break time=\"1s\"/>is defined by the
          <sub alias=\"World Wide Web Consortium\">W3C</sub>.</speak>'
    },
    'voice':{
      'languageCode':'en-us',
      'name':'en-US-Standard-B',
      'ssmlGender':'MALE'
    },
    'audioConfig':{
      'audioEncoding':'MP3'
    }
  }"

保留字元

請避免在要轉換為音訊的文字中使用 SSML 保留字元。如要使用 SSML 保留字元，請使用逸出碼，避免系統將字元讀取為程式碼。下表列出保留的 SSML 字元和相關逸出碼。

選取語音

您可以在 VoiceSelectionParams 物件中設定語音。如要查看示範如何使用 VoiceSelectionParams 物件的程式碼範例，請參閱 Text-to-Speech SSML 教學課程。

您可以使用 <voice> 標記以多種聲音朗讀 SSML，但必須將 VoiceSelectionParams 名稱設為相容的聲音：

可使用的 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

  以下範例會唸成「四十二美元一美分」。如果省略語言屬性，系統會使用目前的語言代碼。

  <speak>
    <say-as interpret-as='currency' language='en-US'>$42.01</say-as>
  </speak>
      

• telephone

  請參閱 W3C SSML 1.0 say-as attribute values WG 附註，查看 interpret-as='telephone' 說明。

  以下範例會唸成「一八○○二○二一二一二」。如果省略「google:style」屬性，系統會將數字 0 唸成字母 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 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}」。

  以下範例會唸成「一九六零年九月十日」：

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

  <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> 元素，系統會忽略 begin 屬性，開始時間則是 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 時間計數值，允許符合規則運算式的值： "\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\*"

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

<phoneme>

您可以使用 <phoneme> 標記，在行內產生字詞的自訂發音。Text-to-Speech 接受 IPA 和 X-SAMPA 語音字母。如需支援的語言和音素清單，請參閱音素頁面。

每個 <phoneme> 標記應用程式都會引導單一字詞的發音：

  <phoneme alphabet="ipa" ph="ˌmænɪˈtoʊbə">manitoba</phoneme>
  <phoneme alphabet="x-sampa" ph='m@"hA:g@%ni:'>mahogany</phoneme>

壓力指標

轉錄稿中最多可標示三種重音：

1. 主要重音：在國際音標中以「/」表示，在 X-SAMPA 中則以「/"」表示。
2. 次要重音：在國際音標中以 /ˌ/ 表示，在 X-SAMPA 中以 /%/ 表示。
3. 非重音：未以符號標示 (無論是哪種標示法)。

部分語言可能少於三個等級，或完全不標示重音位置。如要查看語言支援的重音程度，請參閱音素頁面。重音標記會放在每個重音音節的開頭。舉例來說，在美式英文中：

廣泛與狹義轉錄

一般來說，轉錄內容應較為廣泛，且以音素為主。舉例來說，在美式英語中，請轉錄母音間的 /t/ (而非使用輕彈音)：

在某些情況下，使用音素表示法會導致 TTS 結果聽起來不自然 (例如，音素序列在發音上很困難)。

例如，英文中 /s/ 的發音同化。在這種情況下，轉錄稿應反映同化現象：

減少

每個音節都必須包含一個 (且只能有一個) 母音。也就是說，您應避免使用音節輔音，改用縮減母音轉錄。例如：

音節劃分

你可以使用 /./ 選擇性指定音節界線。每個音節都必須包含一個 (且僅限一個) 母音。例如：

自訂發音字典

除了使用 phoneme 標記提供發音外，您也可以在語音合成 RPC 中提供自訂發音的字典。如果要求中包含自訂發音字典，輸入文字會自動轉換為 SSML phoneme 標記。

舉例來說，下列要求含有文字輸入內容和自訂發音，經過轉換後會等同於下列 SSML。

原始輸入內容：

input: {
  text: 'Hello world! It is indeed a beautiful world!',
  custom_pronunciations: {
    pronunciations: {
      phrase: 'world'
      phonetic_encoding: PHONETIC_ENCODING_IPA
      pronunciation: 'wɜːld'
    }
  }
}

轉換後的輸入內容：

input: {
  ssml: '<speak>Hello <phoneme alphabet="ipa" ph="wɜːld">world</phoneme>! It is indeed a beautiful <phoneme alphabet="ipa" ph="wɜːld">world</phoneme>!</speak>'
}

持續時間

Text-to-Speech 支援 <say-as interpret-as="duration">，可正確朗讀時間長度。舉例來說，以下範例會以「五小時三十分鐘」的形式朗讀：

<say-as interpret-as="duration" format="h:m">5:30</say-as>

格式字串支援下列值：

<voice>

<voice> 標記可讓您在單一 SSML 要求中使用多個聲音。在以下範例中，預設語音是英文男聲。 除了「qu'est-ce qui t'amène ici」之外，所有字詞都會以這個聲音合成。這句話會以法文發音，且使用女聲，而非預設語言 (英文) 和性別 (男性)。

<speak>And then she asked, <voice language="fr-FR" gender="female">qu'est-ce qui
t'amène ici</voice><break time="250ms"/> in her sweet and gentle voice.</speak>

或者，您也可以使用 <voice> 標記指定個別語音 (支援的語音頁面上的語音名稱)，而非指定 language 和/或 gender：

<speak>The dog is friendly<voice name="fr-CA-Wavenet-B">mais la chat est
mignon</voice><break time="250ms"/> said a pet shop
owner</speak>

使用 <voice> 標記時，文字轉語音會預期收到 name (要使用的語音名稱)或下列屬性的組合。這三項屬性都是選填，但如果未提供 name，則必須提供至少一項。

• gender：「male」、「female」或「neutral」。
• variant：如果根據設定有多種可用的語音，這項設定會做為優先順序的依據。
• language：所需語言。在指定的 <voice> 標記中，只能指定一種語言。以 BCP-47 格式指定語言。如要查看語言的 BCP-47 代碼，請前往支援的語音和語言頁面，並查看「語言代碼」欄。

你也可以使用另外兩個標記 required 和 ordering，控制 gender、variant 和 language 屬性的相對優先順序。

• required：如果屬性指定為 required，但未正確設定，要求就會失敗。
• ordering：ordering 標記後列出的任何屬性都會視為偏好屬性，而非必要屬性。Text-to-Speech API 會盡可能依列在 ordering 標記後的順序，考量偏好的屬性。如果偏好的屬性設定有誤，文字轉語音可能仍會傳回有效語音，但會捨棄錯誤的設定。

使用 required 和 ordering 代碼的設定範例：

<speak>And there it was <voice language="en-GB" gender="male" required="gender"
ordering="gender language">a flying bird </voice>roaring in the skies for the
first time.</speak>

<speak>Today is supposed to be <voice language="en-GB" gender="female"
ordering="language gender">Sunday Funday.</voice></speak>

<lang>

您可以使用 <lang>，在同一個 SSML 要求中加入多種語言的文字。除非使用 <voice> 標記明確變更語音，否則所有語言都會以同一種語音合成。xml:lang 字串必須包含 BCP-47 格式的目標語言 (這個值在支援的語音表格中列為「語言代碼」)。在下列範例中，「chat」會以法文發音，而非預設語言 (英文)：

<speak>The french word for cat is <lang xml:lang="fr-FR">chat</lang></speak>

文字轉語音會盡量支援 <lang> 標記。如果指定相同的 SSML 要求，並非所有語言組合都會產生相同品質的結果。在某些情況下，語言組合可能會產生可偵測到但細微的影響，或造成負面觀感。已知問題：

• <lang> 標記不支援日文漢字。系統會音譯輸入內容，並以中文字元讀出。
• <lang> 標記不支援阿拉伯文、希伯來文和波斯文等閃米特語言，因此會導致無聲。如要使用上述任一語言，建議使用 <voice> 標記切換至所需語言的語音 (如有)。

SSML 時間點

Text-to-Speech API 支援在建立的音訊資料中使用時間點。時間點是時間戳記 (以秒為單位，從生成的音訊開頭算起)，對應於腳本中的指定點。您可以使用 <mark> 標記在指令碼中設定時間點。生成音訊後，API 會傳回音訊開頭與時間點之間的時間差。

設定時間點有兩個步驟：

1. 在腳本中要取得時間戳記的位置，加入 <mark> SSML 標記。
2. 將「TimepointType」TimepointType設為 SSML_MARK。如未設定這個欄位，系統預設不會傳回時間點。

以下範例會傳回兩個時間點：

• timepoint_1：表示「Mark」一詞在生成的音訊中出現的時間 (以秒為單位)。
• timepoint_2：表示在生成的音訊中，出現「see」一詞的時間 (以秒為單位)。

<speak>Hello <mark name="timepoint_1"/> Mark. Good to <mark
name="timepoint_2"/> see you.</speak>

樣式

1. en-US-Neural2-F
2. en-US-Neural2-J

使用 <google:style> 標記控制要使用的樣式。請只在完整句子前後使用標記。

範例：

<speak><google:style name="lively">Hello I'm so happy today!</google:style></speak>

name 欄位支援下列值：

1. apologetic
2. calm
3. empathetic
4. firm
5. lively