chrome.tts

Description

使用 chrome.tts API 播放合成的文字转语音 (TTS)。另请参阅相关的 ttsEngine API，它允许扩展来实现语音引擎。

Permissions

tts

# Overview

中文（简体）

Chrome 使用操作系统提供的语音合成功能，为 Windows（使用 SAPI 5）、Mac OS X 和 Chrome OS 上的语音提供本机支持。在所有平台上，用户都可以安装将自己注册为替代语音引擎的扩展程序。

# Generating speech

从您的扩展程序或 Chrome 应用程序中调用 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 时注意语法错误，而不是捕捉合成和输出语音过程中可能出现的所有错误。要捕获这些错误，您需要使用事件侦听器，如下所述。

# Listening to events(监听事件)

要获得有关合成语音状态的更多实时信息，请在 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 markup

此 API 中使用的话语可能包括使用语音合成标记语言 (SSML) Speech Synthesis Markup Language (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 并仍然说出底层文本。

# Choosing a voice（选择声音）

默认情况下，Chrome 会根据语言为您想说的每个话语选择最合适的语音。在大多数 Windows、Mac OS X 和 Chrome OS 系统上，操作系统提供的语音合成应该能够以至少一种语言说出任何文本。但是，某些用户可能会从他们的操作系统和其他 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);
    }
  }
);

Summary

• Types

  EventType

  TtsEvent

  TtsOptions

  TtsVoice

  VoiceGender

• Methods

  getVoices

  isSpeaking

  pause

  resume

  speak

  stop

Types

EventType

Chrome 54+

TYPE

"start", "end", "word", "sentence", "marker", "interrupted", "cancelled", "error", "pause", or "resume"

TtsEvent

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

PROPERTIES

• charIndex

  number optional

  话语中当前字符的索引。对于单词事件，事件在一个单词的结尾和下一个单词的开头之前触发。 charIndex 表示文本中要说出的下一个单词开头的一个点。

• errorMessage

  string optional

  错误描述，如果事件类型为error。

• length

  number optional

  Chrome 74+

  话语下一部分的长度。例如，在word事件中，这是接下来要说的单词的长度。如果语音引擎未设置，它将设置为 -1。

• type

  EventType

  该类型可以在语音开始start后立即开始，到达单词word边界时的单词，到达句子sentence边界时的句子，marker到达 SSML 标记元素时的标记，到达话语结尾end时结束，当话语在到达结束之前停止或中断时被中断interrupted，当它在合成之前从队列中移除时被取消cancelled，或者在发生任何其他错误error时出错。暂停语音时，如果特定话语在中间暂停，则会触发 pause 事件，如果话语恢复resume语音，则恢复。请注意，如果语音在说话之间暂停，则暂停和恢复事件可能不会触发。

TtsOptions

Chrome 77+

TTS 引擎的语音选项。

PROPERTIES

• desiredEventTypes

  string[] optional

  您有兴趣收听的 TTS 事件类型。如果丢失，则可以发送所有事件类型。

• enqueue

  boolean optional

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

• extensionId

  string optional

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

• gender

  VoiceGender optional

  Deprecated since Chrome 77

  gender已被弃用，将被忽略。

  合成语音的语音性别。

• lang

  string optional

  用于综合的语言，形式为语言区域。示例：“en”、“en-US”、“en-GB”、“zh-CN”。

• pitch

  number optional

  说话音高介于 0 和 2 之间，其中 0 为最低，2 为最高。 1.0 对应于语音的默认音高。

• rate

  number optional

  相对于此语音的默认速率的说话速率。 1.0 是默认速率，通常约为每分钟 180 到 220 个字。 2.0 是两倍，0.5 是一半。严格禁止低于 0.1 或高于 10.0 的值，但许多语音会进一步限制最小和最大速率——例如，即使您指定的值大于 3.0，特定语音实际上可能不会比正常说话速度快 3 倍。

• requiredEventTypes

  string[] optional

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

• voiceName

  string optional

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

• volume

  number optional

  说话音量介于0和1之间，0为最低，1为最高，默认为1.0。

• onEvent

  function optional

  这个函数是用说话过程中发生的事件调用的。

  The onEvent function looks like:

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

  • event

    TtsEvent

    来自文本到语音引擎的更新事件，指示此话语的状态。

TtsVoice

可用于语音合成的语音的描述。

PROPERTIES

• eventTypes

  EventType[] optional

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

• extensionId

  string optional

  提供此语音的分机的 ID。

• gender

  VoiceGender optional

  Deprecated since Chrome 70

  性别已被弃用，将被忽略。

  这个声音的性别。

• lang

  string optional

  此语音支持的语言，形式为语言区域。示例：“en”、“en-US”、“en-GB”、“zh-CN”。

• remote

  boolean optional

  如果为 true，则合成引擎是远程网络资源。这可能会导致更高的延迟并可能产生带宽成本。

• voiceName

  string optional

  声音的名字。

VoiceGender

Chrome 54+ Deprecated since Chrome 70

性别已被弃用并被忽略。

TYPE

"male", or "female"

Methods

getVoices

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

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

PARAMETERS

• callback

  function optional

  The callback parameter looks like:

  (voices: TtsVoice[]) => void

  • voices

    TtsVoice[]

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

isSpeaking

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

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

PARAMETERS

• callback

  function optional

  The callback parameter looks like:

  (speaking: boolean) => void

  • speaking

    boolean

    如果说话为真，否则为假。

pause

chrome.tts.pause()

暂停语音合成，可能在说话的中间。呼叫恢复或停止将取消暂停语音。

resume

chrome.tts.resume()

如果讲话被暂停，则从停止的地方继续讲话。

speak

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

使用文本到语音引擎朗读文本。

PARAMETERS

• utterance

  string

  要朗读的文本，可以是纯文本，也可以是完整的、格式良好的 SSML 文档。不支持 SSML 的语音引擎将剥离标签并朗读文本。文本的最大长度为 32,768 个字符。

• options

  TtsOptions optional

  语音选项。

• callback

  function optional

  The callback parameter looks like:

  () => void

stop

chrome.tts.stop()

停止任何当前语音并刷新任何未决话语的队列。此外，如果语音已暂停，现在将在下一次通话时取消暂停。

By.一粒技术服务.