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'）为 final。在收到其中某个事件后，此语音内容将不再朗读，也不会从此语音内容中收到任何新事件。

有些语音可能不支持所有事件类型，而且有些语音可能根本不会发送任何事件。如果您不想使用某个语音，除非它发送某些事件，请在选项对象的 requiredEventTypes 成员中传递您需要的事件，或使用 getVoices() 选择符合您要求的语音。下面对这两种方法进行了介绍。

SSML 标记

此 API 中使用的措辞可能包含使用语音合成标记语言 (SSML) 的标记。如果您使用 SSML，则 speak() 的第一个参数应该是包含 XML 标头和顶级 <speak> 标记的完整 SSML 文档，而不是文档 fragment。

例如：

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"

TtsEvent

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

属性

• charIndex

  数字可选

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

• errorMessage

  字符串（可选）

  错误说明（如果事件类型为 error）。

• length

  数字可选

  Chrome 74 及更高版本

  语音的下一部分的长度。例如，在 word 事件中，表示接下来将说出的字词的长度。如果语音引擎未设置，则将设置为 -1。

• 类型

  EventType

  类型可以是 start：在语音开始播放时就执行 start，在达到字词边界时设为 word；在到达句子边界时设为 sentence；当到达 SSML 标记元素时，类型为 marker；在到达话语末尾时为 end；当话语在到达结束前停止或中断时，interrupted 表示在语音结束之前就停止或中断；cancelled（当语音在尚未合成之前就从队列中移除时），或者 error（如果发生任何其他错误）。暂停语音时，如果暂停播放特定话语，则会触发 pause 事件；如果暂停播放某个话语，则会触发 resume 事件。请注意，如果在讲话间隙暂停语音，暂停和恢复事件可能不会触发。

TtsOptions

Chrome 77 及更高版本

TTS 引擎的语音选项。

属性

• desiredEventTypes

  string[] 可选

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

• 加入队列

  布尔值 选填

  如果为 true，且 TTS 已在进行中，则将此语音内容加入队列。如果为 false（默认值），则在读出新语音内容之前，中断当前所有语音并刷新语音队列。

• extensionId

  字符串（可选）

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

• gender

  VoiceGender 可选

  从 Chrome 77 开始已废弃

  性别已弃用，系统将忽略它。

  合成语音的语音性别。

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

• requiredEventTypes

  string[] 可选

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

• voiceName

  字符串（可选）

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

• 卷

  数字可选

  朗读的音量介于 0 和 1 之间（包括 0 和 1），0 表示最低，1 表示最高，默认值为 1.0。

• onEvent

  void 可选属性

  系统通过讲话过程中发生的事件调用此函数。

  onEvent 函数如下所示：

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

  • event

    TtsEvent

    来自文字转语音引擎的更新事件，指示这段话语的状态。

TtsVoice

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

属性

• eventTypes

  EventType[] 可选

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

• extensionId

  字符串（可选）

  提供此语音的扩展程序的 ID。

• gender

  VoiceGender 可选

  从 Chrome 70 开始已弃用

  性别已弃用，系统将忽略它。

  此声音的性别。

• lang

  字符串（可选）

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

• 遥控器

  布尔值 选填

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

• voiceName

  字符串（可选）

  语音的名称。

VoiceGender

Chrome 54 及更高版本 从 Chrome 70 开始已弃用

gender [适用性别] 已被弃用，且已被忽略。

枚举

"male"

方法

getVoices()

Promise

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

获取所有可用语音的数组。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (voices: TtsVoice[])=>void

  • 声音

    TtsVoice[]

    tts.TtsVoice 对象数组，表示可用于语音合成的语音。

返回

• Promise<TtsVoice[]>

  Chrome 101 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

isSpeaking()

Promise

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

检查引擎当前是否正在说话。在 Mac OS X 上，只要系统语音引擎正在说话，结果就会为 true，即使语音不是由 Chrome 发起的。

参数

• callback

  函数（可选）

  callback 参数如下所示：

  (speaking: boolean)=>void

  • 正在说话

    boolean

    如果是对话，则为 true，否则为 false。

返回

• Promise<boolean>

  Chrome 101 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

pause()

chrome.tts.pause()

暂停语音合成，可能会在语音内容中间暂停。恢复或停止通话会取消暂停语音。

resume()

chrome.tts.resume()

如果语音已暂停，系统会从中断处继续朗读。

speak()

Promise

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

使用文字转语音引擎朗读文字。

参数

• 话语

  string

  要朗读的文本，可以是纯文本，也可以是格式正确的完整 SSML 文档。不支持 SSML 的语音引擎会去除标记并读出文本。文本的最大长度为 32,768 个字符。

• 选项

  TtsOptions 可选

  语音选项。

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 101 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

stop()

chrome.tts.stop()

停止任何当前语音，并清空所有待处理语音的队列。此外，如果语音已暂停，那么现在会取消暂停以便下次通话说话。

活动

onVoicesChanged

Chrome 124 及更高版本

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

当 getVoices 返回的 tts.TtsVoice 列表发生更改时调用。

参数

• callback

  功能

  callback 参数如下所示：

  ()=>void