Android SDK是什么?

功能介绍


语音Android SDK提供一句话识别服务，提供将实时短语音转成文字的功能，可直接用于语音搜索类应用。
阿里云语音服务SDK（NLSClinet），是运行于android平台的基础语音识别、自然语言理解和语音合成的基础服务，本服务通过Jar包和.so库的形式导入，用户通过本指南可以方便的接入。

SDK下载地址


一句话识别AndroidSDK

获取appkey


获取appkey

开发包目录

文件夹	内容
libs/
libs/NlsClientSdk.jar	NLSClinet的服务包
libs/armeabi
libs/armeabi/libztcodec2.so
libs/armeabi-v7a
libs/armeabi-v7a/libztcodec2.so
libs/x86
libs/x86/libztcodec2.so

• 本服务使用了解析json的gson.jar,需要用户自行导入。

集成指南



导入服务包


将下载的服务包解压后，将NlsClientSdk.jar，以及对应架构的.so包导入你的项目中的libs/目录下。

Android权限管理


在AndroidManifest.xml文件中添加以下权限申请：

1. <uses-permission android:name="android.permission.INTERNET" />
2. <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
3. <uses-permission android:name="android.permission.READ_PHONE_STATE" />
4. <uses-permission android:name="android.permission.RECORD_AUDIO" />
5. <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
6. <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
7. <uses-permission android:name="android.permission.WRITE_SETTINGS" />

Proguard配置


如果代码使用了混淆，请在proguard-rules.pro中配置：

1. -keep class com.alibaba.idst.nls.** {*;}
2. -keep class com.google.**{*;}

重要接口说明



com.alibaba.idst.nls.NlsClient

---

语音服务的核心服务类，客户端程序通过调用该类的cancel()、start()、stop()等方法来打开、关闭或发送语音数据。

全局配置


public static void configure(Context appContext)

• 说明 全局配置，在初始化NlsClient前需要被调用，建议放在Application的onCreate()里
• 参数appContext 传入ApplicationContext参数，用于识别引擎内部访问和Android上下文相关的资源

返回值 null

实例化NlsClient对象


public static NlsClient newInstance(Context context,NlsListenernlsListener,StageListener stageListener, NlsRequest nlsRequest)

• 说明 获得一个NlsClient, 通过该方法实例化NlsClient。
• 参数context 传入Context参数，用于识别引擎内部访问和Android上下文相关的资源
• nlsListener 识别相关的回调接口，用于通知客户端识别结果
• stageListener 引擎状态回调接口，用于通知客户端当前的引擎状态以及录音音量等

返回值 NlsClient

打开语音识别引擎


public boolean start()

• 说明 打开语音识别引擎
• 
  参数
• 
  返回值 isOpen true:打印log false:关闭log
  true:开始录音，并对录音进行语音识别 false:打开语音识别引擎失败，可能重复打开或者远程服务处于不可用状态。

关闭语音识别引擎


public void stop()

• 说明 关闭语音识别引擎
• 
  参数
• 
  返回值

判断是否正在进行语音识别


public boolean isStarted()

• 说明 返回当前引擎是否已启动
• 
  参数
• 
  返回值 true:引擎已启动 false:引擎未启动

取消此次语音识别


public void cancel()

• 说明 取消此次语音识别，识别结果为ErrorCode.USER_CANCEL
• 
  参数
• 
  返回值 null

<a class="reference-link" name="其它接口：">其它接口：



Log开关


public static void openLog(boolean isOpen)

• 说明 log开关，标识是否需要通过logcat打印识别引擎的相关log
• 参数isOpen true:打印log false:关闭log

返回值 null

设置VAD是否打开


public NlsClient setRecordAutoStop(boolean isAutoStop)

• 说明 VAD 是端点检测功能，打开VAD可以自动检测语音结束，并结束语音
• 参数isAutoStop true:打开VAD false:关闭VAD

返回值 NlsClient

设置音量回调时长


public NlsClient setMinVoiceValueInterval(int interval)

• 说明 设置获取录音音量的最短时间间隔，防止录音音量回调过于频繁影响客户端对音量的展示逻辑
• 参数interval 更新间隔 单位ms

返回值 NlsClient

设置最短录音时长


public NlsClient setMinRecordTime(int minRecordTime)

• 说明 用于设置最短录音时间，引擎开始时，用户在该时间内不说话，则会自动关闭引擎，识别结果为ErrorCode.NOTHING
• 参数minRecordTime 最短录音时间 单位ms

返回值 NlsClient

设置最大录音时长


public NlsClient setMaxRecordTime(int maxRecordTime)

• 说明 用于设置最大录音时间
• 参数maxRecordTime 最大录音时间 单位ms

返回值 NlsClient设置最大录音中断时间
public NlsClient setMaxStallTime(int milliSeconds)

• 说明 打开VAD时， 设置录音中句子之间的最长停顿时间 ，录音过程中，如果用户停顿超过该时间则认为用户已经停止说话，停止录音
• 参数milliSeconds 最大录音时间 单位ms

返回值 NlsClient

获取完整录音语音


public byte[] getObject()

• 说明得到录音样本PCM，该方法可以在mStageListener.onStopRecognizing()方法中调用。

参数

• pcm bytes

com.alibaba.idst.nls.internal.protocol.NlsRequest

---

语音服务的请求封装对象。调用程序需要至少在请求对象里设定好调用者的appKey和语音数据的格式以便后台服务能正确识别并翻译语音。

初始化Nls 请求：NlsRequest mNlsRequest= new NlsRequest(proto)或缺省proto：NlsRequest mNlsRequest = new NlsRequest()


public void setApp_key(String app_key)

• 说明 设置应用的appkey，appkey请从 “快速开始” 帮助页面的appkey列表中获取。
• 参数app_key

返回值 null
public void setAsr_sc(String sc)

• 说明 设置语音识别的语音格式，默认为opu。 该项在使用语音识别服务时必须设置，起到初始化作用。
• 参数sc 设置为opu。

返回值 null
public void setAsrVocabularyId(String vocabularyId)

• 说明 设置词表id
• 参数id 热词使用

返回值 null
public void setAsrResposeMode(NlsRequestASR.mode mode)

• 说明设置语音识别的结果返回模式。mode有两种模式(STREAMING、NORMAL)。STREAMING模式下，结果为增量返回，即识别中间结果每次返回增加1-2个字；NORMAL模式下，识别只返回最终结果。
• 参数NlsRequestASR.mode mode(STREAMING、NORMAL)

返回值 null
public void authorize(String id, String secret)

• 说明 数加认证模块，所有的请求都必须通过authorize方法认证通过，才可以使用。 id和secret需要申请获取。
• 参数id id。
• secret 对应密钥。

返回值 null

com.alibaba.idst.nls.internal.protocol.NlsRequestProto

---

NlsRequest对象初始化时需要注入的参数。
public void setApp_id(String app_id)

• 设置application_id.

public void setApp_user_id(String app_user_id)

• 设置app_user_id.

public void setReq_id(String req_id)

• 设置req_id.

public void setQuery_type(String query_type)

• 设置query_type.

com.alibaba.idst.nls.StageListener

---

语音服务引擎状态变更回调接口，服务状态的改变、音量大小的回调、语音文件的生成通过本接口获取。

录音开始的回调


public void onStartRecording(NlsClient recognizer)

• 说明 录音开始
• 
  参数
• 
  返回值 NlsClient

录音结束的回调


public void onStopRecording(NlsClient recognizer)

• 说明 录音结束
• 
  参数
• 
  返回值 NlsClient

识别开始的回调


public void onStartRecognizing(NlsClient recognizer)

• 说明 识别开始
• 
  参数
• 
  返回值 NlsClient

识别结束的回调


public void onStopRecognizing(NlsClient recognizer)

• 说明 识别结束
• 
  参数
• 
  返回值 NlsClient

音量大小回调


public void onVoiceVolume(int volume)

• 说明 获取音量
• 
  参数volume 录音音量，范围0-100

返回值 null

获取流式返回录音语音


public void onVoiceData(short[] data, int length)

• 说明 当引擎获取到每帧录音时回调，用于客户端应用获取录音数据，默认20ms每帧数据
• 参数data 录音数据 原始未压缩 未判断VAD
• length 该帧录音长度

com.alibaba.idst.nls.NlsListener

---

语音服务结果的回调类，语音服务是一个相对较长过程，为了不影响客户端的正常工作，语音sdk被设计成异步模式，调用程序将语音客户端建立好并将语音数据交给sdk后就可以离开。在收到语音数据之后的处理需要通过实现该接口来完成。每一个识别过程创建的时候都需要注入侦听者以响应语音服务的结果。

语音识别结果的回调接口


public void onRecognizingResult(int status, RecognizedResult result)

• 说明 语音识别结果回调接口，识别结束时回调。(使用流式返回的key时，会多次回调本接口得到实时识别结果)
• 参数status 标识识别结果的状态，详情见下方。
• result 返回识别结果的数据结构，详情见下方。

返回值 nullresult中的字段值：

字段名	含义	类型
asr_out	语音识别结果json	String
finish	流式返回时判断返回是否结束的字段，finish=true表示返回结束	Boolean
bstream_attached	判断后面是否跟有语音流	Boolean
status_code	状态码	int

json 结构如下：

1.     {
2.       "status" : "1",// 服务器状态，0为失败，非零为成功
3.       "id" : "",// 透传系统始终的uuid,服务端配置是否返回
4.       "finish" : "1",// 0为未结束，非零为结束，识别是否已经结束
5.       "results" : {
6.         "asr_out" : {
7.           "result" : "",// 语音识别结果
8.           "status" : 1,// 服务器状态，0为失败，非零为成功
9.           "finish" : 1,// 0为未结束，非零为结束，识别是否已经结束
10.           "version" : "4.0"
11.         },
12.         "out" : {}//保留字段
13.       },
14.       "bstream_attached" : false,// 应答包的后面是不是还接着二进制语音流。
15.       "version" : "4.0"// 协议版本号
16.     }

错误码

• 客户端错误码

字段名	错误码	含义
SUCCESS	0	成功
RECOGNIZE_ERROR	1	识别失败
USER_CANCEL	520	用户取消
CONNECT_ERROR	530	网络及通讯异常
NOTHING	540	语音服务异常
RECORDING_ERROR	550	录音及语音识别异常
ERROR_CLICK_TOOMUCH	570	用户点击过快

• 服务端返回结果错误码

状态	status_code	CloseFrame状态码	HTTP语义
成功	200	1000	成功处理
请求格式有误	400	4400	错误请求
需要鉴权信息	401	4401	请求要求身份验证
鉴权失败	403	4403	服务器拒绝请求
超出最大并发量	429	4429	太多请求
请求超时	408	4408	处理请求超时
处理出错	500	4500	服务器内部错误
服务不可用	503	4503	服务不可用

完整示例

1. package com.alibaba.idst.nlsdemo;
3. import android.app.Activity;
4. import android.os.Bundle;
5. import android.util.Log;
6. import android.view.View;
7. import android.widget.Button;
8. import android.widget.EditText;
9. import android.widget.Toast;
11. import com.alibaba.idst.R;
12. import com.alibaba.idst.nls.NlsClient;
13. import com.alibaba.idst.nls.NlsListener;
14. import com.alibaba.idst.nls.StageListener;
15. import com.alibaba.idst.nls.internal.protocol.NlsRequest;
16. import com.alibaba.idst.nls.internal.protocol.NlsRequestProto;
18. public class PublicAsrActivity extends Activity {
20.     private boolean isRecognizing = false;
21.     private EditText mFullEdit;
22.     private EditText mResultEdit;
23.     private Button mStartButton;
24.     private Button mStopButton;
25.     private NlsClient mNlsClient;
26.     private NlsRequest mNlsRequest;
27.     private Context context;
29.     @Override
30.     protected void onCreate(Bundle savedInstanceState) {
31.         super.onCreate(savedInstanceState);
32.         setContentView(R.layout.activity_public_asr);
33.         context = getApplicationContext();
34.         mFullEdit = (EditText) findViewById(R.id.editText2);
35.         mResultEdit = (EditText) findViewById(R.id.editText);
36.         mStartButton = (Button) findViewById(R.id.button);
37.         mStopButton = (Button) findViewById(R.id.button2);
39.         mNlsRequest = initNlsRequest();
40.         String appkey = ""; //请设置简介页面的Appkey
42.         mNlsRequest.setApp_key(appkey);    //appkey列表中获取
43.         mNlsRequest.setAsr_sc("opu");      //设置语音格式
44.         // 热词参数
45.         mNlsRequest.setAsrVocabularyId("vocabid");
46.         NlsClient.openLog(true);
47.         NlsClient.configure(getApplicationContext()); //全局配置
48.         mNlsClient = NlsClient.newInstance(this, mRecognizeListener, mStageListener,mNlsRequest);                          //实例化NlsClient
50.         mNlsClient.setMaxRecordTime(60000);  //设置最长语音
51.         mNlsClient.setMaxStallTime(1000);    //设置最短语音
52.         mNlsClient.setMinRecordTime(500);    //设置最大录音中断时间
53.         mNlsClient.setRecordAutoStop(false);  //设置VAD
54.         mNlsClient.setMinVoiceValueInterval(200); //设置音量回调时长
56.         initStartRecognizing();
57.         initStopRecognizing();
58.     }
60.     private NlsRequest initNlsRequest(){
61.         NlsRequestProto proto = new NlsRequestProto(context);
62.         proto.setApp_user_id("xxx"); //设置在应用中的用户名，可选
63.         return new NlsRequest(proto);
65.     }
67.     private void initStartRecognizing(){
68.         mStartButton.setOnClickListener(new View.OnClickListener() {
69.             @Override
70.             public void onClick(View view) {
71.                 isRecognizing = true;
72.                 mResultEdit.setText("正在录音，请稍候！");
73.                 mNlsRequest.authorize("", ""); //请替换为用户申请到的Access Key ID和Access Key Secret
74.                 mNlsClient.start();
75.                 mStartButton.setText("录音中。。。");
76.             }
77.         });
78.     }
80.     private void initStopRecognizing(){
81.         mStopButton.setOnClickListener(new View.OnClickListener() {
82.             @Override
83.             public void onClick(View view) {
84.                 isRecognizing = false;
85.                 mResultEdit.setText("");
86.                 mNlsClient.stop();
87.                 mStartButton.setText("开始 录音");
89.             }
90.         });
91.     }
93.     private NlsListener mRecognizeListener = new NlsListener() {
95.         @Override
96.         public void onRecognizingResult(int status, RecognizedResult result) {
97.             switch (status) {
98.                 case NlsClient.ErrorCode.SUCCESS:
99.                     Log.i("asr", "[demo]  callback onRecognizResult " + result.asr_out);
100.                     mResultEdit.setText(result.asr_out);
101.                     mFullEdit.setText(result.asr_out);
102.                     break;
103.                 case NlsClient.ErrorCode.RECOGNIZE_ERROR:
104.                     Toast.makeText(PublicAsrActivity.this, "recognizer error", Toast.LENGTH_LONG).show();
105.                     break;
106.                 case NlsClient.ErrorCode.RECORDING_ERROR:
107.                     Toast.makeText(PublicAsrActivity.this,"recording error",Toast.LENGTH_LONG).show();
108.                     break;
109.                 case NlsClient.ErrorCode.NOTHING:
110.                     Toast.makeText(PublicAsrActivity.this,"nothing",Toast.LENGTH_LONG).show();
111.                     break;
112.             }
113.             isRecognizing = false;
114.         }
117.     } ;
119.     private StageListener mStageListener = new StageListener() {
120.         @Override
121.         public void onStartRecognizing(NlsClient recognizer) {
122.             super.onStartRecognizing(recognizer);    //To change body of overridden methods use File | Settings | File Templates.
123.         }
125.         @Override
126.         public void onStopRecognizing(NlsClient recognizer) {
127.             super.onStopRecognizing(recognizer);    //To change body of overridden methods use File | Settings | File Templates.
128.         }
130.         @Override
131.         public void onStartRecording(NlsClient recognizer) {
132.             super.onStartRecording(recognizer);    //To change body of overridden methods use File | Settings | File Templates.
133.         }
135.         @Override
136.         public void onStopRecording(NlsClient recognizer) {
137.             super.onStopRecording(recognizer);    //To change body of overridden methods use File | Settings | File Templates.
138.         }
140.         @Override
141.         public void onVoiceVolume(int volume) {
142.             super.onVoiceVolume(volume);
143.         }
145.     };
147. }