说明
使用 chrome.ttsEngine
API 通过扩展程序实现文本转语音(TTS) 引擎。如果您的扩展程序使用此 API 注册,那么当任何扩展程序或 Chrome 应用使用 tts
API 生成语音时,该扩展程序将收到包含待说出的话语和其他参数的事件。然后,您的扩展程序可以使用任何可用的网络技术来合成并输出语音,并将事件发送回调用函数以报告状态。
权限
ttsEngine
概览
扩展程序可以将自己注册为语音引擎。这样,它就可以拦截对 tts.speak
和 tts.stop
等函数的部分或全部调用,并提供替代实现。扩展程序可以自由使用任何可用的 Web 技术来提供语音,包括从服务器流式传输音频、HTML5 音频。扩展程序甚至可以对这些语音内容执行其他操作,例如在弹出式窗口中显示字幕,或将其作为日志消息发送到远程服务器。
清单
如需实现 TTS 引擎,扩展程序必须声明“ttsEngine”权限,然后在扩展程序清单中声明其提供的所有语音,如下所示:
{
"name": "My TTS Engine",
"version": "1.0",
"permissions": ["ttsEngine"],
"tts_engine": {
"voices": [
{
"voice_name": "Alice",
"lang": "en-US",
"event_types": ["start", "marker", "end"]
},
{
"voice_name": "Pat",
"lang": "en-US",
"event_types": ["end"]
}
]
},
"background": {
"page": "background.html",
"persistent": false
}
}
扩展程序可以指定任意数量的语音。
voice_name
为必需参数,名称应具有足够的描述性,能够指明语音的名称和所使用的引擎。在极少数情况下,如果两个扩展程序注册了同名的语音,客户端可以指定应执行合成的扩展程序的 ID。
lang
参数是可选的,但强烈建议您使用。几乎在所有情况下,一个语音只能合成一种语言的语音。当引擎支持多种语言时,它可以轻松为每种语言注册单独的声音。在极少数情况下,单个语音可以处理多种语言,最简单的方法就是列出两个单独的语音,并在内部使用相同的逻辑进行处理。不过,如果您想创建可处理任何语言语音的语音,请从扩展程序的清单中去掉 lang
参数。
最后,如果引擎可以发送事件来更新客户端的语音合成进度,则必须使用 event_types
参数。强烈建议至少支持 'end'
事件类型,以指示语音何时结束,否则 Chrome 将无法调度队列中的语音指令。
加载后,扩展程序可以通过调用 chrome.ttsEngine.updateVoices
来替换声明的语音列表。(请注意,对 updateVoices
进行程序化调用时使用的参数采用驼峰式命名法:例如voiceName
,而清单文件使用 voice_name
。)
您可以发送的可能事件类型与 speak()
方法收到的事件类型相对应:
'start'
:引擎已开始读出该语音内容。'word'
:达到了字词边界。使用event.charIndex
确定当前语音位置。'sentence'
:达到了句子边界。使用event.charIndex
确定当前语音位置。'marker'
:达到了 SSML 标记。使用event.charIndex
确定当前语音位置。'end'
:引擎已说完该语句。'error'
:发生了特定于引擎的错误,无法读出此语音指令。在event.errorMessage
中传递更多信息。
'interrupted'
和 'cancelled'
事件并非由语音引擎发送;而是由 Chrome 自动生成的。
假设您已按照下文所述注册语音事件监听器,文本转语音客户端可以通过调用 tts.getVoices
从扩展程序的清单中获取语音信息。
处理语音事件
如需根据客户端请求生成语音,您的扩展程序必须为 onSpeak
和 onStop
注册监听器,如下所示:
const speakListener = (utterance, options, sendTtsEvent) => {
sendTtsEvent({type: 'start', charIndex: 0})
// (start speaking)
sendTtsEvent({type: 'end', charIndex: utterance.length})
};
const stopListener = () => {
// (stop all speech)
};
chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);
是否向扩展程序发送给定语音请求的决定仅取决于扩展程序是否在其清单中支持给定的语音参数,以及是否已为 onSpeak
和 onStop
注册监听器。换句话说,扩展程序无法接收语音请求并动态决定是否处理该请求。
类型
AudioBuffer
包含音频缓冲区和关联数据的参数。
属性
-
audioBuffer
ArrayBuffer
文字转语音引擎中的音频缓冲区。其长度应与 audioStreamOptions.bufferSize 完全相同,并以音频流选项的采样率编码为单声道,以及以线性 PCM 编码为 32 位有符号浮点,即 JavaScript 中的 Float32Array 类型。
-
charIndex
number 可选
与此音频缓冲区关联的字符索引。
-
isLastBuffer
布尔值(可选)
如果此音频缓冲区是正在朗读的文本的最后一个,则为 true。
AudioStreamOptions
包含引擎预期生成的音频流格式。
属性
-
bufferSize
数值
音频缓冲区中的样本数。
-
sampleRate
数值
音频缓冲区中预期的采样率。
LanguageInstallStatus
语音的安装状态。
枚举
"notInstalled"
“installing”
"已安装"
"失败"
LanguageStatus
语言的安装状态。
属性
-
错误
字符串(选填)
有关安装失败的详细信息。如果语言安装失败,则可选择填充。
-
installStatus
安装状态。
-
lang
字符串
语言代码区域代码形式的语言字符串,其中区域可以省略。例如 en、en-AU、zh-CH。
LanguageUninstallOptions
用于卸载给定语言的选项。
属性
-
uninstallImmediately
布尔值
如果 TTS 客户端希望立即卸载语言,则为 True。引擎可能会根据此参数和请求方信息选择是否以及何时卸载语言。如果为 false,则系统可能会使用其他条件(例如近期使用情况)来确定何时卸载。
SpeakOptions
向 tts.speak() 方法指定的选项。
属性
-
gender
VoiceGender 选填
自 Chrome 92 起弃用Gender 已被弃用,将被忽略。
合成语音的语音性别。
-
lang
字符串(选填)
用于合成的语言,格式为“语言-区域”。示例:“en”“en-US”“en-GB”“zh-CN”。
-
投球
number 可选
语音音调介于 0 到 2 之间(包括这两个数值),其中 0 表示最低,2 表示最高。1.0 对应于此语音的默认音调。
-
费率
number 可选
与此语音的默认语速相比的语速。1.0 是默认速率,通常为每分钟 180 到 220 个字左右。2.0 表示快一倍的速度,0.5 则表示原有速度的一半。此值保证介于 0.1 到 10.0 之间(包括这两个数值)。如果某个语音不支持此完整速率范围,请勿返回错误。而是将速率剪裁到语音支持的范围。
-
voiceName
字符串(选填)
用于合成的语音的名称。
-
音量
编号(选填)
讲话音量,介于 0 到 1 之间(包括这两个数值),其中 0 表示最低音量,1 表示最高音量,默认值为 1.0。
TtsClient
请求状态的客户端的标识符。
属性
-
id
字符串
发出语言管理请求的客户端。对于扩展程序,这是唯一的扩展程序 ID。对于 Chrome 功能,这是用户能够看懂的功能名称。
-
请求者的类型。
TtsClientSource
请求者的类型。
枚举
"chromefeature"
"extension"
VoiceGender
Gender 已被弃用,将被忽略。
枚举
“male”
“female”
方法
updateLanguage()
chrome.ttsEngine.updateLanguage(
status: LanguageStatus,
)
在尝试安装语言和卸载语言时由引擎调用。也用于响应来自客户的状态请求。安装或卸载语音时,引擎还应调用 ttsEngine.updateVoices 以注册语音。
参数
-
语言的安装状态。
updateVoices()
chrome.ttsEngine.updateVoices(
voices: TtsVoice[],
)
由引擎调用以更新其语音列表。此列表会替换此扩展程序清单中声明的所有语音。
参数
-
声音
TtsVoice[]
表示可用于语音合成的可用语音的
tts.TtsVoice
对象数组。
事件
onInstallLanguageRequest
chrome.ttsEngine.onInstallLanguageRequest.addListener(
callback: function,
)
当 TTS 客户端请求安装新语言时触发。引擎应尝试下载并安装语言,并使用结果调用 ttsEngine.updateLanguage。成功后,引擎还应调用 ttsEngine.updateVoices 以注册新推出的语音。
参数
-
callback
函数
callback
参数如下所示:(requestor: TtsClient, lang: string) => void
-
要求提出者
-
lang
字符串
-
onLanguageStatusRequest
chrome.ttsEngine.onLanguageStatusRequest.addListener(
callback: function,
)
当 TTS 客户端请求语言的安装状态时触发。
参数
-
callback
函数
callback
参数如下所示:(requestor: TtsClient, lang: string) => void
-
要求提出者
-
lang
字符串
-
onPause
chrome.ttsEngine.onPause.addListener(
callback: function,
)
可选:如果引擎支持暂停事件,则应暂停当前正在说出的语音(如果有),直到收到恢复事件或停止事件。请注意,停止事件也应清除暂停状态。
参数
-
callback
函数
callback
参数如下所示:() => void
onResume
chrome.ttsEngine.onResume.addListener(
callback: function,
)
可选:如果引擎支持暂停事件,则也应支持恢复事件,以继续说出当前的语音(如果有)。请注意,停止事件也应清除暂停状态。
参数
-
callback
函数
callback
参数如下所示:() => void
onSpeak
chrome.ttsEngine.onSpeak.addListener(
callback: function,
)
当用户调用 tts.speak() 且此扩展程序清单中的某个语音最先与 options 对象匹配时调用。
参数
-
callback
函数
callback
参数如下所示:(utterance: string, options: SpeakOptions, sendTtsEvent: function) => void
-
话语
字符串
-
选项
-
sendTtsEvent
函数
sendTtsEvent
参数如下所示:(event: tts.TtsEvent) => void
-
事件
来自文本转语音引擎的事件,用于指示此语音的状态。
-
-
onSpeakWithAudioStream
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
callback: function,
)
当用户调用 tts.speak() 且此扩展程序清单中的某个语音最先与 options 对象匹配时调用。与 ttsEngine.onSpeak 不同,Chrome 提供音频播放服务并处理调度 TTS 事件。
参数
-
callback
函数
callback
参数的格式为:(utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void
-
话语
字符串
-
选项
-
audioStreamOptions
-
sendTtsAudio
函数
sendTtsAudio
参数的格式为:(audioBufferParams: AudioBuffer) => void
-
audioBufferParams
包含音频缓冲区和关联数据的参数。
-
-
sendError
函数
Chrome 94 及更高版本sendError
参数如下所示:(errorMessage?: string) => void
-
errorMessage
字符串(可选)
用于描述错误的字符串。
-
-
onStop
chrome.ttsEngine.onStop.addListener(
callback: function,
)
当对 tts.stop 进行调用且此扩展程序可能正在说话时触发。如果扩展程序收到对 onStop 的调用,并且语音已停止,则应不执行任何操作(不引发错误)。如果语音处于暂停状态,此操作应该会取消暂停状态。
参数
-
callback
函数
callback
参数如下所示:() => void
onUninstallLanguageRequest
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
callback: function,
)
在 TTS 客户端指示不再需要某语言时触发。
参数
-
callback
函数
callback
参数如下所示:(requestor: TtsClient, lang: string, uninstallOptions: LanguageUninstallOptions) => void
-
要求提出者
-
lang
字符串
-
uninstallOptions
-