refresh date: 2026-09-25 robots: noindex
說明
使用 chrome.ttsEngine API，透過擴充功能實作文字轉語音(TTS) 引擎。如果擴充功能使用這個 API 註冊，當任何擴充功能或 Chrome 應用程式使用 tts API 產生語音時，就會收到包含要朗讀語音和其他參數的事件。接著，擴充功能可以使用任何可用的網路技術合成及輸出語音，並將事件傳回呼叫函式，回報狀態。
權限
ttsEngine總覽
擴充功能可以註冊為語音引擎。這樣一來，它就能攔截部分或所有對 tts.speak 和 tts.stop 等函式的呼叫，並提供替代實作。擴充功能可自由使用任何可用的網路技術提供語音，包括從伺服器串流音訊、HTML5 音訊。擴充功能甚至可以對語音內容執行其他操作，例如在彈出式視窗中顯示隱藏式輔助字幕，或將語音內容做為記錄訊息傳送至遠端伺服器。
資訊清單
如要導入文字轉語音引擎，擴充功能必須宣告「ttsEngine」權限，然後在擴充功能資訊清單中宣告其提供的所有語音，如下所示：
{
"name": "My TTS Engine",
"version": "1.0",
"permissions": ["ttsEngine"],
"tts_engine": {
"voices": [
{
"voice_name": "Alice",
"lang": "en-US",
"event_types": ["start", "marker", "end"]
},
{
"voice_name": "Pat",
"lang": "en-US",
"event_types": ["end"]
}
]
},
"background": {
"page": "background.html",
"persistent": false
}
}
擴充功能可以指定任意數量的語音。
必須使用 voice_name 參數。名稱應清楚描述語音和所用引擎。萬一有兩個擴充功能註冊了相同名稱的語音，用戶端可以指定應執行合成的擴充功能 ID。
lang 參數為選用，但強烈建議使用。語音幾乎只能合成單一語言的語音。如果引擎支援多種語言，可以輕鬆為每種語言註冊不同的語音。在極少數情況下，如果單一語音可以處理多種語言，最簡單的做法是列出兩種不同的語音，並在內部使用相同的邏輯處理。不過，如果您想建立可處理任何語言語音的語音，請從擴充功能的資訊清單中省略 lang 參數。
最後，如果引擎可以傳送事件，向用戶端更新語音合成進度，則必須使用 event_types 參數。強烈建議至少支援 'end' 事件類型，指出語音何時結束，否則 Chrome 無法排定佇列中的語音。
載入後，擴充功能可以呼叫 chrome.ttsEngine.updateVoices，取代宣告的語音清單。(請注意，以程式輔助方式呼叫 updateVoices 時使用的參數採用駝峰式大小寫，例如 voiceName，與使用 voice_name 的資訊清單檔案不同)。
您可以傳送的事件類型，與 speak() 方法接收的事件類型相對應：
'start'：引擎已開始朗讀語音。'word'：已達字詞邊界。使用event.charIndex判斷目前的語音位置。'sentence'：已達句子邊界。使用event.charIndex判斷目前的語音位置。'marker'：已到達 SSML 標記。使用event.charIndex判斷目前的語音位置。'end'：引擎已完成語音朗讀。'error'：發生引擎專屬錯誤，無法朗讀這段語音。在event.errorMessage中傳遞更多資訊。
'interrupted' 和 'cancelled' 事件並非由語音引擎傳送，而是由 Chrome 自動產生。
假設您已按照下方說明註冊語音事件監聽器，文字轉語音用戶端可以呼叫 tts.getVoices，從擴充功能的資訊清單中取得語音資訊。
處理語音事件
如要根據用戶端要求生成語音，擴充功能必須為 onSpeak 和 onStop 註冊事件監聽器，如下所示：
const speakListener = (utterance, options, sendTtsEvent) => {
sendTtsEvent({type: 'start', charIndex: 0})
// (start speaking)
sendTtsEvent({type: 'end', charIndex: utterance.length})
};
const stopListener = () => {
// (stop all speech)
};
chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);
是否將特定語音要求傳送至擴充功能，完全取決於擴充功能是否在其資訊清單中支援指定的語音參數，並已註冊 onSpeak 和 onStop 的事件監聽器。換句話說，擴充功能無法接收語音要求，並動態決定是否處理。
類型
AudioBuffer
包含音訊緩衝區和相關資料的參數。
屬性
-
audioBuffer
ArrayBuffer
文字轉語音引擎的音訊緩衝區。長度應與 audioStreamOptions.bufferSize 完全相同，並編碼為單聲道、audioStreamOptions.sampleRate，以及線性 PCM、32 位元帶正負號浮點數，即 JavaScript 中的 Float32Array 類型。
-
charIndex
數字 選填
與這個音訊緩衝區相關聯的字元索引。
-
isLastBuffer
布林值 選填
如果這個音訊緩衝區是朗讀文字的最後一個緩衝區，則為 True。
AudioStreamOptions
包含引擎預期產生的音訊串流格式。
屬性
-
bufferSize
數字
音訊緩衝區中的樣本數量。
-
sampleRate
數字
音訊緩衝區中的預期取樣率。
LanguageInstallStatus
語音的安裝狀態。
列舉
"notInstalled"
"installing"
"installed"
「失敗」
LanguageStatus
語言的安裝狀態。
屬性
-
錯誤
字串 選填
安裝失敗的詳細資料。如果無法安裝語言，則可選擇填入。
-
installStatus
安裝狀態。
-
lang
字串
語言字串，格式為「語言代碼-地區代碼」，其中地區代碼可省略。例如 en、en-AU、zh-CH。
LanguageUninstallOptions
解除安裝特定語言的選項。
屬性
-
uninstallImmediately
布林值
如果 TTS 用戶端希望立即解除安裝語言，則為 True。引擎可能會根據這項參數和要求者資訊，選擇是否或何時解除安裝語言。如果設為 false，則可能會根據其他條件 (例如最近使用情況) 決定解除安裝時間。
SpeakOptions
為 tts.speak() 方法指定的選項。
屬性
-
性別
VoiceGender 選填
自 Chrome 92 起淘汰性別已淘汰，系統會忽略。
合成語音的性別。
-
lang
字串 選填
合成語音時使用的語言，格式為「語言」-「地區」。例如：「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 之間 (含頭尾)。如果語音不支援這個完整語速範圍，請勿傳回錯誤。請改為將語速限制在語音支援的範圍內。
-
voiceName
字串 選填
合成時使用的語音名稱。
-
磁碟區
數字 選填
說話音量介於 0 到 1 之間 (含 0 和 1)，0 為最低，1 為最高，預設值為 1.0。
TtsClient
要求狀態的用戶端 ID。
屬性
-
id
字串
用戶端提出語言管理要求。如果是擴充功能，則為專屬擴充功能 ID。如果是 Chrome 功能，則為人類可讀的功能名稱。
-
要求者類型。
TtsClientSource
要求者類型。
列舉
"chromefeature"
"extension"
VoiceGender
性別已淘汰，系統會忽略。
列舉
"male"
"female"
方法
updateLanguage()
chrome.ttsEngine.updateLanguage(
status: LanguageStatus,
): void
嘗試安裝或解除安裝語言時，引擎會呼叫這個方法。系統也會在用戶端要求狀態時呼叫這個方法。安裝或解除安裝語音時，引擎也應呼叫 ttsEngine.updateVoices 來註冊語音。
參數
-
語言的安裝狀態。
updateVoices()
chrome.ttsEngine.updateVoices(
voices: TtsVoice[],
): void
由引擎呼叫，用於更新語音清單。這份清單會覆寫這項擴充功能資訊清單中宣告的所有語音。
參數
-
voices
TtsVoice[]
tts.TtsVoice物件陣列，代表可用於語音合成的語音。
事件
onInstallLanguageRequest
chrome.ttsEngine.onInstallLanguageRequest.addListener(
callback: function,
)
當 TTS 用戶端要求安裝新語言時，系統會觸發這個事件。引擎應嘗試下載並安裝語言，然後使用結果呼叫 ttsEngine.updateLanguage。成功後，引擎也應呼叫 ttsEngine.updateVoices，註冊新提供的語音。
onLanguageStatusRequest
chrome.ttsEngine.onLanguageStatusRequest.addListener(
callback: function,
)
TTS 用戶端要求語言的安裝狀態時觸發。
onPause
chrome.ttsEngine.onPause.addListener(
callback: function,
)
選用：如果引擎支援暫停事件，則應暫停目前朗讀的語句 (如有)，直到收到繼續事件或停止事件為止。請注意，停止事件也應清除暫停狀態。
參數
-
callback
函式
callback參數如下：() => void
onResume
chrome.ttsEngine.onResume.addListener(
callback: function,
)
選用：如果引擎支援暫停事件，也應支援繼續事件，以便繼續朗讀目前的語句 (如有)。請注意，停止事件也應清除暫停狀態。
參數
-
callback
函式
callback參數如下：() => void
onSpeak
chrome.ttsEngine.onSpeak.addListener(
callback: function,
)
當使用者呼叫 tts.speak()，且這項擴充功能資訊清單中的其中一個語音最先與選項物件相符時，系統就會呼叫這個函式。
參數
-
callback
函式
callback參數如下：(utterance: string, options: SpeakOptions, sendTtsEvent: function) => void
-
語句
字串
-
選項
-
sendTtsEvent
函式
sendTtsEvent參數如下：(event: tts.TtsEvent) => void
-
事件
文字轉語音引擎的事件，指出這段語音的狀態。
-
-
onSpeakWithAudioStream
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
callback: function,
)
當使用者呼叫 tts.speak()，且這項擴充功能資訊清單中的其中一個語音最先與選項物件相符時，系統就會呼叫這個函式。與 ttsEngine.onSpeak 的差異在於，Chrome 會提供音訊播放服務，並處理 tts 事件調度。
參數
-
callback
函式
callback參數如下：(utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void
-
語句
字串
-
選項
-
audioStreamOptions
-
sendTtsAudio
函式
sendTtsAudio參數如下：(audioBufferParams: AudioBuffer) => void
-
audioBufferParams
包含音訊緩衝區和相關資料的參數。
-
-
sendError
函式
Chrome 94 以上版本sendError參數如下：(errorMessage?: string) => void
-
錯誤訊息
字串 選填
說明錯誤的字串。
-
-
onStop
chrome.ttsEngine.onStop.addListener(
callback: function,
)
呼叫 tts.stop 時觸發，此時這個擴充功能可能正在朗讀。如果擴充功能收到 onStop 呼叫，且語音已停止，則不應執行任何動作 (不應引發錯誤)。如果語音處於暫停狀態，則應取消暫停狀態。
參數
-
callback
函式
callback參數如下：() => void
onUninstallLanguageRequest
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
callback: function,
)
當 TTS 用戶端指出不再需要某種語言時，就會觸發這個事件。
參數
-
callback
函式
callback參數如下：(requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions) => void
-
要求者
-
lang
字串
-
uninstallOptions
-