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() 的第一个实参应为包含 XML 标头和顶级 <speak> 标记的完整 SSML 文档，而不是文档片段。

例如：

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 及更高版本

枚举

“开始”

“结束”

“字词”

“句子”

“marker”

“中断”

“cancelled”

“错误”

“暂停”

“继续”

TtsEvent

来自 TTS 引擎的事件，用于传达朗读的状态。

属性

  • charIndex

    number 可选

    话语中当前字符的索引。对于字词事件，该事件会在一个字词结束时触发，并在下一个字词开始之前触发。charIndex 表示文本中下一个要朗读的字词的开头位置。

  • errorMessage

    字符串（选填）

    如果事件类型为 error，则为错误说明。

  • 长度

    number 可选

    Chrome 74 及更高版本

    话语下一部分的长度。例如，在 word 事件中，这是接下来要朗读的字词的长度。如果语音引擎未设置此值，则会将其设置为 -1。

  • 类型

    EventType

    类型可以是 start（语音开始后立即）、word（到达字词边界时）、sentence（到达句子边界时）、marker（到达 SSML mark 元素时）、end（到达话语末尾时）、interrupted（在到达末尾之前停止或中断话语时）、cancelled（在合成之前从队列中移除时）或 error（发生任何其他错误时）。暂停语音时，如果特定话语在中间暂停，则会触发 pause 事件；如果话语恢复语音，则会触发 resume 事件。请注意，如果在话语之间暂停语音，可能不会触发暂停和恢复事件。

TtsOptions

Chrome 77 及更高版本

TTS 引擎的语音选项。

属性

  • desiredEventTypes

    string[] 可选

    您感兴趣的要监听的 TTS 事件类型。如果缺少此参数，则可能会发送所有事件类型。

  • enqueue

    布尔值（可选）

    如果为 true，则在 TTS 正在进行时将此话语加入队列。如果为 false（默认值），则在说出此新话语之前，会中断任何当前语音并清空语音队列。

  • extensionId

    字符串（选填）

    要使用的语音引擎的扩展程序 ID（如果已知）。

  • gender

    VoiceGender 可选

    自 Chrome 77 起已弃用

    性别已被弃用，系统将忽略此属性。

    合成语音的性别。

  • 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 的值，但许多语音会进一步限制最低和最高速率，例如，即使您指定的值大于 3.0，特定语音实际上也可能不会以超过正常速度 3 倍的速度说话。

  • requiredEventTypes

    string[] 可选

    语音必须支持的 TTS 事件类型。

  • voiceName

    字符串（选填）

    要用于合成的语音的名称。如果为空，则使用任何可用的声音。

  • 音量

    number 可选

    说话音量，介于 0 到 1 之间（含 0 和 1），其中 0 为最低音量，1 为最高音量，默认值为 1.0。

  • onEvent

    void optional

    此函数会随说出话语的过程中发生的事件一起调用。

    onEvent 函数如下所示： 

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

    • 事件

      TtsEvent

      来自文字转语音引擎的更新事件，用于指示相应朗读的状态。

TtsVoice

可用于语音合成的语音的说明。

属性

  • eventTypes

    EventTypeEventType[] 可选

    相应语音能够发送的所有回调事件类型。

  • extensionId

    字符串（选填）

    提供相应语音的扩展服务的 ID。

  • gender

    VoiceGender 可选

    自 Chrome 70 起已弃用

    性别已被弃用，系统将忽略此属性。

    相应语音的性别。

  • lang

    字符串（选填）

    相应语音支持的语言，格式为 language-region。示例：“en”“en-US”“en-GB”“zh-CN”。

  • 遥控器

    布尔值（可选）

    如果为 true，则表示合成引擎是远程网络资源。延迟时间可能会更长，并且可能会产生带宽费用。

  • voiceName

    字符串（选填）

    语音的名称。

VoiceGender

Chrome 54 及更高版本 自 Chrome 70 起弃用

性别已弃用，系统会忽略此属性。

枚举

“男”

"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 可选

    语音选项。

返回

  • Promise<void>

    Chrome 101 及更高版本

stop()

chrome.tts.stop(): void

停止任何当前语音，并清空所有待处理话语的队列。此外，如果之前暂停了语音，现在会取消暂停，以便在下次调用 speak 时继续朗读。

事件

onVoicesChanged

Chrome 124 及更高版本 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

当 getVoices 将返回的 tts.TtsVoice 列表发生变化时调用。

参数

  • callback

    函数

    callback 参数如下所示： 

    () => void