SSML 文件結構和事件
具有輸入文字的語音合成標記語言 (SSML) 會判斷文字轉換語音輸出的結構、內容和其他特性。 例如，您可以使用 SSML 來定義段落、句子、中斷或暫停或靜音。 您可以使用書籤或描聲影像等事件標籤來換行文字，以供應用程式稍後處理。
如需如何在 SSML 文件中建構元素的詳細資訊，請參閱下列各節。
注意
除了 Azure AI 語音神經（非 HD）語音之外，您也可以使用 Azure AI 語音高清 （HD） 語音 和 Azure OpenAI 神經 （HD 和非 HD） 語音。 HD 語音為更多功能的案例提供更高的品質。
某些語音不支援所有 語音合成標記語言 （SSML） 標記。 這包括類神經文字到語音的 HD 語音、個人語音，以及內嵌語音。
- 如需 Azure AI 語音高定義 （HD） 語音，請查看這裡的 SSML 支援。
- 如需個人語音，您可以在這裡找到 SSML 支援。
- 如需內嵌語音，請查看這裡的 SSML 支援。
文件結構
SSML 的語音服務實作基礎是全球資訊網協會的語音合成標記語言 1.0 版。 語音支援的元素可能與 W3C 標準不同。
每個 SSML 文件在建立時都會使用到 SSML 元素或標籤。 這些元素可用來調整聲音、風格、音調、韻律、音量等項目。
以下是基本結構的子集與 SSML 文件的語法：
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="https://www.w3.org/2001/mstts" xml:lang="string">
<mstts:backgroundaudio src="string" volume="string" fadein="string" fadeout="string"/>
<voice name="string" effect="string">
<audio src="string"></audio>
<bookmark mark="string"/>
<break strength="string" time="string" />
<emphasis level="value"></emphasis>
<lang xml:lang="string"></lang>
<lexicon uri="string"/>
<math xmlns="http://www.w3.org/1998/Math/MathML"></math>
<mstts:audioduration value="string"/>
<mstts:ttsembedding speakerProfileId="string"></mstts:ttsembedding>
<mstts:express-as style="string" styledegree="value" role="string"></mstts:express-as>
<mstts:silence type="string" value="string"/>
<mstts:viseme type="string"/>
<p></p>
<phoneme alphabet="string" ph="string"></phoneme>
<prosody pitch="value" contour="value" range="value" rate="value" volume="value"></prosody>
<s></s>
<say-as interpret-as="string" format="string" detail="string"></say-as>
<sub alias="string"></sub>
</voice>
</speak>
下列清單中會說明每個元素中允許的內容範例：
audio：audio元素的內文可以包含純文字或 SSML 標記 (如果音訊檔案無法使用或無法播放的話)。audio元素也可以包含文字和下列元素：audio、break、p、s、phoneme、prosody、say-as和sub。bookmark：此元素不可包含文字或任何其他元素。break：此元素不可包含文字或任何其他元素。emphasis：此元素可包含文字和下列元素：audio、break、emphasis、lang、phoneme、prosody、say-as和sub。lang：此元素可包含除了mstts:backgroundaudiovoice和speak以外的所有其他元素。lexicon：此元素不可包含文字或任何其他元素。math：此元素只可包含文字和 MathML 元素。mstts:audioduration：此元素不可包含文字或任何其他元素。mstts:backgroundaudio：此元素不可包含文字或任何其他元素。mstts:embedding：此元素可包含文字和下列元素：audio、break、emphasis、lang、phoneme、prosody、say-as和sub。mstts:express-as：此元素可包含文字和下列元素：audio、break、emphasis、lang、phoneme、prosody、say-as和sub。mstts:silence：此元素不可包含文字或任何其他元素。mstts:viseme：此元素不可包含文字或任何其他元素。p：此元素可包含文字和下列元素：audio、break、phoneme、prosody、say-as、sub、mstts:express-as和s。phoneme：此元素只可包含文字，且不可包含其他元素。prosody：此元素可包含文字和下列元素：audio、break、p、phoneme、prosody、say-as、sub和s。s：此元素可包含文字和下列元素：audio、break、phoneme、prosody、say-as、mstts:express-as和sub。say-as：此元素只可包含文字，且不可包含其他元素。sub：此元素只可包含文字，且不可包含其他元素。speak：SSML 文件的根項目。 此元素可包含下列元素：mstts:backgroundaudio和voice。voice：此元素可包含除了mstts:backgroundaudio和speak以外的所有其他元素。
語音服務會適時自動處理標點符號，例如在遇到句號後暫停，或在句子的結尾為問號時使用正確語調。
特殊字元
若要在 SSML 元素的值或文字中使用字元 &、< 和 >，您必須使用實體格式。 具體來說，您必須使用 & 而非 &、使用 < 而非 <，並使用 > 來取代 >。 否則 SSML 不能正確剖析。
例如指定 green & yellow 而非 green & yellow。 系統便會如預期地剖析下列 SSML：
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
<voice name="en-US-AvaNeural">
My favorite colors are green & yellow.
</voice>
</speak>
特殊字元 (例如引號、撇號和括弧) 必須避免。 如需相關資訊，請參閱可延伸標記語言 (XML) 1.0：附錄 D。
屬性值必須以雙引號或單引號括住。 例如 <prosody volume="90"> 和 <prosody volume='90'> 是格式正確的有效元素，但 <prosody volume=90> 就無法辨識。
說出根項目
speak 元素包含例如版本、語言和標記詞彙定義等資訊。 speak 元素是根項目，為所有 SSML 文件所必要。 您必須在 speak 元素內指定預設語言，無論語言是否在其他地方 (例如在 lang 元素內) 受到調整。
以下是 speak 元素的語法：
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="string"></speak>
| 屬性 | 描述 | 必要或選用 |
|---|---|---|
version |
指出用來解讀文件標記的 SSML 規格版本。 目前的版本為 「1.0」。 | 必要 |
xml:lang |
根文件的語言。 此值可包含語言代碼，例如 en (英文)，或地區設定，例如 en-US (英文 - 美國)。 |
必要 |
xmlns |
定義 SSML 文件標記詞彙 (元素類型和屬性名稱) 的文件 URI。 目前的 URI 為 "http://www.w3.org/2001/10/synthesis"。 | 必要 |
speak 元素必須包含最少一個語音元素。
說話範例
先前已描述speak 元素的屬性支援值。
單一語音範例
此範例使用 en-US-AvaNeural 語音。 如需更多範例，請參閱語音範例。
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
<voice name="en-US-AvaNeural">
This is the text that is spoken.
</voice>
</speak>
加入中斷符號
使用 break 元素覆寫單字之間中斷或暫停的預設行為。 否則語音服務會自動插入暫停。
下表說明 break 元素屬性的使用方式。
| 屬性 | 描述 | 必要或選用 |
|---|---|---|
strength |
使用下列其中一個值來暫停的相對持續時間：
|
選擇性 |
time |
暫停的絕對持續時間，以秒 (例如 2s) 或毫秒 (例如 500ms) 為單位。 有效值的範圍為 0 到 20000 毫秒。 如果您設定的值大於支援的最大值，服務會使用 20000ms。 如果設定了 time 屬性，則服務會忽略 strength 屬性。 |
選擇性 |
以下是 strength 屬性的更多詳細資料。
| 優勢 | 相對持續時間 |
|---|---|
| 極弱 | 250 毫秒 |
| 週 | 500 毫秒 |
| 中 | 750 毫秒 |
| 強式 | 1,000 毫秒 |
| 極強 | 1,250 毫秒 |
中斷範例
先前已描述break 元素的屬性支援值。 下列三種方式都會新增 750 毫秒中斷。
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
<voice name="en-US-AvaNeural">
Welcome <break /> to text to speech.
Welcome <break strength="medium" /> to text to speech.
Welcome <break time="750ms" /> to text to speech.
</voice>
</speak>
新增靜音
您可以使用 mstts:silence 元素在文字前或文字後插入停頓，或在兩個連續句子之間插入停頓。
mstts:silence 和 break 之間的其中一個差異是可以在文字中的任何位置插入 break 元素。 靜音僅適用於輸入文字的開頭或結尾，或是兩個相鄰句子的界限。
靜音設定會套用至由 voice 元素括住的所有輸入文字。 若要再次重設或變更靜音設定，您必須使用具有相同語音或不同語音的新 voice 元素。
下表說明 mstts:silence 元素屬性的使用方式。
| 屬性 | 描述 | 必要或選用 |
|---|---|---|
type |
指定在何處以及如何新增靜音。 支援下列靜音類型：
絕對靜音類型 (含 -exact 尾碼) 會取代任何其他自然前置或尾端靜音。 絕對靜音類型的優先順序高於對應的非絕對類型。 例如，如果您同時設定 Leading 和 Leading-exact 類型，則 Leading-exact 類型就會生效。 WordBoundary 事件優先於標點符號相關的靜音設定，包括 Comma-exact、Semicolon-exact 或 Enumerationcomma-exact。 當您同時使用 WordBoundary 事件和標點符號相關的靜音設定時，標點符號相關的靜音設定不會生效。 |
必要 |
Value |
暫停的持續時間，以秒 (例如 2s) 或毫秒 (例如 500ms) 為單位。 有效值的範圍為 0 到 20000 毫秒。 如果您設定的值大於支援的最大值，服務會使用 20000ms。 |
必要 |
mstts 靜音範例
先前已描述mstts:silence 元素的屬性支援值。
此範例使用 mstts:silence 在兩個句子之間新增 200 毫秒的靜音。
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="http://www.w3.org/2001/mstts" xml:lang="en-US">
<voice name="en-US-AvaNeural">
<mstts:silence type="Sentenceboundary" value="200ms"/>
If we're home schooling, the best we can do is roll with what each day brings and try to have fun along the way.
A good place to start is by trying out the slew of educational apps that are helping children stay happy and smash their schooling at the same time.
</voice>
</speak>
在此範例中，mstts:silence 用來於逗號處新增 50 毫秒的靜音、於分號新增 100 毫秒的靜音，以及於頓號處新增 150 毫秒的靜音。
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="http://www.w3.org/2001/mstts" xml:lang="zh-CN">
<voice name="zh-CN-YunxiNeural">
<mstts:silence type="comma-exact" value="50ms"/><mstts:silence type="semicolon-exact" value="100ms"/><mstts:silence type="enumerationcomma-exact" value="150ms"/>你好呀，云希、晓晓；你好呀。
</voice>
</speak>
指定段落和句子
p 和 s 元素分別可用來表示段落和句子。 如果沒有這兩個元素，語音服務會自動判斷 SSML 文件的結構。
段落和句子範例
下列範例會定義個別包含句子的兩個段落。 在第二個段落中，語音服務會自動判斷句子結構，因為它們未在 SSML 文件中定義。
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
<voice name="en-US-AvaNeural">
<p>
<s>Introducing the sentence element.</s>
<s>Used to mark individual sentences.</s>
</p>
<p>
Another simple paragraph.
Sentence structure in this paragraph is not explicitly marked.
</p>
</voice>
</speak>
Bookmark 元素
您可以在 SSML 中使用 bookmark 元素，以參考文字或標記順序中的特定位置。 然後使用語音 SDK 並訂閱 BookmarkReached 事件，以取得音訊數據流中每個標記的位移。 bookmark 元素不會說出。 如需詳細資訊，請參閱訂閱合成器事件。
下表說明 bookmark 元素屬性的使用方式。
| 屬性 | 描述 | 必要或選用 |
|---|---|---|
mark |
bookmark 元素的參考文字。 |
必要 |
書籤範例
先前已描述bookmark 元素的屬性支援值。
例如，您或許會想要知道在下列程式碼片段中每個 flower 文字的時間位移：
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="en-US">
<voice name="en-US-AvaNeural">
We are selling <bookmark mark='flower_1'/>roses and <bookmark mark='flower_2'/>daisies.
</voice>
</speak>
Viseme 元素
描聲影像是口說語言中語素的視覺呈現。 Viseme 會在有人說話時定義臉部和嘴巴的位置。 您可以在 SSML 中使用 mstts:viseme 元素來要求 viseme 輸出。 如需詳細資訊，請參閱使用 viseme 取得臉部位置。
描聲影像設定會套用至由 voice 元素括住的所有輸入文字。 若要再次重設或變更描聲影像設定，您必須使用具有相同語音或不同語音的新 voice 元素。
下表說明 viseme 元素屬性的使用方式。
| 屬性 | 描述 | 必要或選用 |
|---|---|---|
type |
描聲影像輸出的類型。
|
必要 |
注意
目前，redlips_front 僅支援 en-US 地區設定中的神經語音，而 FacialExpression 支援 en-US和 zh-CN 地區設定中的神經語音。
描聲影像範例
先前已描述viseme 元素的屬性支援值。
此 SSML 程式碼片段說明如何使用合成的語音來要求形態融合 (blend shape)。
<speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" xmlns:mstts="http://www.w3.org/2001/mstts" xml:lang="en-US">
<voice name="en-US-AvaNeural">
<mstts:viseme type="FacialExpression"/>
Rainbow has seven colors: Red, orange, yellow, green, blue, indigo, and violet.
</voice>
</speak>