一、产品介绍

语音识别API，是将录音转为相应的文字的服务。

1.1 适用场景

可适用于语音听写，语音输入法，游戏娱乐，人机交互，智能客服等场景。

1.2 使用限制

需要先前往控制台进行授权操作，才能正常使用在线语音识别。

二、接入说明

2.1 接入步骤

2.1.1 创建语音识别产品

前往控制台产品模块，创建基础技术语音识别产品。

2.1.2 完成产品授权

授权操作详见：配置授权。

完成授权后，还需要在控制台上发布产品。

2.1.3 接入在线语音识别API

按照识别接口请求说明和示例完成接入操作。

2.2 API服务地址

在线语音识别的API服务地址为：asr.dui.ai

2.3 请求参数

2.3.1 参数说明

enableTone

lmList

2.3.2 REST API

请求格式

POST /runtime/v2/recognize?language=zh-CN&res=comm&productId=xxx HTTP/1.1 
// qurery string里带一些重复的用于调度的参数
Host: asr.dui.ai
Content-Type: multipart/form-data; boundary=b0123456789;
Content-Length: N
--b0123456789
Content-Disposition: form-data; name="params"
 
{
    "context": {
        "productId": "p001", // 必选
        "userId": "u003",    // 可选
        "deviceName": "d002",  // 可选, 同IoT Device Name授权服务里的deviceName
        "sdkName": "dui-asr-android-sdk-6.1" // 可选
    },
    "request": {
        "requestId": "request-id-in-uuid", // 必选
        "audio": {
            "audioType": "wav", // 必选
            "sampleRate": 16000, // 必选
            "channel": 1, // 必选
            "sampleBytes": 2 // 必选
                    },
        "asr": {
            "wakeupWord": "你好小驰", // 可选；当前请求的唤醒词
            "enableRealTimeFeedback": true, //可选；启用结果实时返回
            "enableVAD": true, //可选；启用云端VAD
            "enablePunctuation": true, //可选；启用结果带标点符号
            "language": "zh-CN", //可选； 指定语种
            "res": "comm", //可选；指定选择何种解决方案 [comm, airobot, aihome, aicar]
            "lmId": "custom-lm-id", // 可选, 定制语言模型的模型id
         
        }
    }
}
 
--b0123456789
Content-Disposition: form-data; name="audio"; filename="audio.name"
Content-Type: application/octet-stream
 
content of audio.bin
 
--b0123456789--

2.3.3 WebSocket Protocol

wss://asr.dui.ai/runtime/v2/recognize?language=zh-CN&res=comm&productId=xxx HTTP/1.1 // qurery string里带一些重复的用于调度的参数

建立连接：
客户端在和服务端完成websocket协议握手后，向服务端发送一个GET请求，uri是/runtime/v2/recognize, 授权参数在query string中携带； 授权如果不通过，服务端会回复授权不通过的信息， 并且关闭连接。

客户端发送语音请求：
在客户端和服务端建立websocket连接后，客户端发送语音请求，首先向服务端发送一个opcode为text的报文，这个报文的payload是一个 json 字符串，示例如下:

{
    "context": {
        "productId": "p001", // 必选
        "userId": "u003",    // 可选
        "deviceName": "d002",  // 可选, 同IoT Device Name授权服务里的deviceName
        "sdkName": "dui-asr-android-sdk-6.1" // 可选
    },
    "request": {
        "requestId": "request-id-in-uuid", // 必选
        "audio": {
            "audioType": "wav", // 必选，建议压缩，格式上支持ogg, wav,mp3,flv,amr
            "sampleRate": 16000, // 必选
            "channel": 1, // 必选
            "sampleBytes": 2 // 必选
                   },
        "asr": {
            "wakeupWord": "你好小驰", // 可选；当前请求的唤醒词
            "enableRealTimeFeedback": true, //可选；启用结果实时返回
            "enableVAD": true, //可选；启用云端VAD
            "enablePunctuation": true, //可选；启用结果带标点符号
            "language": "zh-CN", //可选； 指定语种
            "res": "comm", //可选；指定选择何种解决方案 [comm, airobot, aihome, aicar]
            "lmId": "custom-lm-id", // 可选, 定制语言模型的模型id
                 }
    }
}

然后，客户端向服务端发送语音数据，opcode为binary, 这个报文的payload是语音数据，关建议分帧发送语音数据，每帧语音数据包含100毫秒时间长度的语音。

客户端向服务端发送一个报文表示语音数据发送完毕，这个报文的opcode为binary, payload是空。至此，客户端发送语音请求结束。

2.4 返回结果

2.4.1 参数说明

2.4.2 正确返回

1）REST API

{
    "requestId": "request-id-in-uuid",
    "eof": 0, // 0: 实时反馈结果, 1: 最后的结果
    "result": {
       "rec": "导航去香山",   // 已经确定的识别结果, 不重复
       "var": "吧", // 可变识别结果, 这部分不是最终的结果, 可能会变
      
           }
}

注意：在识别结果实时反馈的情景下，当eof为1并且有rec时，这个rec不是表示最终的识别结果。客户端需要缓存之前接收的eof为0，并且rec不为空的结果，并且把这些rec按接收的时间顺序做拼接，取拼接后的字符串作为最终的识别结果。

2）WebSocket Protocol

{
    "requestId": "request-id-in-uuid",
    "eof": 0, // 0: 实时反馈结果, 1: 最后的结果
    "result": {
       "rec": "导航去香山",   // 已经确定的识别结果, 不重复
       "var": "吧", // 可变识别结果, 这部分不是最终的结果, 可能会变
    }
}

2.4.3 错误返回

http code  非200

2.4.4 错误码描述

2.5 服务示例

2.5.1 Java_基于http协议

点此查看示例

2.5.2 Java_基于websocket协议

点此查看示例

2.5.3 asr在线识别curl命令_基于http协议

curl -H 'Content-Type: multipart/form-data' -F 'params={"context":{"productId": "x","userId":"x","deviceName":"x","sdkName":"x"},"request":{"requestId":"x","audio":{"audioType":"ogg","sampleRate":16000,"channel":1,"sampleBytes":2},"asr":{"res":"comm"}}}' -F "file=@filePath" "https://asr.dui.ai/runtime/v2/recognize?productId=x&apikey=x&res=comm"

2.5.4 Python_基于websocket协议

#!/usr/bin/env python
# coding=utf-8
### websocket模块https://pypi.python.org/pypi/websocket-client
### oggfile是一个speex压缩的ogg文件,文件格式是Ogg data, Speex audio
import websocket
from websocket import ABNF
import time
import thread
import json
import ssl
import uuid
product_id = 'x' #填入产品Id
apikey = 'x' #填入apikey
url = 'ws://asr.dui.ai/runtime/v2/recognize?productId='+product_id+'&apikey='+apikey
oggfile = 'x' #ogg文件的绝对路径
def on_message(ws, message):
    print 'Message>>>>>>>>>>>>>>>>>>>>>>>>'
    print message
    print 'Message<<<<<<<<<<<<<<<<<<<<<<<<'
    ws.close()
def on_error(ws, error):
    print 'error>>>>>>>>>>>>>>>>>>>>>>'
    print error
    print 'error<<<<<<<<<<<<<<<<<<<<<<'
  
def on_close(ws):
    print "### closed ###"
  
def on_open(ws):
    def run(*args):
        content = {
            "context": {
                "productId":product_id,
                "userId": "x",
                "deviceName": "x",
                "sdkName": "x"
            },
            "request": {
                "requestId": str(uuid.uuid1()).replace('-',''),
                "audio": {
                    "audioType": "ogg",
                    "sampleBytes": 2,
                    "sampleRate": 16000,
                    "channel": 1,
                    "compress": "raw"
                },
                "asr":{
                    "enableVAD": True,
                    "enableRealTimeFeedback": False
                }
            }
        }
        ws.send(json.dumps(content))
        step = 400 #如果audioType是wav，此处需要修改为3200
        with open(oggfile, 'rb') as f:
            while True:
                data = f.read(step)
                if data:
                    ws.send(data, ABNF.OPCODE_BINARY)
                if len(data) < step:
                    break
                time.sleep(0.1)
        ws.send('', ABNF.OPCODE_BINARY)
        #print "thread terminating..."
    thread.start_new_thread(run, ())
if __name__ == "__main__":
    ws = websocket.WebSocketApp(url, on_message = on_message,
    on_error = on_error, on_close = on_close)
    ws.on_open = on_open
    ws.run_forever(sslopt={"cert_reqs": ssl.CERT_NONE})

2.6 注意事项

接入在线语音识别服务需要注意以下内容：
1）不支持识别合成音；
2）只支持单声道、16k采样率、一个采样点大小是2个字节的音频文件；
3）ogg音频文件不支持ogg vorbis，只支持ogg speex；
4）基于http协议的识别请求，不支持识别结果实时返回，不支持识别结果中间带标点符号
5) Java项目基于Maven构建，Http和WebSocket实现主类都基于BasicClient类,项目依赖在pom.xml中体现。