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 的資訊清單檔案不同)。

您可以傳送的可能事件類型與 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

Chrome 92 以上版本

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

屬性

  • audioBuffer

    ArrayBuffer

    文字轉語音引擎的音訊緩衝區。這個值應完全包含 audioStreamOptions.bufferSize，且編碼為單聲道，格式為 audioStreamOptions.sampleRate，以及為線性 pcm、32 位元帶正負號浮點值 (JavaScript 中的 Float32Array 類型)。

  • charIndex

    數字 選填

    與這個音訊緩衝區相關聯的字元索引。

  • isLastBuffer

    布林值 (選用)

    如果這個音訊緩衝區是朗讀文字的最後一個音訊緩衝區，則為「true」。

AudioStreamOptions

Chrome 92 以上版本

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

屬性

  • bufferSize

    號碼

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

  • sampleRate

    號碼

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

SpeakOptions

Chrome 92 以上版本

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

屬性

  • gender

    VoiceGender 選用

    自 Chrome 92 版起已淘汰的項目

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

    合成語音的語音性別。

  • lang

    字串 選用

    用於合成的語言，格式為 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 為一半的速度。這個值保證介於 0.1 到 10.0 (含) 之間。如果語音不支援整個範圍的費率，則不會傳回錯誤。請改為將速率裁剪為語音支援的範圍。

  • voiceName

    字串 選用

    用於合成的語音名稱。

  • 磁碟區

    數字 選填

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

VoiceGender

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

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

列舉

"male"

"female"

方法

updateVoices()

Chrome 66 以上版本 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
)

引擎呼叫了以更新其語音清單。這份清單會覆寫這個擴充功能資訊清單中宣告的語音。

參數

活動

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

      • event

        tts.TtsEvent

        文字轉語音引擎的事件，用於指出這個語音內容的狀態。

onSpeakWithAudioStream

Chrome 92 以上版本 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

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

參數

  • 回呼

    功能

    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

        字串 選用

        說明錯誤的字串。

onStop

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

呼叫 tts.stop 時觸發，且可能正在通話中。如果擴充功能收到對 onStop 的呼叫，而語音已經停止，則不應執行任何動作 (不會引發錯誤)。如果語音處於暫停狀態，就會取消暫停狀態。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    ()=>void