說明
使用 chrome.tts
API 播放合成的文字轉語音 (TTS)。另請參閱相關的 ttsEngine
API,可讓擴充功能實作語音引擎。
權限
tts
總覽
Chrome 使用作業系統提供的語音合成功能,在 Windows (使用 SAPI 5)、Mac OS X 和 ChromeOS 上提供原生支援語音。在所有平台上,使用者可以安裝自行註冊為其他語音引擎的擴充功能。
正在產生語音內容
透過擴充功能呼叫 speak()
即可說話。例如:
chrome.tts.speak('Hello, world.');
如要立即停止說話,只要呼叫 stop()
即可:
chrome.tts.stop();
您可以提供控制語音各種屬性的選項,例如速率、音調等。例如:
chrome.tts.speak('Hello, world.', {'rate': 2.0});
我們也建議您指定語言,讓合成器支援該語言 (以及地區方言,如適用)。
chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});
根據預設,每次呼叫 speak()
都會中斷所有進行中的語音,並立即朗讀內容。如要判斷來電是否會中斷任何動作,可以呼叫 isSpeaking()
。此外,您也可以使用 enqueue
選項,將這個語音內容新增至語音佇列,系統會在目前語音內容結束後朗讀語音內容佇列。
chrome.tts.speak('Speak this first.');
chrome.tts.speak(
'Speak this next, when the first sentence is done.', {'enqueue': true});
如需所有選項的完整說明,請參閱下方的 tts.speak
。並非所有語音引擎都支援所有選項。
如要找出錯誤,並確保您正確呼叫 speak()
,請傳遞不使用引數的回呼函式。在回呼中檢查 runtime.lastError
,確認是否發生任何錯誤。
chrome.tts.speak(
utterance,
options,
function() {
if (chrome.runtime.lastError) {
console.log('Error: ' + chrome.runtime.lastError.message);
}
}
);
回呼會立即傳回,在引擎開始產生語音之前。回呼的目的是提醒您,在使用 TTS API 時發生語法錯誤,而非找出合成和輸出語音過程中可能發生的所有錯誤。如要擷取這些錯誤,您必須使用事件監聽器,說明如下。
監聽事件
如要取得更多有關合成語音狀態的即時資訊,請將選項中的事件監聽器傳遞至 speak()
,如下所示:
chrome.tts.speak(
utterance,
{
onEvent: function(event) {
console.log('Event ' + event.type + ' at position ' + event.charIndex);
if (event.type == 'error') {
console.log('Error: ' + event.errorMessage);
}
}
},
callback
);
每個事件都包含事件類型、目前語音相對於語音內容的字元索引,以及錯誤事件 (選填)。事件類型如下:
'start'
:引擎已開始說話。'word'
:已達到字詞邊界。使用event.charIndex
來判斷目前的語音位置。'sentence'
:已達到語句邊界。使用event.charIndex
來判斷目前的語音位置。'marker'
:已達 SSML 標記。使用event.charIndex
來判斷目前的語音位置。'end'
:引擎已唸出語音內容。'interrupted'
:這個語音內容因再次呼叫speak()
或stop()
而中斷,但並未完成。'cancelled'
:這個語音內容已排入佇列,隨後又由另一個對speak()
或stop()
的呼叫取消,而且完全不再語音。'error'
:發生引擎相關錯誤,因此無法說出這個語音內容。詳情請參閱event.errorMessage
。
這四種事件類型 ('end'
、'interrupted'
、'cancelled'
和 'error'
) 處於最終版階段。收到上述其中一個事件後,該語音內容不會再說話,也不會收到該語音內容的新事件。
有些語音可能不支援所有事件類型,有些語音則完全無法傳送任何事件。如果您不想使用語音,除非它傳送特定事件,請在選項物件的 requiredEventTypes
成員中傳遞您需要的事件,或使用 getVoices()
選擇符合需求的語音。以下詳細說明這兩種情況。
SSML 標記
這個 API 中使用的通口可能包含使用語音合成標記語言 (SSML) 的標記。如果您是使用 SSML,則 speak()
的第一個引數應為包含 XML 標頭和頂層 <speak>
標記的完整 SSML 文件,而不是文件片段。
例如:
chrome.tts.speak(
'<?xml version="1.0"?>' +
'<speak>' +
' The <emphasis>second</emphasis> ' +
' word of this sentence was emphasized.' +
'</speak>'
);
並非所有語音引擎都支援所有 SSML 標記,有些則可能不支援 SSML,但所有引擎都必須忽略其不支援的 SSML,並仍能朗讀基礎文字。
選擇語音
根據預設,Chrome 會根據語言,為你想說的每句話選擇最合適的語音。在大多數的 Windows、Mac OS X 和 ChromeOS 系統上,作業系統提供的語音合成應能使用至少一種語言朗讀任何文字。不過,部分使用者可能會透過作業系統及其他 Chrome 擴充功能實作的語音引擎,提供多種聲音。在這種情況下,您可以實作自訂程式碼來選擇合適的語音,或向使用者顯示選項清單。
如要取得所有語音的清單,請呼叫 getVoices()
並向其傳遞接收 TtsVoice
物件陣列做為引數的函式:
chrome.tts.getVoices(
function(voices) {
for (var i = 0; i < voices.length; i++) {
console.log('Voice ' + i + ':');
console.log(' name: ' + voices[i].voiceName);
console.log(' lang: ' + voices[i].lang);
console.log(' extension id: ' + voices[i].extensionId);
console.log(' event types: ' + voices[i].eventTypes);
}
}
);
類型
EventType
列舉
"word"
"sentence"
"marker"
TtsEvent
TTS 引擎中的事件,用於傳達語音的狀態。
屬性
-
charIndex
數字 選填
當前字元的索引。以字詞事件來說,事件會在一個字詞的結尾和下一個字詞之前觸發。
charIndex
代表在文字開頭,系統要朗讀下一個字詞開頭的一個點。 -
errorMessage
字串 選用
如果事件類型為
error
,則會顯示錯誤說明。 -
length
數字 選填
Chrome 74 以上版本語音內容的後續部分長度。舉例來說,在
word
事件中,這就是下一個朗讀字詞的長度。如果沒有由語音引擎設定,則會設為 -1。 -
類型
語音開始後,類型包括
start
、在達到字詞邊界時為word
、到達語句邊界時為sentence
、到達 SSML 標記元素結束時marker
、在語音內容結束之前停止或中斷時end
、在合成前就從佇列中移除、在合成前就從佇列中移除,或者發生任何其他錯誤時error
。interrupted
cancelled
暫停語音時,如果特定語音內容在中間暫停,則會觸發pause
事件;如果語音內容繼續朗讀,則會觸發resume
。請注意,如果在語音之間暫停了語音,系統可能不會觸發暫停和繼續事件。
TtsOptions
TTS 引擎的語音選項。
屬性
-
desiredEventTypes
string[] 選填
您要監聽的 TTS 事件類型。如果缺少任何事件,系統可能會傳送所有事件類型。
-
排入佇列
布林值 (選用)
如果為 true,如果 TTS 已在進行中,請將這個語音內容排入佇列。如果設為 false (預設值),系統會中斷目前任何的語音,並在朗讀這個新的語音內容前清除語音佇列。
-
extensionId
字串 選用
要使用的語音引擎擴充功能 ID (如果已知)。
-
gender
VoiceGender 選用
自 Chrome 77 版起已淘汰的項目性別已淘汰,系統會予以忽略。
合成語音的語音性別。
-
lang
字串 選用
用於合成的語言,格式為 language-region。例如:「en」、「en-US」、「en-GB」、「zh-CN」。
-
投球
數字 選填
說出 0 到 2 (含 0 和 2) 之間的音調,0 代表最低,2 代表最高。1.0 代表語音的預設音調。
-
費用
數字 選填
相對於這個語音預設速率的說話率。預設速率為 1.0,通常每分鐘約 180 至 220 字。2.0 為兩倍速,0.5 為一半的速度。嚴禁使用低於 0.1 或高於 10.0 的值,但許多語音會進一步限制最小和最大比率。舉例來說,即便指定大於 3.0 的值,特定語音的朗讀速度可能不如預期快 3 倍。
-
requiredEventTypes
string[] 選填
語音必須支援的 TTS 事件類型。
-
voiceName
字串 選用
用於合成的語音名稱。如果空白,系統會使用任何可用的語音。
-
磁碟區
數字 選填
朗讀音量大小介於 0 到 1 (含 0 和 1) 之間,0 為最低音量,1 表示最高,預設值為 1.0。
-
onEvent
void optional
朗讀語音過程中發生的事件會呼叫此函式。
onEvent
函式如下所示:(event: TtsEvent) => {...}
-
event
文字轉語音引擎的更新事件,用於指出這個語音內容的狀態。
-
TtsVoice
適用於語音合成的語音說明。
屬性
-
eventTypes
EventType[] 選用
這個語音能傳送的所有回呼事件類型。
-
extensionId
字串 選用
提供這個語音的擴充功能 ID。
-
gender
VoiceGender 選用
自 Chrome 70 版起已淘汰的項目性別已淘汰,系統會予以忽略。
這個語音的性別。
-
lang
字串 選用
這個語音支援的語言,格式為 language-region。例如:「en」、「en-US」、「en-GB」、「zh-CN」。
-
遙控器
布林值 (選用)
如果為 true,則合成引擎是一個遠端網路資源。這可能導致延遲時間較長,並可能產生頻寬費用。
-
voiceName
字串 選用
語音的名稱。
VoiceGender
性別已淘汰,系統會予以忽略。
列舉
"male"
"female"
方法
getVoices()
chrome.tts.getVoices(
callback?: function,
)
取得所有可用的語音。
參數
-
回呼
函式選用
callback
參數如下所示:(voices: TtsVoice[]) => void
-
聲音
TtsVoice[]
tts.TtsVoice
物件的陣列,代表語音合成的可用語音。
-
傳回
-
Promise<TtsVoice[]>
Chrome 101 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
isSpeaking()
chrome.tts.isSpeaking(
callback?: function,
)
檢查引擎目前是否正在說話。在 Mac OS X 上,只要系統說話,不論語音是否由 Chrome 啟動,結果都會是 true。
參數
-
回呼
函式選用
callback
參數如下所示:(speaking: boolean) => void
-
說話
boolean
如為「是」,否則傳回「否」。
-
傳回
-
Promise<boolean>
Chrome 101 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
pause()
chrome.tts.pause()
暫停語音合成,可能會在語音內容中有朗讀時暫停。假如呼叫繼續或停止,語音功能就會取消暫停。
resume()
chrome.tts.resume()
如果暫停了語音功能,系統會從上次中斷的地方繼續說話。
speak()
chrome.tts.speak(
utterance: string,
options?: TtsOptions,
callback?: function,
)
使用文字轉語音引擎朗讀文字。
參數
-
語音
字串
要朗讀的文字,可以是純文字或格式完整的 SSML 文件。不支援 SSML 的語音引擎會移除標記,並朗讀文字。文字長度上限為 32,768 個字元。
-
選項
TtsOptions 選用
語音選項。
-
回呼
函式選用
callback
參數如下所示:() => void
傳回
-
Promise<void>
Chrome 101 以上版本Promise 僅支援 Manifest V3 以上版本,其他平台就必須使用回呼。
stop()
chrome.tts.stop()
停止任何目前的語音,並清除所有待處理的語音佇列。此外,如果暫停說話,系統現在也會取消暫停,並啟動下一場通話。
活動
onVoicesChanged
chrome.tts.onVoicesChanged.addListener(
callback: function,
)
當 getVoices 傳回的 tts.TtsVoice
清單已變更時會呼叫此方法。
參數
-
回呼
功能
callback
參數如下所示:() => void