browser.tts

說明

使用 chrome.tts API 播放合成的文字轉語音 (TTS) 內容。另請參閱相關的 ttsEngine API，該 API 可讓擴充功能實作語音引擎。

Chrome 在 Windows (使用 SAPI 5)、Mac OS X 和 ChromeOS 上提供這項功能，使用作業系統提供的語音合成功能。在所有平台上，使用者都可以安裝擴充功能，將其註冊為替代語音引擎。

權限

tts

概念和用途

生成語音

請從分機撥打 speak() 進行通話。例如：

browser.tts.speak('Hello, world.');

如要立即停止朗讀，只要呼叫 stop() 即可：

browser.tts.stop();

您可以提供選項，控制語音的各種屬性，例如語速、音調等。例如：

browser.tts.speak('Hello, world.', {'rate': 2.0});

建議您指定語言，以便選擇支援該語言 (和地區方言，如適用) 的合成器。

browser.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

根據預設，每次呼叫 speak() 都會中斷任何進行中的語音，並立即說話。如要判斷通話是否會中斷任何活動，可以呼叫 isSpeaking()。此外，您可以使用 enqueue 選項，將這段語音加入語音佇列，在目前語音播放完畢後播放。

browser.tts.speak('Speak this first.');
browser.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

如需所有選項的完整說明，請參閱 tts.speak()。並非所有語音引擎都支援所有選項。

如要擷取錯誤並確保正確呼叫 speak()，請傳遞不含引數的回呼函式。在回呼中，檢查 runtime.lastError 是否有任何錯誤。

browser.tts.speak(
  utterance,
  options,
  function() {
    if (browser.runtime.lastError) {
      console.log('Error: ' + browser.runtime.lastError.message);
    }
  }
);

回呼會在引擎開始生成語音前立即傳回。回呼的目的是提醒您使用 TTS API 時發生語法錯誤，而非擷取合成及輸出語音過程中可能發生的所有錯誤。如要一併擷取這些錯誤，請使用事件監聽器，詳情請參閱下一節。

監聽事件

如要取得更多有關合成語音狀態的即時資訊，請在選項中將事件監聽器傳遞至 speak()，如下所示：

browser.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 文件，而非文件片段。

例如：

browser.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 物件陣列做為引數：

browser.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

Chrome 54+ 瀏覽器。*自 Chrome 148 起

列舉

「開始」

"end"

"word"

"sentence"

"marker"

「interrupted」

"cancelled"

"error"

"pause"

"resume"

TtsEvent

TTS 引擎發出的事件，用於傳達語音狀態。

屬性

• charIndex

  數字 選填

  語句中目前字元的索引。如果是字詞事件，事件會在一個字詞結束後、下一個字詞開始前觸發。charIndex 代表文字中下一個要朗讀的字詞開頭。

• 錯誤訊息

  字串 選填

  如果事件類型為 error，則會顯示錯誤說明。

• 長度

  數字 選填

  Chrome 74 以上版本 瀏覽器。*自 Chrome 148 起

  語句下一部分的長度。舉例來說，在 word 事件中，這是下一個要讀出的字詞長度。如果語音引擎未設定，則會設為 -1。

• 類型

  EventType

  類型可以是 start (語音開始時)、word (到達字詞邊界時)、sentence (到達句子邊界時)、marker (到達 SSML 標記元素時)、end (到達語句結尾時)、interrupted (語句在到達結尾前停止或中斷時)、cancelled (在合成前從佇列中移除時)，或 error (發生任何其他錯誤時)。暫停語音時，如果特定語句在中間暫停，系統會觸發 pause 事件；如果語句恢復語音，則會觸發 resume 事件。請注意，如果語音在語句之間暫停，可能不會觸發暫停和繼續事件。

TtsOptions

Chrome 77 以上版本 瀏覽器。*自 Chrome 148 起

TTS 引擎的語音選項。

屬性

• desiredEventTypes

  string[] 選填

  您想監聽的 TTS 事件類型。如果缺少這個參數，系統可能會傳送所有事件類型。

• enqueue

  布林值 選填

  如果設為 true，且文字轉語音功能已在執行中，系統會將這段語音加入佇列。如果設為 false (預設值)，系統會中斷目前的語音，並在說出新語句前清除語音佇列。

• extensionId

  字串 選填

  要使用的語音引擎擴充功能 ID (如有)。

• 性別

  VoiceGender 選填

  自 Chrome 77 起淘汰

  性別已淘汰，系統會忽略。

  合成語音的性別。

• 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，但許多語音會進一步限制最低和最高語速，例如特定語音的實際語速可能不會超過正常語速的 3 倍，即使您指定的值大於 3.0 也一樣。

• requiredEventTypes

  string[] 選填

  語音必須支援的 TTS 事件類型。

• voiceName

  字串 選填

  合成時使用的語音名稱。如果留空，則會使用任何可用的語音。

• 磁碟區

  數字 選填

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

• onEvent

  void 選填

  系統會在朗讀語音內容的過程中，呼叫這個函式並傳入發生的事件。

  onEvent 函式如下所示：

  (event: TtsEvent) => {...}

  • 事件

    TtsEvent

    文字轉語音引擎的更新事件，指出這段語音的狀態。

TtsVoice

語音合成可用語音的說明。

屬性

• eventTypes

  EventType[] 選填

  這個語音可傳送的所有回呼事件類型。

• extensionId

  字串 選填

  提供這個語音的擴充功能 ID。

• 性別

  VoiceGender 選填

  自 Chrome 70 起淘汰

  性別已淘汰，系統會忽略。

  這個語音的性別。

• lang

  字串 選填

  這個語音支援的語言，格式為「語言」-「地區」。例如：「en」、「en-US」、「en-GB」、「zh-CN」。

• 遙控器

  布林值 選填

  如果為 true，表示合成引擎是遠端網路資源。這可能會導致延遲時間較長，並產生頻寬費用。

• voiceName

  字串 選填

  語音名稱。

VoiceGender

Chrome 54 以上版本 Chrome 148 起為 browser.* Chrome 70 起淘汰

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

列舉

"male"

"female"

方法

getVoices()

browser.tts.getVoices(): Promise<TtsVoice[]>

取得所有可用語音的陣列。

傳回

• Promise<TtsVoice[]>

  Chrome 101 以上版本 Chrome 148 以上版本的 browser.*

isSpeaking()

browser.tts.isSpeaking(): Promise<boolean>

檢查引擎目前是否正在朗讀。在 Mac OS X 上，只要系統語音引擎正在朗讀，結果就會是 true，即使朗讀不是由 Chrome 啟動也一樣。

傳回

• Promise<boolean>

  Chrome 101 以上版本 Chrome 148 以上版本的 browser.*

pause()

browser.tts.pause(): void

暫停語音合成，可能會在語句中間暫停。呼叫繼續或停止會取消暫停語音。

resume()

browser.tts.resume(): void

如果語音已暫停，則會從暫停處繼續朗讀。

speak()

browser.tts.speak(
  utterance: string,
  options?: TtsOptions,
): Promise<void>

使用文字轉語音引擎朗讀文字。

參數

• 語句

  字串

  要朗讀的文字，可以是純文字或完整、格式正確的 SSML 文件。不支援 SSML 的語音引擎會移除標記，並朗讀文字。文字長度上限為 32,768 個字元。

• 選項

  TtsOptions 選用

  語音選項。

傳回

• 承諾<void>

  Chrome 101 以上版本 Chrome 148 以上版本的 browser.*

  在語音結束前立即解析。如果發生錯誤，系統會拒絕 Promise。使用 options.onEvent 取得更詳細的意見回饋。

stop()

browser.tts.stop(): void

停止目前的所有語音，並清除待處理語音佇列。此外，如果語音功能已暫停，系統會在下次呼叫 speak 時取消暫停。

事件

onVoicesChanged

Chrome 124 以上版本 瀏覽器。*自 Chrome 148 起

browser.tts.onVoicesChanged.addListener(
  callback: function,
)

當 getVoices 傳回的 tts.TtsVoice 清單有所變更時，系統會呼叫這個方法。

參數

• callback

  函式

  callback 參數如下：

  () => void