chrome.tts

說明

使用 chrome.tts API 播放合成的文字轉語音 (TTS)。另請參閱相關的 ttsEngine API，這個 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 以上版本

列舉

"start"

"end"

<字詞>

"sentence"

"標記"

"已中斷"

"已取消"

"錯誤"

"pause"

"resume"

TtsEvent

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

屬性

• charIndex

  編號 選填

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

• errorMessage

  string optional

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

• 長度

  編號 選填

  Chrome 74 以上版本

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

• 類型

  EventType

  類型可能為 start (在語音開始時開始、word、達到語句邊界時為 sentence、到達 SSML 標記元素時為 marker)、end、讀完詞結尾時中斷或中斷的類型、interrupted、如果詞語在結束前停止或中斷，類型可能為 cancelled；或者發生其他錯誤時，已從佇列中移除 cancelled。error暫停語音時，如果特定語音在中間暫停，就會觸發 pause 事件；如果語音繼續播放語音，則會觸發 resume。請注意，如果語音在語句間暫停播放，暫停和繼續事件可能不會觸發。

TtsOptions

Chrome 77 以上版本

TTS 引擎的語音選項。

屬性

• desiredEventTypes

  string[] 選填

  您想監聽的 TTS 事件類型。如未指定，可能會傳送所有事件類型。

• 加入佇列

  布林值 選填

  如為 true，且 TTS 已在進行中，則將此話語排入佇列。如果為 false (預設值)，會中斷目前的語音，並在朗讀這個新話語前排出語音佇列。

• extensionId

  string optional

  要使用的語音引擎擴充功能 ID (如果知道的話)。

• gender

  VoiceGender 選用

  自 Chrome 77 版起已淘汰

  性別已淘汰，因此將遭到忽略。

  合成語音的語音性別。

• lang

  string optional

  要用於合成的語言，格式為 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 為一半的速度。Google 嚴格禁止低於 0.1 或高於 10.0 的值，但許多語音限制了最低和最高速率。舉例來說，即使指定的值大於 3.0，特定語音的實際說話速度可能仍不會超過平常的 3 倍。

• requiredEventTypes

  string[] 選填

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

• voiceName

  string optional

  要用於合成的語音名稱。如果空白，系統會採用任何可用的語音。

• 磁碟區

  編號 選填

  朗讀音量介於 0 到 1 之間 (含 0 和 1)，其中 0 代表最低，1 代表最高，預設值為 1.0。

• onEvent

  void optional

  藉由說話口語過程中發生的事件呼叫此函式。

  onEvent 函式如下所示：

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

  • 活動

    TtsEvent

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

TtsVoice

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

屬性

• eventTypes

  EventType[] 選用

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

• extensionId

  string optional

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

• gender

  VoiceGender 選用

  自 Chrome 70 版起已淘汰

  性別已淘汰，因此將遭到忽略。

  這個語音的性別。

• lang

  string optional

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

• 遙控器

  布林值 選填

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

• voiceName

  string optional

  語音的名稱。

VoiceGender

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

性別已淘汰，並遭到忽略。

列舉

"male"

"female"

方法

getVoices()

Promise

chrome.tts.getVoices(
  callback?: function,
)

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

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (voices: TtsVoice[]) => void

  • 聲音

    TtsVoice[]

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

傳回

• Promise&lt;TtsVoice[]&gt;

  Chrome 101 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

isSpeaking()

Promise

chrome.tts.isSpeaking(
  callback?: function,
)

檢查引擎是否正在說話。在 Mac OS X 中，每次系統語音引擎說話時，結果都是 true，即使語音不是由 Chrome 啟動也一樣。

參數

• 回呼

  函式 選用

  callback 參數如下所示：

  (speaking: boolean) => void

  • 說話

    布林值

    如果有，則為「true」，否則傳回「false」。

傳回

• Promise&lt;boolean&gt;

  Chrome 101 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

pause()

chrome.tts.pause()

暫停語音合成，此功能可能在話語中途中斷。回撥或停止通話會取消暫停語音。

resume()

chrome.tts.resume()

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

speak()

Promise

chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

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

參數

• 話語

  字串

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

• 選項

  TtsOptions 選用

  語音選項。

• 回呼

  函式 選用

  callback 參數如下所示：

  () => void

傳回

• 承諾<void>

  Chrome 101 以上版本

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

stop()

chrome.tts.stop()

停止目前的語音，並排清所有待回覆的語音內容。此外，如果語音暫停，現在也會恢復暫停，讓你下次通話時可以繼續說話。

活動

onVoicesChanged

Chrome 124 以上版本

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

當 getVoices 傳回的 tts.TtsVoice 清單有所變更時呼叫。

參數

• 回呼

  函式

  callback 參數如下所示：

  () => void