chrome.tts

說明

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

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

權限

tts

概念與用途

生成語音

從擴充功能呼叫 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() 的第一個引數應為完整的 SSML 文件，包含 XML 標頭和頂層 <speak> 標記，而非文件片段。

例如：

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

Chrome 54 以上版本

列舉

「開始」

「end」

「word」

「sentence」

「marker」

「interrupted」

「已取消」

「error」

「pause」

「resume」

TtsEvent

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

屬性

  • charIndex

    號碼 選填

    語音中目前字元的索引。如果是字詞事件，事件會在一個字詞的結尾和下一個字詞的開頭觸發。charIndex 代表文字中的某個點，也就是下一個要朗讀的字詞開頭。

  • errorMessage

    字串 選填

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

  • 長度

    號碼 選填

    Chrome 74 以上版本

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

  • 類型

    EventType

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

TtsOptions

Chrome 77 以上版本

文字轉語音引擎的語音選項。

屬性

  • desiredEventTypes

    字串陣列 選用

    您感興趣的 TTS 事件類型。如果缺少這項資訊，系統可能會傳送所有事件類型。

  • enqueue

    布林值 選填

    如為 true，如果 TTS 正在進行中，系統會將這段語音加入佇列。如果為 false (預設值)，系統會中斷目前的語音，並在說出這個新語音前，清除語音佇列。

  • extensionId

    字串 選填

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

  • gender

    VoiceGender 選填

    Chrome 77 版起已淘汰

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

    合成語音的性別。

  • lang

    字串 選填

    用於合成的語言，格式為 語言-地區。例如：「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 的值，但許多語音會進一步限制最低和最高速率，例如即使指定大於 3.0 的值，特定語音的說話速度也不會超過正常速度的 3 倍。

  • requiredEventTypes

    字串陣列 選用

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

  • voiceName

    字串 選填

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

  • 磁碟區

    號碼 選填

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

  • onEvent

    void optional

    系統會在說出語音的過程中發生事件時呼叫這個函式。

    onEvent 函式如下所示： 

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

    • 活動

      TtsEvent

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

TtsVoice

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

屬性

  • eventTypes

    EventType[] 選用

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

  • extensionId

    字串 選填

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

  • gender

    VoiceGender 選填

    Chrome 70 版起已淘汰

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

    這個聲音的性別。

  • lang

    字串 選填

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

  • 遙控器

    布林值 選填

    如果是 true，合成引擎就是遠端網路資源。延遲時間可能會較長，且可能會產生頻寬費用。

  • voiceName

    字串 選填

    語音名稱。

VoiceGender

Chrome 54 以上版本 Chrome 70 以上版本已淘汰

性別已遭淘汰，系統會忽略這項屬性。

列舉

「male」

「female」

方法

getVoices()

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

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

傳回

  • Promise<TtsVoice[]>

    Chrome 101 以上版本

isSpeaking()

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

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

傳回

  • Promise<boolean>

    Chrome 101 以上版本

pause()

chrome.tts.pause(): void

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

resume()

chrome.tts.resume(): void

如果語音功能已暫停，會從上次中斷的地方繼續說話。

speak()

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

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

參數

  • 話語

    字串

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

  • 選項

    TtsOptions optional

    語音選項。

傳回

  • Promise<void>

    Chrome 101 以上版本

stop()

chrome.tts.stop(): void

停止目前的任何朗讀，並清除佇列中待處理的語音。此外，如果語音已暫停，系統現在會取消暫停，以便進行下一次語音通話。

事件

onVoicesChanged

Chrome 124 以上版本 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

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

參數

  • callback

    函式

    callback 參數如下： 

    () => void