本頁面由 Cloud Translation API 翻譯而成。

chrome.ttsEngine

說明

使用 chrome.ttsEngine API 實作文字轉語音(TTS) 引擎，並使用擴充功能。如果擴充功能是使用這個 API 註冊，當任何擴充功能或 Chrome 應用程式使用 tts API 產生語音時，擴充功能就會收到包含要朗讀的字詞和其他參數的事件。這樣一來，擴充功能就能使用任何可用的網路技術來合成及輸出語音，並將事件傳回呼叫函式以回報狀態。

權限

ttsEngine

總覽

擴充功能可以將自己註冊為語音引擎。這樣一來，它就能攔截對 tts.speak 和 tts.stop 等函式的部分或所有呼叫，並提供其他實作方式。擴充功能可自由使用任何可用的網頁技術提供語音，包括來自伺服器的串流音訊、HTML5 音訊。擴充功能甚至可以對語音輸入內容採取其他動作，例如在彈出式視窗中顯示隱藏式輔助字幕，或將其做為記錄訊息傳送至遠端伺服器。

資訊清單

如要實作 TTS 引擎，擴充功能必須宣告「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)。

注意：如果 TTS 引擎不支援 'end' 事件類型，Chrome 就無法排入語音輸入，因為它無法得知語音輸入何時結束。為減輕這種情況，Chrome 會將額外的布林 enqueue 選項傳遞至引擎的 onSpeak 處理常式，讓您可以選擇實作自己的排隊機制。我們不建議這麼做，因為客戶無法將應由不同語音引擎朗讀的語句排入佇列。

您可以傳送的可能事件類型，對應至 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 註冊事件監聽器，則無論資訊清單中包含什麼內容，擴充功能都不會攔截任何語音呼叫。

系統會根據擴充功能是否支援其資訊清單中的指定語音參數，以及是否已為 onSpeak 和 onStop 註冊事件監聽器，決定是否將指定語音要求傳送至擴充功能。換句話說，擴充功能無法接收語音要求，並動態決定是否要處理該要求。

類型

AudioBuffer

Chrome 92 以上版本

參數包含音訊緩衝區和相關資料。

屬性

audioBuffer

ArrayBuffer

文字轉語音引擎的音訊緩衝區。長度應與 audioStreamOptions.bufferSize 完全相同，並以音訊串流選項的 sampleRate 編碼為單聲道，並以線性 PCM 和 32 位元帶符號浮點值 (即 JavaScript 中的 Float32Array 類型) 編碼。
charIndex

號碼選填

與此音訊緩衝區相關聯的字元索引。
isLastBuffer

boolean 選填

如果此音訊緩衝區是所說文字的最後一個，則為 True。

AudioStreamOptions

Chrome 92 以上版本

包含引擎預期產生的音訊串流格式。

屬性

bufferSize

數字

音訊緩衝區中的樣本數。
sampleRate

數字

音訊緩衝區預期的取樣率。

LanguageInstallStatus

待處理

語音的安裝狀態。

列舉

"notInstalled"

「installing」

「已安裝」

"failed"

LanguageStatus

待處理

語言的安裝狀態。

屬性

錯誤

string 選填

安裝失敗的詳細資料。如果語言安裝失敗，系統會視情況填入這個值。
installStatus

LanguageInstallStatus

安裝狀態。
lang

字串

語言字串，格式為語言代碼-地區代碼，其中地區代碼可省略。例如 en、en-AU、zh-CH。

LanguageUninstallOptions

待處理

解除安裝特定語言的選項。

屬性

uninstallImmediately

布林值

如果 TTS 用戶端希望立即解除安裝語言，則為 True。引擎可能會根據這個參數和要求者資訊，選擇是否要卸載語言，以及何時卸載。如果為 false，則可能會使用其他條件 (例如最近的使用情形)，判斷何時要解除安裝。

SpeakOptions

Chrome 92 以上版本

指定給 tts.speak() 方法的選項。

屬性

gender

VoiceGender 選填

已在 Chrome 92 版淘汰

性別已淘汰，系統會略過這項資訊。
合成語音的性別。
lang

string 選填

要用於合成的語言，格式為「語言」-「地區」。例如：'en'、'en-US'、'en-GB'、'zh-CN'。
投球

號碼選填

語調音調介於 0 和 2 之間 (含兩者)，其中 0 為最低，2 為最高。1.0 對應至此語音的預設音調。
費用

號碼選填

相對於此語音的預設速率，說話速率。1.0 是預設速率，通常每分鐘約 180 到 220 個字。2.0 為兩倍速，0.5 為一半的速度。這個值保證會介於 0.1 和 10.0 之間 (含頭尾)。如果語音不支援此完整費率範圍，請勿傳回錯誤。請將速率剪輯為語音支援的範圍。
voiceName

string 選填

要用於合成時使用的聲音名稱。
磁碟區

號碼選填

語音音量介於 0 和 1 之間 (0 為最低，1 為最高)，預設值為 1.0。

TtsClient

Chrome 131 以上版本

用於要求狀態的用戶端 ID。

屬性

id

字串

用戶端提出語言管理要求。對於擴充功能，這是擴充功能專屬 ID。針對 Chrome 功能，這是功能的易讀名稱。
來源

TtsClientSource

要求者的類型。

TtsClientSource

Chrome 131 以上版本

要求者的類型。

列舉

"chromefeature"

"extension"

VoiceGender

Chrome 54 以上版本自 Chrome 70 版起淘汰

性別已淘汰，系統會略過這項資訊。

列舉

"male"

"female"

方法

updateLanguage()

待處理

chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
)

引擎在嘗試安裝語言及解除安裝語言時會呼叫。也可用於回應用戶端的狀態要求。安裝或解除安裝語音時，引擎也應呼叫 ttsEngine.updateVoices 來註冊語音。

參數

狀態

LanguageStatus

語言的安裝狀態。

updateVoices()

Chrome 66 以上版本

chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
)

引擎會呼叫此方法來更新其語音清單。這份清單會覆寫在擴充功能資訊清單中宣告的任何語音。

參數

聲音

TtsVoice[]

代表可用語音合成語音的 tts.TtsVoice 物件陣列。

活動

onInstallLanguageRequest

Chrome 131 以上版本

chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

當 TTS 用戶端要求安裝新語言時觸發。引擎應嘗試下載及安裝語言，並使用結果呼叫 ttsEngine.updateLanguage。成功後，引擎也應呼叫 ttsEngine.updateVoices 來註冊新推出的語音。

參數

回呼

函式

callback 參數如下所示：
```
(requestor: TtsClient, lang: string) => void
```
- 要求者
  
  TtsClient
- lang
  
  字串

onLanguageStatusRequest

待處理

chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

當 TTS 用戶端要求語言的安裝狀態時觸發。

參數

回呼

函式

callback 參數如下所示：
```
(requestor: TtsClient, lang: string) => void
```
- 要求者
  
  TtsClient
- lang
  
  字串

onPause

chrome.ttsEngine.onPause.addListener(
  callback: function,
)

選用：如果引擎支援暫停事件，則應暫停目前正在說出的語音 (如果有)，直到收到繼續事件或停止事件為止。請注意，停止事件也應清除暫停狀態。

參數

回呼

函式

callback 參數如下所示：
```
() => void
```

onResume

chrome.ttsEngine.onResume.addListener(
  callback: function,
)

選用：如果引擎支援暫停事件，則也應支援繼續事件，以便繼續播放目前的語音 (如果有的話)。請注意，停止事件也應清除暫停狀態。

參數

回呼

函式

callback 參數如下所示：
```
() => void
```

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

當使用者呼叫 tts.speak()，且這個擴充功能資訊清單中的其中一個語音是第一個與選項物件相符的語音時，系統會呼叫這個方法。

參數

回呼

函式

callback 參數如下所示：
```
(utterance: string, options: SpeakOptions, sendTtsEvent: function) => void
```
- 話語
  
  字串
- 選項
  
  SpeakOptions
- sendTtsEvent
  
  函式
  
  sendTtsEvent 參數如下所示：
```
(event: tts.TtsEvent) => void
```
  - 活動
    
    tts.TtsEvent
    
    文字轉語音引擎的事件，指出這項語音的狀態。

onSpeakWithAudioStream

Chrome 92 以上版本

chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

當使用者呼叫 tts.speak()，且這個擴充功能資訊清單中的其中一個語音是第一個與選項物件相符的語音時，系統會呼叫這個方法。與 ttsEngine.onSpeak 不同的是，Chrome 提供音訊播放服務，並處理調度 tts 事件。

參數

回呼

函式

callback 參數如下所示：
```
(utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void
```
- 話語
  
  字串
- 選項
  
  SpeakOptions
- audioStreamOptions
  
  AudioStreamOptions
- sendTtsAudio
  
  函式
  
  sendTtsAudio 參數如下所示：
```
(audioBufferParams: AudioBuffer) => void
```
  - audioBufferParams
    
    AudioBuffer
    
    參數包含音訊緩衝區和相關資料。
- sendError
  
  函式
  
  Chrome 94 以上版本
  
  sendError 參數如下所示：
```
(errorMessage?: string) => void
```
  - errorMessage
    
    string 選填
    
    說明錯誤的字串。

onStop

chrome.ttsEngine.onStop.addListener(
  callback: function,
)

在呼叫 tts.stop 時觸發，且此擴充功能可能正在說話。如果擴充功能收到 onStop 的呼叫，且語音已停止，則應不做任何動作 (不會發生錯誤)。如果語音處於暫停狀態，則應取消暫停狀態。

參數

回呼

函式

callback 參數如下所示：
```
() => void
```

onUninstallLanguageRequest

待處理

chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

TTS 用戶端指出不再需要某種語言時觸發。

參數

回呼

函式

callback 參數如下所示：
```
(requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions) => void
```
- 要求者
  
  TtsClient
- lang
  
  字串
- uninstallOptions
  
  LanguageUninstallOptions