命令和响应
本文介绍使用WebSocket接口以流式方式发送音频数据时的命令和响应。
客户端使用下表中的命令向API发送开始/结束语音识别的请求以及发送数据。发送s和e命令后需等待API的响应再发送下一个命令。发生错误时会返回错误响应。
| 名称 | 说明 |
|---|---|
| s命令 | 客户端发送的语音识别请求命令 |
| p命令 | 客户端发送音频数据的命令 |
| e命令 | 客户端发送结束语音识别请求的命令 |
API会根据处理进度返回下表中的事件。
| 名称 | 说明 |
|---|---|
| S事件 | 通知语音检测进程检测到语音开始的事件 |
| E事件 | 通知语音检测进程检测到语音结束的事件 |
| C事件 | 通知语音识别进程开始语音识别的事件 |
| U事件 | 通知语音识别进程中间结果的事件 |
| A事件 | 通知语音识别进程完成识别并返回结果的事件 |
| G事件 | 通知服务器生成的信息的事件。未使用相关功能时不会发生。 |
使用音频流的应用程序的命令和事件的一般流程如下图所示。
S和E事件是语音检测的结果，C、U和A事件是语音识别的结果。根据语音段的长度和基础系统的繁忙程度，事件的顺序可能会有所不同。例如，在上图中C出现在S和E之间，但也可能出现在E之后。
这里以一个音频数据中语音检测检测到3个语音段的情况为例进行说明。
下面使用日志来说明当通过WebSocket接口从流式数据源每秒向API发送1秒数据时，客户端发送命令和API响应事件的流程。
- 以
command>>>开头的行是客户端发送的命令 - 以
message<<<开头的行是API返回的响应事件
完整日志如下。为了便于查看，API返回的事件已高亮显示。
0:00:00.000 open> wss://acp-api.amivoice.com/v1/
0:00:00.161 open # WebSocket连接
0:00:00.161 command>>> s 16k -a-general segmenterProperties="useDiarizer=1" resultUpdatedInterval=1000 authorization=XXXXXXXXXXXXXXXX
0:00:00.226 message<<< s # 语音识别请求s命令的响应
0:00:00.226 command>>> p [..(32000 bytes)..] # 发送第1秒数据
0:00:01.232 command>>> p [..(32000 bytes)..] # 发送第2秒数据
0:00:02.236 command>>> p [..(32000 bytes)..] # 发送第3秒数据
0:00:03.241 command>>> p [..(32000 bytes)..] # 发送第4秒数据
0:00:04.245 command>>> p [..(32000 bytes)..] # 发送第5秒数据
0:00:05.250 command>>> p [..(32000 bytes)..] # 发送第6秒数据
0:00:06.254 command>>> p [..(32000 bytes)..] # 发送第7秒数据
0:00:07.257 command>>> p [..(32000 bytes)..] # 发送第8秒数据
0:00:07.291 message<<< S 6200 # [语音1] 在6.2秒检测到语音开始
0:00:07.297 message<<< C # [语音1] 开始语音识别处理
0:00:08.262 command>>> p [..(32000 bytes)..] # 发送第9秒数据
0:00:08.315 message<<< E 7450 # [语音1] 在7.45秒检测到语音结束
0:00:08.315 message<<< U {...} # [语音1] 中间结果
0:00:08.446 message<<< A {...} # [语音1] 语音段结果
0:00:09.267 command>>> p [..(32000 bytes)..] # 发送第10秒数据
0:00:10.270 command>>> p [..(32000 bytes)..] # 发送第11秒数据
0:00:10.309 message<<< S 8600 # [语音2] 在8.6秒检测到语音开始
0:00:10.327 message<<< C # [语音2] 开始语音识别处理
0:00:11.272 command>>> p [..(32000 bytes)..] # 发送第12秒数据
0:00:11.337 message<<< U {...} # [语音2] 中间结果
0:00:12.274 command>>> p [..(32000 bytes)..] # 发送第13秒数据
0:00:12.321 message<<< U {...} # [语音2] 中间结果
0:00:13.277 command>>> p [..(32000 bytes)..] # 发送第14秒数据
0:00:13.301 message<<< E 11650 # [语音2] 在11.65秒检测到语音结束
0:00:13.304 message<<< S 12000 # [语音3] 在12.00秒检测到语音开始
0:00:13.311 message<<< U {...} # [语音3] 中间结果
0:00:13.343 message<<< A {...} # [语音3] 语音段结果
0:00:14.282 command>>> p [..(32000 bytes)..] # 发送第15秒数据
0:00:14.336 message<<< C # [语音3] 开始语音识别处理
0:00:15.287 command>>> p [..(32000 bytes)..] # 发送第16秒数据
0:00:15.344 message<<< U {...} # [语音3] 中间结果
0:00:16.289 command>>> p [..(32000 bytes)..] # 发送第17秒数据
0:00:16.337 message<<< U {...} # [语音3] 中间结果
0:00:17.291 command>>> p [..(22968 bytes)..] # 发送第18秒数据
0:00:17.345 message<<< U {...} # [语音3] 中间结果
0:00:18.297 command>>> e # 音频发送完毕，发送e命令结束会话
0:00:18.341 message<<< U {...} # [语音3] 中间结果
0:00:18.347 message<<< E 17700 # [语音3] 在17.70秒检测到语音结束
0:00:18.347 message<<< U {...} # [语音3] 中间结果
0:00:18.512 message<<< A {...} # [语音3] 语音段结果
0:00:18.574 message<<< e # 会话结束响应
0:00:18.574 close> # 客户端关闭WebSocket
0:00:18.595 close # WebSocket关闭响应
下面按步骤进行说明。
首先，通过WebSocket连接到AmiVoice API的 endpoint，然后使用s命令发送语音识别请求。API会返回s命令的响应。
0:00:00.000 open> wss://acp-api.amivoice.com/v1/
0:00:00.161 open # WebSocket连接
0:00:00.161 command>>> s 16k -a-general segmenterProperties="useDiarizer=1" resultUpdatedInterval=1000 authorization=XXXXXXXXXXXXXXXX
0:00:00.226 message<<< s # 语音识别请求s命令的响应
请求成功后，客户端通过p命令每秒发送一次音频数据。在发送第8秒数据后，API发送了S(检测到语音)事件。
0:00:00.226 command>>> p [..(32000 bytes)..] # 发送第1秒数据
0:00:01.232 command>>> p [..(32000 bytes)..] # 发送第2秒数据
0:00:02.236 command>>> p [..(32000 bytes)..] # 发送第3秒数据
0:00:03.241 command>>> p [..(32000 bytes)..] # 发送第4秒数据
0:00:04.245 command>>> p [..(32000 bytes)..] # 发送第5秒数据
0:00:05.250 command>>> p [..(32000 bytes)..] # 发送第6秒数据
0:00:06.254 command>>> p [..(32000 bytes)..] # 发送第7秒数据
0:00:07.257 command>>> p [..(32000 bytes)..] # 发送第8秒数据
0:00:07.291 message<<< S 6200 # [语音1] 在6.2秒检测到语音开始
之后，依次收到C(开始语音识别)、A(语音段结果)事件。另外，在中间还收到了表示在7.45秒检测到语音结束的E(检测到语音结束)事件。由于在s命令连接时设置了resultUpdatedInterval=1000，所以每秒会收到一次U(中间结果)。
0:00:07.297 message<<< C # [语音1] 开始语音识别处理
0:00:08.262 command>>> p [..(32000 bytes)..] # 发送第9秒数据
0:00:08.315 message<<< E 7450 # [语音1] 在7.45秒检测到语音结束
0:00:08.315 message<<< U {...} # [语音1] 中间结果
0:00:08.446 message<<< A {...} # [语音1] 语音段结果
之后，对剩余的2个语音重复进行语音检测和语音识别处理。
音频数据发送完成后，发送e命令结束会话。API在完成所有语音检测和语音识别处理后，会返回e事件作为会话结束的响应。
0:00:18.297 command>>> e # 音频发送完毕，发送e命令结束会话
0:00:18.341 message<<< U {...} # [语音3] 中间结果
0:00:18.347 message<<< E 17700 # [语音3] 在17.70秒检测到语音结束
0:00:18.347 message<<< U {...} # [语音3] 中间结果
0:00:18.512 message<<< A {...} # [语音3] 语音段结果
0:00:18.574 message<<< e # 会话结束响应
0:00:18.574 close> # 客户端关闭WebSocket
0:00:18.595 close # WebSocket关闭响应
关于这个18秒会话的整体情况，请参阅前面日志中的注释说明。
A和U事件的响应中包含结果。详情请参阅语音识别结果格式。关于WebSocket的命令和事件，也请参阅WebSocket 接口。
上述日志中的命令和事件序列如下图所示。该图中省略了p命令。
错误响应
如果客户端发送的s 命令、p命令、e命令由于某些原因失败，例如命令发送顺序错误、触发限制事项、基盘出现问题等，可能会返回包含错误消息的错误响应。
成功响应
s
p
e
错误响应
s 错误消息
p 错误消息
e 错误消息
在出现错误响应的情况下，系统将回到发送s命令前的初始状态。请再次从s命令开始发送请求。详细信息请参考数据包和状态转换中的语音供给状态转换图。
请参考错误消息，如果是客户端错误，请修正原因后再次发送请求；如果是AmiVoice API基盘的服务器错误，请稍等片刻后再次发送请求。关于由于限制事项导致的错误，请参考限制事项。有关错误消息的详细信息，请参考以下内容：
为了应对s命令的服务器错误或意外的网络传输错误等问题，重试s命令直到成功是有效的。在这种情况下，通过使用环形缓冲区等方法来防止丢失来自流式音源的音频，可以创建更加健壮的应用程序。