WebSocket 接口
要使用 IBM Watson® Text to Speech 服务的 WebSocket 接口将文本合成为语音,可首先通过调用其 /v1/synthesize
方法来建立与服务的连接。 然后,通过该连接将要合成的文本作为 JSON 文本消息发送到服务。 服务完成请求处理后,会自动关闭该 WebSocket 连接。
合成请求和响应周期包含以下步骤:
WebSocket 接口接受的输入和生成的结果与 HTTP 接口的 GET
和 POST /v1/synthesize
方法完全相同。 此外,WebSocket 界面还支持使用SSML <mark>
元素来识别音频中用户指定标记的位置。 此接口还可以返回输入文本中所有字符串的计时信息。 ( <mark>
元素和单词时间仅在 WebSocket 界面可用。)
以下示例代码片段是用 JavaScript 编写的,并基于 HTML5 WebSocket API。 如需了解有关 WebSocket 协议的更多信息,请参阅互联网工程任务组(IETF) 意见征询(RFC)6455。
打开连接
可以通过 WebSocket Secure (WSS) 协议调用 /v1/synthesize
方法来打开与服务的连接。 此方法在以下端点可用:
wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}/v1/synthesize
其中 {location}
指示应用程序的托管位置:
us-south
表示达拉斯us-east
表示华盛顿eu-de
表示法兰克福au-syd
表示悉尼jp-tok
表示东京eu-gb
表示伦敦kr-seo
表示首尔
{instance_id}
是服务实例的唯一标识。
文档中的示例将 wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}
缩写为 {ws_url}
。 因此,所有 WebSocket 示例都将此方法称为 {ws_url}/v1/synthesize
。
一个 WebSocket 客户端调用 /v1/synthesize
方法,并带有以下查询参数,以与服务建立经过身份验证的连接:
access_token
(所需 string)-
传递有效的访问令牌以向服务认证。 必须使用未到期的访问令牌。
- IBM Cloud通过Identity and Access Management(IAM)访问令牌来验证服务。 通过调用传递的是 IAM 访问令牌,而不是传递 API 密钥。 更多信息,请参见 验证至 IBM Cloud。
- IBM Cloud Pak for Data 传递访问令牌,就像在xml-ph-0001@deepl.internal请求中传递xml-ph-0000@deepl.internal标头一样。IBM Software Hub 传递访问令牌,就像在 请求中传递 标头一样。HTTP
Authorization
更多信息,请参见 验证至 IBM Cloud Pak for Data。
voice
(可选的 string)-
指定音频中读文本的声音。 使用
/v1/voices
方法来获取受支持声音的当前列表。 省略参数,使用默认语音。 有关更多信息,请参阅 语言和语音 以及 使用默认语音。 customization_id
(可选的 string)-
指定用于合成的定制模型的全局唯一标识符(GUID)。 指定的定制模型必须与用于合成的声音的语言相匹配。 如果包含定制标识,那么必须使用拥有定制模型的服务实例的凭证来发出请求。 省略此参数可使用没有任何定制的指定声音。 有关更多信息,请参阅了解定制。
rate_percentage
(可选的 integer)-
指定整个合成请求的全局发言速率。 语速是指服务将文本合成为语音的速度。 语速越快,文字说得越快;语速越低,文字说得越慢。 该参数可更改整个请求的每个语音默认费率。 更多信息,请参阅 修改发言速率。
pitch_percentage
(可选的 integer)-
指定整个合成请求的全局发言音高。 说话音调代表服务合成的语音语调。 它表示听者感受到的声音音调的高低。 音调越高,语音语调越高;音调越低,语音语调越低。 该参数可更改整个请求中每个声部的默认音高。 更多信息,请参阅 修改说话音调。
spell_out_mode
(可选的 string)-
*对于德语语音,*指定字符串中各个字符的拼写方式。 默认情况下,该服务拼写单个字符的速度与合成语言文本的速度相同。 You can use the parameter to direct the service to spell out individual characters more slowly, in groups of one (
singles
), two (pairs
), or three (triples
). For more information, see 指定字符串的拼写方式. x-watson-metadata
(可选的 string)-
将客户标识与通过连接传递的数据相关联。 此参数接受自变量
customer_id={id}
,其中id
是要与数据关联的随机或通用字符串。 必须对该自变量进行 URL 编码,以转入该参数,例如customer_id%3dmy_customer_ID
。 缺省情况下,没有客户标识与数据相关联。 有关更多信息,请参阅信息安全。 x-watson-learning-opt-out
(可选的 boolean)-
IBM Cloud 指示服务是否记录通过连接发送的请求和结果。 要阻止 IBM 访问您的数据以进行一般服务改进,请为此参数指定
true
。 选择退出会指示IBM在磁盘中不写入您请求的用户数据(文本或音频)。 您也可以在账户级别选择退出。 有关更多信息,请参阅请求日志记录。
以下 JavaScript 代码片段将打开与服务的连接。 对 /v1/synthesize
方法的调用传递了 voice
和 access_token
查询参数,前者指示服务使用美国英语 Allison 声音。 连接建立后,事件侦听器(onOpen()
、onClose()
等)被定义为响应服务中的事件。
var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
+ '?access_token=' + access_token
+ '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);
websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };
发送输入文本
为了合成文本,客户端向服务发送一个简单的JSON文本消息,并附带以下参数:
text
(所需 string)-
提供要合成的文本。 客户机可以传递纯文本或使用语音合成标记语言 (SSML) 进行注释的文本。 客户机在请求中最多可传递 5 KB 的输入文本。 此限制包括指定的任何 SSML。 有关更多信息,请参阅指定输入文本及其后面的各部分内容。 (SSML输入还可以包含
<mark>
元素。 有关更多信息,请参阅 指定 SSML 标记。) accept
(所需 string)-
指定请求的音频格式(MIME 类型)。 使用
*/*
可请求缺省音频格式audio/ogg;codecs=opus
。 更多信息,请参阅 使用音频格式。Safari 浏览器不支持 Ogg 音频格式。 如果您在 Safari 浏览器上使用Text to Speech服务,则必须指定不同的格式,以便服务返回音频。
timings
(可选的 string[ ])-
指定服务将返回输入文本中所有字符串的词计时信息。 服务会返回输入中每个标记的开始时间和结束时间。 将
words
指定为数组的唯一元素,以请求词计时。 指定空数组或省略此参数时,不会收到任何词计时信息。 更多信息,请参阅 生成字定时。 不支持日语输入文本。
以下 JavaScript 代码片段将简单的“Hello world”消息作为输入文本传递,并请求音频的缺省格式。 这些呼叫包含在 onOpen()
功能中,该功能是为客户定义的,以确保仅在连接建立后才发送呼叫。
function onOpen(evt) {
var message = {
text: 'Hello world',
accept: '*/*'
};
websocket.send(JSON.stringify(message));
}
服务通过发送用于确认音频响应格式的文本消息来响应此消息。 以下响应将确认缺省音频格式。
{
'binary_streams': [
{
content_type: 'audio/ogg;codecs=opus'
}
]
}
接收响应
服务确认音频格式后,会将合成音频作为所示格式的二进制数据流发送。 对于包含头的音频格式(例如,audio/wav
和 audio/ogg
),服务会在发送音频数据之前返回该头。 该头可以跨多个二进制响应。 对于所有音频格式,客户机都需要附加所有来自服务的二进制响应,以组合成完整的音频响应。
除了发送确认请求的音频格式的文本消息外,服务还可以发送包含警告或错误的文本消息。 在以下情况下,服务还会发送包含计时信息的一个或多个文本消息:
- 输入文本包含一个或多个SSML
<mark>
元素。 - 在请求中指定了
timings
参数。
客户机可以通过响应或显示文本消息,或者通过捕获文本消息供应用程序使用(例如,如果消息包含标记位置),对这些消息进行处理。
当服务完成输入文本合成并发送所有二进制和文本消息后,会自动关闭 WebSocket 连接。 以下简单的 onMessage()
函数根据文本和二进制消息的类型,将它们从服务中接收并附加到相应的变量中。 当 onClose()
函数执行时,已收到整个音频流,并且服务不会发送进一步的二进制或文本消息。
var messages;
var audioStream;
function onMessage(evt) {
if (typeof evt.data === string) {
messages += evt.data;
} else {
console.log('Received ' + evt.data.size() + ' binary bytes');
audioStream += evt.data;
}
}
function onClose(evt) {
// The service's response is complete.
}
WebSocket 返回码
服务可以通过 WebSocket 连接向客户机发送以下返回码:
1000
指示连接正常关闭,这意味着已实现建立连接的目的。1002
指示由于协议错误,服务正在关闭连接。1006
指示连接异常关闭。1009
指示帧大小超过 4 MB 限制。1011
指示服务正在终止连接,因为服务遇到了阻止其执行请求的意外状况,例如无效自变量。 此返回码还可能指示输入文本太大。
如果套接字关闭并返回错误,那么在关闭之前,服务会向客户机发送格式为 {"error": "Specific error message"}
的参考消息。 此外,对于未知参数,服务会发送非致命警告消息。 有关 WebSocket 返回代码的更多信息,请参阅互联网工程任务组(IETF) 意见征询(RFC)6455。
SDK 的WebSocket实现可以返回不同或额外的响应代码。
示例错误和警告消息
以下示例显示了错误响应。 它们包括来自客户端 onClose()
回调方法的JSON文本消息和格式化消息。 格式化消息以布尔值 true
开头,因为连接已关闭。 此外,还包含导致关闭的 WebSocket 错误代码。
-
以下示例显示了有关
accept
参数自变量无效的错误消息:{ "error": "Unsupported mimetype. Supported mimetypes are: ['application/json', 'audio/flac', ...]" } (True, 1011, u'see the previous message for the error details.')
-
以下示例显示了有关缺少
text
参数的错误消息:{ "error": "Required parameter \"text\" is missing." } (True, 1011, u'see the previous message for the error details.')
以下示例显示了警告响应,在本例中是有关名为 invalid-parameter
的参数未知的警告响应。 响应中并未包含第二条消息,因为该警告未导致连接关闭。
{
"warnings": "Unknown arguments: invalid-parameter."
}