说明
使用 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
枚举
"start"
"end"
"字词"
"sentence"
"标记"
“中断”
"cancelled"
"错误"
“暂停”
"继续"
TtsEvent
来自 TTS 引擎的事件,用于传达话语的状态。
属性
-
charIndex
编号(选填)
话语中当前字符的索引。对于字词事件,事件会在一个字词结束且下一个字词开始之前触发。
charIndex
表示文本中下一个要说出的字词开头的点。 -
错误消息
字符串(可选)
事件类型为
error
时的错误说明。 -
长度
编号(选填)
Chrome 74 及更高版本话语下一部分的长度。例如,在
word
事件中,这是接下来要说的字词的长度。如果语音引擎未设置,则将其设置为 -1。 -
类型
类型可以是
start
,当语音开始时立即;达到单词边界时为word
;到达句子边界时为sentence
;当到达 SSML 标记元素时,为marker
;当话语到达结束时,为end
;当话语在到达结束之前停止或中断时,为interrupted
;当话语尚未合成时从队列中移除,或者当发生任何其他错误时,为error
。cancelled
暂停语音时,如果在中间暂停特定话语,则会触发pause
事件;如果话语恢复说话,则会触发resume
事件。请注意,如果语音在语音切换间隙暂停,则暂停和恢复事件可能不会触发。
TtsOptions
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) => {...}
-
事件
来自文字转语音引擎的更新事件,用于指示此话语的状态。
-
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
Gender 已被弃用,并会被忽略。
枚举
“男性”
“女性”
方法
getVoices()
chrome.tts.getVoices(
callback?: function,
)
获取所有可用语音的数组。
参数
-
callback
函数(可选)
callback
参数如下所示:(voices: TtsVoice[]) => void
-
声音
TtsVoice[]
tts.TtsVoice
对象数组,表示可用于语音合成的语音。
-
返回
-
Promise<TtsVoice[]>
Chrome 浏览器 101 及以上版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
isSpeaking()
chrome.tts.isSpeaking(
callback?: function,
)
检查引擎当前是否在说话。在 Mac OS X 上,只要系统语音引擎正在说话,结果就会为真,即使语音并非由 Chrome 发起也是如此。
参数
-
callback
函数(可选)
callback
参数如下所示:(speaking: boolean) => void
-
说话
布尔值
如果说话则为 true,否则为 false。
-
返回
-
Promise<boolean>
Chrome 浏览器 101 及以上版本Manifest V3 及更高版本支持 Promise,但为以下项目提供回调: 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。
pause()
chrome.tts.pause()
暂停语音合成(可能会在语音或语音合成期间暂停)。呼吁恢复或停止说话,即可取消暂停语音。
resume()
chrome.tts.resume()
如果语音暂停,系统会从中断的地方继续讲话。
speak()
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.tts.onVoicesChanged.addListener(
callback: function,
)
在 getVoices 返回的 tts.TtsVoice
列表发生更改时调用。
参数
-
callback
函数
callback
参数如下所示:() => void