This page was saved using WebZIP 7.0.3.1030 offline browser on 12/24/13 11:31:36.
Address: https://crxdoc-zh.appspot.com/extensions/tts.html
Title: chrome.tts - Google Chrome 扩展程序开发文档（非官方中文版）  •  Size: 55717

chrome.tts

描述： 使用 chrome.tts API 播放合成的文字语音转换（TTS），同时请您参见相关的 ttsEngine API，允许扩展程序实现语音引擎。
可用版本： 从 Chrome 14 开始稳定支持。
权限： "tts"
了解更多： Chrome 浏览器办公时间：文字语音转换 API

概述

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

朗读

从您的扩展程序或 Chrome 应用中调用 speak() 开始朗读。例如： 

chrome.tts.speak('您好！');

要立刻停止朗读，只要调用stop()： 

chrome.tts.stop();

您可以提供选项，控制语音的多种属性，例如速率、音调等等。例如： 

chrome.tts.speak('您好！', {'rate': 2.0});

最好指定语言，这样会选择支持那种语言（以及方言，如果可用的话）的合成器。 

chrome.tts.speak(
    '您好！', {'lang': 'zh-CN', 'rate': 2.0});

默认情况下每一次调用 speak() 都会中断当前正在进行的朗读，并立刻开始新的朗读。要确定某次调用是否会中断当前的朗读，您可以调用 isSpeaking()。此外，您可以使用 enqueue 选项，将这一次朗读添加到队列中，等到当前朗读完成后再朗读队列中的内容。 

chrome.tts.speak(
    '先说这句话。');
chrome.tts.speak(
    '等第一句话完成后再说这句话。', {'enqueue': true});

所有选项的完整描述可以在下面的 speak() 方法文档 中找到，不是所有的语音引擎都会支持所有选项。

要捕捉错误并确保您正确调用了 speak()，请传递一个没有参数的回调函数。在回调函数中，检查 runtime.lastError 确定是否发生错误。 

chrome.tts.speak(
    utterance,
    options,
    function() {
      if (chrome.runtime.lastError) {
        console.log('错误：' + chrome.runtime.lastError.message);
      }
    });

回调函数在引擎开始朗读前就立刻返回。这一回调函数的目的是提醒您在使用 TTS API 过程中的语法错误，而不是用来捕捉在合成和输出语音的过程中可能发生的错误。要捕捉这些错误，您应该使用事件处理，这将在下面描述。

监听事件

要获得有关语音合成状态的实时信息，请在 speak() 的选项中传递一个事件监听器，如下列代码所示： 

chrome.tts.speak(
    utterance,
    {
      onEvent: function(event) {
        console.log('在位置 ' + event.charIndex ' 处产生事件 ' + event.type);
        if (event.type == 'error') {
          console.log('错误：' + 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>' +
    '  这一句话中第<emphasis>七</emphasis> ' +
    '  个字要强调。' +
    '</speak>');

不是所有的语音引擎都支持所有 SSML 标记，甚至有一些可能完全不支持 SSML，但是所有引擎都会忽略它们不支持的 SSML 并继续朗读其中的文字。

选择语音

默认情况下，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('第 ' + i + ' 种语音：');
        console.log('  名称：' + voices[i].voiceName);
        console.log('  语言：' + voices[i].lang);
        console.log('  性别：' + voices[i].gender);
        console.log('  扩展程序标识符：' + voices[i].extensionId);
        console.log('  事件类型：' + voices[i].eventTypes);
}
});

chrome.tts 参考

类型

TtsEvent

来自 TTS 引擎的事件，通知朗读状态。

TtsEvent 的属性

type ( enum of "start", "end", "word", "sentence", "marker", "interrupted", "cancelled", "error", "pause", or "resume" )

类型可以为：
'start'：朗读刚开始；
'word'：遇到词语边界；
'sentence'：遇到句子边界；
'marker'：遇到 SSML 标记元素；
'end'：朗读完成；
'interrupted'：朗读停止或在到达结尾前中断；
'cancelled'：朗读在合成前就从队列中移除；
'error'：发生错误。
暂停语音时，如果某一次朗读从中间暂停了则产生 'pause' 事件，朗读恢复时产生 'resume' 事件。注意，如果语音在两次朗读之间暂停，可能不会产生暂停和恢复事件。

charIndex ( optional double )

当前朗读的字符索引。

errorMessage ( optional string )

如果事件类型为 'error'，则包含错误描述。

TtsVoice

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

TtsVoice 的属性

voiceName ( optional string )

语音的名称。

lang ( optional string )

语音支持的语言，以语言-区域的形式表示。例如：'zh-CN'、'en'、'en-US'、'en-GB'。

gender ( optional enum of "male", or "female" )

语音的性别，"male" 表示男性，"female" 表示女性。

remote ( optional boolean )

如果为 true，综合引擎是远程网络资源，可能有较高的延迟并且会增加带宽的开销。

extensionId ( optional string )

提供语音的扩展程序的标识符。

eventTypes ( optional array of string )

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

方法

speak

chrome.tts.speak(string utterance, object options, function callback)

使用文字语音转换朗读文本。

参数

utterance ( string )

要朗读的文本，既可以是纯文本，也可以是完整的、形式正确的 SSML 文档。不支持 SSML 的语音引擎会忽略标签只朗读文本。这一文本的最大长度为 32 768 个字符。

options ( optional object )

朗读选项。

属性

enqueue ( optional boolean )

如果为 true，若当前 TTS 正在朗读则将这一次朗读放入队列。如果为 false（默认值），则中断当前的朗读，清理语音队列，然后朗读新的文本。

voiceName ( optional string )

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

extensionId ( optional string )

要使用的语音引擎扩展程序的标识符，如果已知的话。

lang ( optional string )

用于合成的语言，以语言-区域的形式。例如：'zh-CN'、'en'、'en-US'、'en-GB'。

gender ( optional enum of "male", or "female" )

语音合成所使用的性别，"male" 表示男性，"female" 表示女性。

rate ( optional double )

朗读速率，相对于这一语音的默认速率。1.0 表示默认速率，通常为每分钟 180 至 220 个单词。2.0 表示快一倍，而 0.5 是默认速率的一半。不允许 0.1 以下的值或者 10.0 以上的值，并且许多语音会进一步限制最低和最高速率，例如某种语音也许不可能朗读地比默认速率快三倍，即使您指定了大于 3.0 的值。

pitch ( optional double )

指定 0 到 2 之间（包括 0 和 2）的声调，0 表示最低，2 表示最高，1.0 对应于语音的默认声调。

volume ( optional double )

0 到 1 之间（包括 0 和 1）的朗读音量，0 为最低，1 为最高，默认为 1.0。

requiredEventTypes ( optional array of string )

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

desiredEventTypes ( optional array of string )

您需要处理的 TTS 事件类型。如果省略，会发送所有事件。

onEvent ( optional function )

该函数将在朗读过程中发生事件时调用。

参数

event ( TtsEvent )

来自 TTS 引擎的更新事件，指示当前朗读的状态。

callback ( optional function )

在朗读完成前立即调用。检查 runtime.lastError 确保没有错误发生。使用 options.onEvent 获得更详细的反馈。

如果您指定了 callback 参数，它应该指定一个如下形式的函数： 

function() {...};

stop

chrome.tts.stop()

停止当前的朗读，并清空未完成朗读的队列。此外，如果朗读暂停了，则会取消暂停，以便下一次调用时朗读。

pause

chrome.tts.pause()

暂停语音合成，可能正处于一次朗读的中间。调用 resume 或 stop 会取消暂停朗读。

resume

chrome.tts.resume()

如果朗读暂停了，从暂停的位置恢复朗读。

isSpeaking

chrome.tts.isSpeaking(function callback)

检查引擎当前是否正在朗读。在 Mac OS X 中，只要系统的语音引擎正在朗读，即使此次朗读并不是由 Chrome 浏览器发起的，结果也是 true。

参数

callback ( optional function )

如果您指定了 callback 参数，它应该指定一个如下形式的函数： 

function(boolean speaking) {...};

speaking ( boolean )

如果正在朗读则为 true ，否则为 false。

getVoices

chrome.tts.getVoices(function callback)

获得包含所有可用语音的数组。

参数

callback ( optional function )

如果您指定了 callback 参数，它应该指定一个如下形式的函数： 

function(array of TtsVoice voices) {...};

voices ( array of TtsVoice )

包含 TtsVoice 对象的数组，代表语音合成可用的语音。