chrome.ttsEngine

说明

使用 chrome.ttsEngine API 通过扩展程序实现文本转语音(TTS) 引擎。如果您的扩展程序使用此 API 进行注册，那么当任何扩展程序或 Chrome 应用使用 tts API 生成语音时，该扩展程序将收到包含要朗读的语音和其他参数的事件。然后，您的扩展程序可以使用任何可用的 Web 技术来合成和输出语音，并将事件发送回调用函数以报告状态。

权限

ttsEngine

概念和用法

扩展程序可以将自己注册为语音引擎。这样，它就可以拦截对 tts.speak() 和 tts.stop() 等函数的部分或全部调用，并提供替代实现。扩展程序可以自由使用任何可用的 Web 技术来提供语音，包括从服务器流式传输音频、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 会向引擎的 onSpeak 处理脚本传递一个额外的布尔值 enqueue 选项，以便您选择实现自己的队列。不建议这样做，因为这样一来，客户端将无法将应由不同的语音引擎读出的语音内容加入队列。

您可以发送的可能事件类型与 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 完全相同，并以音频流选项的采样率编码为单声道，以及以线性 PCM 编码为 32 位有符号浮点，即 JavaScript 中的 Float32Array 类型。

• charIndex

  number 可选

  与此音频缓冲区关联的字符索引。

• isLastBuffer

  布尔值（可选）

  如果此音频缓冲区是正在朗读的文本的最后一个，则为 true。

AudioStreamOptions

Chrome 92 及更高版本

包含引擎预期生成的音频流格式。

属性

• bufferSize

  数值

  音频缓冲区中的样本数。

• sampleRate

  数值

  音频缓冲区中预期的采样率。

LanguageInstallStatus

待处理

语音的安装状态。

枚举

"notInstalled"

“installing”

“installed”

“failed”

LanguageStatus

待处理

语言的安装状态。

属性

• 错误

  字符串（选填）

  有关安装失败的详细信息。如果语言安装失败，则可选择填充。

• installStatus

  LanguageInstallStatus

  安装状态。

• lang

  字符串

  语言字符串，采用语言代码-地区代码的形式，其中地区代码可以省略。例如 en、en-AU、zh-CH。

LanguageUninstallOptions

待处理

用于卸载给定语言的选项。

属性

• uninstallImmediately

  布尔值

  如果 TTS 客户端希望立即卸载语言，则为 True。引擎可能会根据此参数和请求方信息选择是否以及何时卸载语言。如果为 false，则系统可能会使用其他条件（例如近期使用情况）来确定何时卸载。

SpeakOptions

Chrome 92 及更高版本

向 tts.speak() 方法指定的选项。

属性

• gender

  VoiceGender（语音性别）可选

  从 Chrome 92 开始已废弃

  性别已废弃，将被忽略。

  合成语音的语音性别。

• lang

  字符串（选填）

  要用于合成的语言，格式为语言-地区。示例：“en”“en-US”“en-GB”“zh-CN”。

• 投球

  number 可选

  语音音调介于 0 到 2 之间（包括这两个数值），其中 0 表示最低，2 表示最高。1.0 对应于此语音的默认音调。

• 费率

  number 可选

  与此语音的默认语速相比的语速。1.0 是默认速率，通常为每分钟 180 到 220 个字左右。2.0 表示快一倍的速度，0.5 则表示原有速度的一半。此值保证介于 0.1 到 10.0 之间（包括这两个数值）。如果某个语音不支持此完整速率范围，请勿返回错误。而是将速率剪裁到语音支持的范围。

• voiceName

  字符串（选填）

  要用于合成的语音的名称。

• 音量

  number 可选

  讲话音量，介于 0 到 1 之间（包括这两个数值），其中 0 表示最低音量，1 表示最高音量，默认值为 1.0。

TtsClient

Chrome 131 及更高版本

请求状态的客户端的标识符。

属性

• 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

  函数

  callback 参数如下所示：

  (requestor: TtsClient, lang: string) => void

  • 要求提出者

    TtsClient

  • lang

    字符串

onLanguageStatusRequest

待处理

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

当 TTS 客户端请求语言的安装状态时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (requestor: TtsClient, lang: string) => void

  • 要求提出者

    TtsClient

  • lang

    字符串

onPause

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

可选：如果引擎支持暂停事件，则应暂停当前正在说出的语音（如果有），直到收到恢复事件或停止事件。请注意，停止事件也应清除暂停状态。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onResume

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

可选：如果引擎支持暂停事件，则也应支持恢复事件，以继续说出当前的语音（如果有）。请注意，停止事件也应清除暂停状态。

参数

• callback

  函数

  callback 参数如下所示：

  () => void

onSpeak

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

当用户调用 tts.speak() 且此扩展程序清单中的某个语音最先与 options 对象匹配时调用。

参数

• callback

  函数

  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() 且此扩展程序清单中的某个语音最先与 options 对象匹配时调用。与 ttsEngine.onSpeak 不同，Chrome 提供音频播放服务并处理调度 TTS 事件。

参数

• callback

  函数

  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

  函数

  callback 参数如下所示：

  () => void

onUninstallLanguageRequest

待处理

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

当 TTS 客户端指示不再需要某种语言时触发。

参数

• callback

  函数

  callback 参数如下所示：

  (requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions) => void

  • 要求提出者

    TtsClient

  • lang

    字符串

  • uninstallOptions

    LanguageUninstallOptions