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() 的第一个参数应该是包含以下内容的完整 SSML 文档 XML 标头和顶级 <speak> 标记，而不是文档 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 及更高版本

枚举

"start"

"end"

"字词"

"sentence"

"标记"

“中断”

"cancelled"

"错误"

“暂停”

"继续"

TtsEvent

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

属性

  • charIndex

    编号（选填）

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

  • 错误消息

    字符串（可选）

    事件类型为 error 时的错误说明。

  • 长度

    编号（选填）

    Chrome 74 及更高版本

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

  • 类型

    EventType

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

TtsOptions

Chrome 77 及更高版本

TTS 引擎的语音选项。

属性

  • desiredEventTypes

    string[] 选填

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

  • 加入队列

    布尔值（可选）

    如果为 true，则当 TTS 已在进行中时，将该话语加入队列。如果为 false（默认值），系统会中断当前的所有语音，并在说出此新语音之前清空语音队列。

  • extensionId

    字符串（可选）

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

  • gender

    VoiceGender 选填

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 77 起弃用

    Gender 已被弃用，将被忽略。

    合成语音的语音性别。

  • lang

    字符串（可选）

    用于合成的语言，格式为“语言-区域”。示例：“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) => {...}

    • 事件

      TtsEvent

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

TtsVoice

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

属性

  • eventTypes

    EventType[] 选填

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

  • extensionId

    字符串（可选）

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

  • gender

    VoiceGender 选填

    <ph type="x-smartling-placeholder"></ph> 自 Chrome 70 起弃用

    Gender 已被弃用，将被忽略。

    此声音的性别。

  • lang

    字符串（可选）

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

  • 遥控器

    布尔值（可选）

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

  • voiceName

    字符串（可选）

    语音的名称。

VoiceGender

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

Gender 已被弃用，并会被忽略。

枚举

“男性”

“女性”

方法

getVoices()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tts.getVoices(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (voices: TtsVoice[]) => void

返回

  • Promise&lt;TtsVoice[]&gt;

    Chrome 浏览器 101 及以上版本

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

isSpeaking()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tts.isSpeaking(
  callback?: function,
)

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

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (speaking: boolean) => void

    • 说话

      布尔值

      如果说话则为 true，否则为 false。

返回

  • Promise&lt;boolean&gt;

    Chrome 浏览器 101 及以上版本

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

pause()

chrome.tts.pause()

暂停语音合成（可能会在语音或语音合成期间暂停）。呼吁恢复或停止说话，即可取消暂停语音。

resume()

chrome.tts.resume()

如果语音暂停，系统会从中断的地方继续讲话。

speak()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

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

参数

  • 语音

    字符串

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

  • 选项

    TtsOptions 可选

    语音选项。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<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