WebSocketAPI接入

## 示例代码

[WebSocket DEMO](https://gitee.com/xiaosumay/DemoCode/tree/master/websocket)

## 接口说明

>接口是短连接，每次交互要新建连接，会话完成后，讯飞断开连接。单次会话过程中支持流式交互（客户端不断上传音频数据，讯飞不断下发结果）

交互时序图：
1. 设备有vad功能：
![](https://aiui-file.cn-bj.ufileos.com/vad.png)

2. 设备无vad功能，依赖云端vad：
![](https://aiui-file.cn-bj.ufileos.com/novad.png)

## 建立连接
WebSocket握手阶段鉴权，参数在url中指定。
握手成功后：1. 连接>60s超时,讯飞断开连接
2. >10s无数据交互，讯飞断开连接。

### 请求地址
	ws[s]://wsapi.xfyun.cn/v1/aiui

### 请求参数

> 参数格式： 需 url encode

key1=value1&key2=value2…

> 请求示例：

ws[s]://wsapi.xfyun.cn/v1/aiui?appid=xxx&checksum=xxx&curtime=xxx&param=xxx

> 参数说明：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|appid | string | 是 | AIUI开放平台注册申请应用的应用ID(appid) | 594bxxc3 |
|curtime | string | 是 | 当前UTC时间戳，从1970年1月1日0点0 分0 秒开始到现在的秒数 | 1502607694 |
|signtype | string | 否 | 签名算法，可选 md5（默认），sha256 |
|checksum | string | 是 | 令牌，生成方法：(appkey + curtime + param拼接字符串)，根据signtype参数的算法加密 | 02607694eyjzy2vuzsi6im1haw4ifq |
|param | string | 是 | 参数用 Base64 编码后的字符串，详见 param 字段说明 | eyJzY2VuZSI6Im1haW4ifQ== |

*注：*
* appkey：接口密钥，在 AIUI 开放平台查看；
* checksum 有效期：  5 分钟(用curtime计算)， curtime必须是东八区标准时间，否则无效；
* BASE64 编码采用 MIME 格式，编码后大小增加约1/3

**checksum**生成示例，假设加密算法为 md5：
~~~ java
String apikey="abcd1234";
String curtime="1502607694";
String param="eyAiYXVmIjogImF1ZGlvL0wxNjtyYXR...";
String checksum=MD5(apikey+curtime+param);
~~~

### param 字段详细说明
参数用Base64 编码后得到param，原始参数说明：

#### 通用配置参数：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|scene | string | 是 | 情景模式 | main |
|auth_id | string | 是 | 设备唯一ID（鉴权），自定义的**32位**字符串，包括英文小写字母与数字| 2049a1b2fdedae553bd03ce6f4820ac4|
|data_type | string | 是 | 上传数据类型： text（文本） audio（音频）| text |
|interact_mode | string | 否 | 交互模式: continuous（一次唤醒，持续交互） oneshot（一次唤醒，一次交互） | continuous |
|close_delay| string | 否 | 交互完成后，云端延迟关闭连接时间，单位ms。取值范围：[0,200] ||
|sn | string | 否 | 唯一设备id，推荐公司名+mac地址。使用音乐时需要与音乐设备注册激活请求的sn值一样 |iflytek-00:09:5B:EC:EE:F2 |

#### 语义参数：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|lat | string | 否 | 纬度，用于地理定位| 31.83 |
|lng | string | 否 | 经度，用于地理定位| 117.14 |
|topn | string | 否 | 多候选词 | 2 |
|pers_param | string | 否 |动态实体生效范围： 用户级（auth_id） 应用级（appid） 自定义级。 | "{\\"auth_id\\":\\"xxxxxx\\"}" |
|clean_dialog_history | string | 否 | 清除交互历史： user（手动清除） auto（系统清除，默认） | user |

#### 识别参数：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|aue | string | 否 | 音频编码，可选： raw（默认，pcm或wav格式） speex（sample_rate=8000） speex-wb（宽频speex格式，sample_rate=16000） opus（sample_rate=8000） opus-wb（宽频opus格式，sample_rate=16000）
|sample_rate | string | 否 | 音频采样率：16000（默认）、8000
|speex_size | string | 否 | speex音频帧大小，speex音频必传。详见speex_size与speex库压缩等级关系表 |60 |
|result_level | string | 否 | 结果级别：plain（精简，默认），complete（完整）
|vad_info | string | 否 | 是否需要云端返回 vad 信息：end（末端点） | end |
|cloud_vad_eos | string | 否 | 后端点静音时长，单位ms | 700 |
|vrto | string | 否 | 无效交互等待时间（有音频但没识别结果），超时讯飞断开连接，单位ms | 10000 |

*speex_size与speex库压缩等级（quantity）关系表：*

|quantity（压缩等级）|0|1|2|3|4|5|6|7|8|9|10|
|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|:--|
|speex | 6 | 10 | 15 | 20 | 20 | 28 | 28 | 38 | 38 | 46 | 62 |
|speex-wb | 10 | 15 | 20 | 25 | 32 | 42 | 52 | 60 | 70 | 86 | 106 |

*opus编码说明：*
每个编码帧加上两个字节头信息存储编码帧长度，

"opus"编码

0                    1                   2                   
	   0  1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2
	   +--+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	   | 20 |     20字节压缩音频数据                  |
	   +--+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
"opus-wb"编码

0                    1                   2                       3                   4
	   0  1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2
	   +--+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	   |  40|                            40字节压缩音频数据                                       |  
	   +--+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

#### 所见即可说参数：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|iat_user_data| string | 是 | 所见即可说-识别，总长度<4000字节 | |
|nlp_user_data| string | 否 | 所见即可说-语义 ，总长度<4000字节| |

iat_user_data示例：

{
		"recHotWords":"播报内容|地图显示|路线优先",//会话级热词
		"sceneInfo":{}
	}

nlp_user_data示例：

{
		"res":[{
			"res_name":"vendor_applist",//资源名称
			"data":"xxxxx"//数据的base64编码
		}],
		"skill_name":"telephone"//对应的技能名称
	}

#### 合成参数（单合成scene=IFLYTEK.tts）：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|ent | string | 否 | 引擎类型| xtts |
|vcn | string | 是 | 发音人，[发音人列表](https://aiui-doc.xf-yun.com/project-1/doc-23/#支持的发音人)| x_xiaoyan |
|speed | string | 否 | 语速，取值范围：[0,100]，值越大语速越快。默认值：50| 50 |
|volume | string | 否 | 音量，取值范围：[0,100]。默认值：50| 50 |
|pitch | string | 否 | 语调，取值范围：[0,100]。默认值：50| 50 |
|tts_aue | string | 否 | 合成音频编码格式：，raw（pcm格式，默认），lame（mp3）|raw |
|tts_res_type | string | 否 | 合成音频下发格式，取值范围： url：以url链接形式流式下发音频，仅支持mp3格式，返回内容可参考文章接收结果部分的合成返回内容 url_v2：云端合成完毕后以url链接形式一次性下发音频，默认为mp3链接|url|

#### 语义后合成参数：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|context | string | 是（语义后合成必传）|json字符串，参数设置时注意转义符号不能丢，内容为"{\\"sdk_support\\":[\\"tts\\"]}" | "{\\"sdk_support\\":[\\"tts\\"]}"|

#### 翻译参数：

|参数|类型|必须|说明|示例|
|:-------------|:-------------|:-------------|:-------------|:-------------|
|from | string | 是 | 源语言： cn（中文） en（英文）| cn |
|to | string | 是 | 目标语言： cn（中文） en（英文） ug（维吾尔语） ja（日语） ko（韩语） fr（法语） es（西班牙语） ru（俄语）| en |

*X-Param生成示例：*

原始JSON串：
	{
		"scene":"main",
		"aue":"raw",
		"sample_rate":"16000",
		"pers_param":"{\"auth_id\":\"xxxxxx\"}",
		"data_type":"audio",
		"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4"
	}
	BASE64编码（即X-Param）：
	eyJzY2VuZSI6Im1haW4iLCJhdWUiOiJyYXciLCJzYW1wbGVfcmF0ZSI6IjE2MDAwIiwicGVyc19wYXJhbSI6IntcImF1dGhfaWRcIjpcInh4eHh4eFwifSIsImRhdGFfdHlwZSI6ImF1ZGlvIiwiYXV0aF9pZCI6IjIwNDlhMWIyZmRlZGFlNTUzYmQwM2NlNmY0ODIwYWM0In0=

*注：*

* vad 信息与开发者设置的尾静音时长（cloud_vad_eos）有关，默认700ms。云端对音频进行vad检测，发现静音时长超过该值时会返回vad信息。建议该值 > 600 ms。

*param生成示例：*

原始JSON串：
	{
		"scene":"main",
		"aue":"raw",
		"sample_rate":"16000",
		"data_type":"audio",
		"auth_id":"2049a1b2fdedae553bd03ce6f4820ac4"
	}
	BASE64编码（即 param）：
	eyJzY2VuZSI6Im1haW4iLCJhdWUiOiJyYXciLCJzYW1wbGVfcmF0ZSI6IjE2MDAwIiwiZGF0YV90eXBlIjoiYXVkaW8iLCJhdXRoX2lkIjoiMjA0OWExYjJmZGVkYWU1NTNiZDAzY2U2ZjQ4MjBhYzQifQ==

### 返回信息

> 成功：

{
	　　"action":"started",
	　　"code":"0",
	　　"data":"",
	　　"desc":"success",
	　　"sid":"awa00000001@ch27f00e2d00fe430100"
	}

> 失败：

{
		"action":"error",
		"code":"10114",
		"data":"",
		"desc":"time out|illegal curtime",
		"sid":"awa00000049@ch78170e55bcd92a0100"
	}

## 实时通信阶段

### 上传数据
客户端不断发数据给服务端，内容是音频或文本的二进制数据。注意，上传的总分片数<3000，且 speex 音频每次发送的字节数应为 speex_size 的整数倍。

### 上传结束符
客户端需发送结束标志，内容是字符串 `--end--` 的二进制数据。
注意：音频长度<60s，大小<2 MB，文本长度<1000 字节。

#### 识别结果（完整）
	{
		"action":"result",
		"code":"0",
		"data":{
			"sub":"iat",
			"auth_id":"xxx",
			"text":{
				"sn":1,
				"ls":false,
				"bg":0,
				"ed":0,
				"ws":[
					{"bg":0,"cw":[{"sc":0,"w":"今天"}]},
					{"bg":0,"cw":[{"sc":0,"w":"星期几"}]}]
			},
			"json_args":{
				"language":"zh-cn",
				"accent":"mandarin"
			},
			"result_id":1,
			"is_last":true,
			"is_finish":true
	　　},
	　　"desc":"success",
	　　"sid":"awa00000001@ch27f00e2d00fe430100"
	}

#### 识别结果（精简）

{
	　　"action":"result",
	　　"code":"0",
	　　"data":{
	　　　　"sub":"iat",
			"auth_id":"xxx",
			"text":"今天星期几",
			"json_args":{
				"language":"zh-cn",
				"accent":"mandarin"
			},
			"result_id":1,
			"is_last":true,
			"is_finish":true
	　　},
	　　"desc":"success",
	　　"sid":"awa00000001@ch27f00e2d00fe430100"
	}

#### 语义结果：
	{
	    "action":"result",
	    "code":"0",
	    "data":{
	        "sub":"nlp",
			"auth_id":"xxx",
	        "intent":{
	            "answer":{
	                "text":"今天是3月1日",
	                "type":"T"
	            },
	            "match_info":{
	                "type":"gparser_path",
	                "value":"-----"
	            },
	            "operation":"ANSWER",
	            "rc":0,
	            "service":"datetime",
	            "sid":"ara00000002@ch5aa00e0ba5e72a0100",
	            "state":{
	
	            },
	            "text":"今天星期几",
	            "uuid":"atn004a008d@ch1aa50e0ba5e96f1d01"
	        },
			"result_id":1,
			"is_last":true,
			"is_finish":true
	    },
	    "desc":"success",
	    "sid":"awa00000001@ch03040e2d0ad3430100"
	}

#### tpp 应用后处理结果：
	{
	    "action":"result",
	    "code":"0",
	    "data":{
			"sub":"tpp",
			"auth_id":"xxx",
	        "content":"xxx",
			"result_id":1,
			"is_last":true,
			"is_finish":true
	    },
	    "desc":"success",
	    "sid":"awa00000001@ch03040e2d0ad3430100"
	}

#### 合成结果：

{
	    "action":"result",
	    "code":"0",
	    "data":{
			"sub":"tts",
			"auth_id":"xxx",
	
			//content是音频数据，需要base64解码，android解析示例
			//步骤1 保存字符串：String base64String = "YXNkZmFz......"
			//步骤2 base64解码： byte[] audio = Base64.decode(base64String, Base64.DEFAULT);
			//步骤3 保存音频：new FileOutputStream(new File(filePath), true).write(audio);
			"content":"YXNkZmFz......",
			"result_id":0,
			"json_args":{
				"cancel":"0",//合成过程中是否被取消
				"dte":"raw",
				 //dts音频序号,0（长音频，开始），1（长音频中间结果，可出现多次）,2（长音频结束),3（短音频，结束）
                 //长音频dts示例：0 1 1 1 ... 2
                 //短音频dts示例: 3
				"dts":1,
				// frame_id：音频段id，取值：1,2,3,...
				"frame_id":59,
				"text_end":220,
				//text_percent：合成进度
				"text_percent":11
			},
			"is_last":true,
			"is_finish":true
	    },
	    "desc":"success",
	    "sid":"awa00000001@ch03040e2d0ad3430100"
	}

### 错误信息
服务异常时（如会话超时），将异常信息以 text message 形式返回给客户端并关闭连接。
	{
	　　"action":"error",
	　　"code":"10205",
	　　"data":"",
	　　"desc":"websocket read error|read dispatch data error: i/o timeout",
	　　"sid":"awa00000003@ch78b90e18f1d4630100"
	}

### vad信息（配置vad_info参数后才返回）
	{
	    "action":"vad",
	    "code":"0",
	    "data":{
	        "vad_info":"end"
	    },
	    "desc":"success",
	    "sid":"awa00000001@ch2ba00e4f8e8c430100"
	}

## 连接断开
连接的断开由讯飞发起，客户端不应主动断开；
连接断开情况：
1. 会话正常结束，is_finish = true 的结果下发后断开；
2. 会话报错，下发错信息action="error"后断开；
3. 会话超时，在连接时长>60s 或 10s 无有效数据交互时断开。

如果客户要中断数据上传，必须发送 end 指令(--end--)给服务端，讯飞下发完相应结果后断开连接。

## 结果说明

| 参数 |类型|说明|
|:-------------|:-------------|:-------------|
|action	|string	|操作类型（started-握手，result-结果，error-出错，vad-端点检测）|
|code	|string	|返回码，详见错误码|
|data	|object	|结果数据|
|desc	|string	|描述|
|sid	|string	|会话id，调试时提供给讯飞帮助定位问题|

data字段说明如下：

| 参数 |类型|说明|
|:-------------|:-------------|:-------------|
|sub	|string	|业务类型（nlp-语义，iat-识别，tpp-后处理，itrans-翻译，tts-合成）|
|intent	|object	|语义结果数据|
|text	|object/string	|识别结果，object-分词结果，string-精简结果|
|content|object	|后处理、翻译、合成等结果|
|auth_id|string	|用户ID回传|
|is_last	|bool	|是否为该业务的最后一条结果（如识别的最后一条结果，语义的最后一条结果）|
|is_finish	|bool	|是否为本次会话的最后一条结果|
|result_id	|int	|结果序号|
|json_args	|object	|结果参数|

*intent 字段说明：*

详见 [语义协议](https://aiui-doc.xf-yun.com/project-1/doc-70/)

*text 字段说明：*

|参数|全称|类型|说明|
|:------|:------|:-----|:-----|
|sn	|sentence	|number	|第几句|
|ls	|last sentence	|boolean	|是否最后一句|
|bg	|begin	|number	|开始|
|ed	|end	|number	|结束|
|ws	|words	|array	|词|
|cw	|chinese word	|array	|中文分词|
|w	|word	|string	|单字|
|sc	|score	|number	|分数|

语义后合成json_args字段说明：

| 参数 |类型|说明|
|:-------------|:-------------|:-------------|
|dte|string|合成数据编码，如raw等|
|dts|int|数据状态|
|frame_id|int|合成音频编号，从1开始|
|text_percent|int|音频合成的进度百分比|
|error|string|错误信息|
|cancel|string|是否已取消|
|text_end |int|当前合成音频对应文本的结束位置（按照UTF16编码计算）|