Java SDK是什么?

功能介绍


语音Java SDK提供一句话识别服务，提供将实时短语音转成文字的功能，可直接用于语音搜索类应用。

选择app_key


选择app_key

SDK下载地址


一句话识别JavaSDK
压缩包内为Java Demo工程，SDK jar包在src/main/java/resources/目录下，用户需要在IDE中操作将jar包导入。

• IDEA 中的操作方法为在jar包上右键，选”Add as library…”。
• Eclipse中的操作方法为在工程上右键，选“Build Path”->“Add Library…”

请注意：sdk内部不自带语音采集的功能，只提供将语音流与文字互转和语意识别的功能。

示例说明



SDK调用顺序

1. 
   创建一个NlsClient的实例并调用init()方法来初始化客户端
2. 
   提取语音数据并创建语音识别请求，至少填写appKey及需要识别的语音数据的格式。创建一个NlsListener的实现类。
3. 
   调用NlsClient的createNlsFuture（第2步中的listener实例作为入参之一，用来处理返回结果）方法获取future，通过future的sendVoice方法来发送语音数据并在listener中处理返回结果。
4. 
   通过future的sendFinishSignal来结束语音文件的发送，ASR服务收到这个结束信号后，会返回处理结果。
5. 
   如有多个识别需要，重复步骤2-4。
6. 
   调用NlsClient的close()方法来关闭客户端并释放资源。

SDK调用注意事项

1. 
   NlsClient创建一次可以重复使用,每次创建消耗性能
2. 
   NlsClient使用了netty的框架，创建时比较消耗时间和资源，但创建之后可以重复利用。建议调用程序将NlsClient的创建和关闭与程序本身的生命周期结合。
3. 
   每一次调用语音识别请求时注入的NlsListener只对本次语音识别的生命周期负责。
4. 
   每次调用createNlsFuture(NlsRequest req, com.alibaba.idst.nls.event.NlsListenerlistener)方法做语音识别和对话时，注入的listener只对本次识别起作用。其他的语音识别进程不会触发该listener。
5. 
   NlsRequest里面的语音格式请与语音文件的格式保持一致。目前SDK支持pcm和opu格式，opu格式请参考opus编解码文档进行压缩。
6. 
   sdk只会根据该格式来切分和发送语音文件，如果两个不一致，后续的一切都是错误的。
7. 
   NlsListener的实现类里面，处理返回结果的代码尽量耗时剪短，最好不要涉及I/O操作。
8. 
   NlsListener的实现类中的处理方法是在NlsClient的语音识别线程中调用的，太长的操作时间导致线程不能及时释放会影响其他识别进程的顺利进行，同时也会影响整个程序的loading。I/O操作应该禁止在该实现类中出现，最好使用触发的方式将操作转移到其他线程中去进行。
9. 
   并发或多线程支持，如果需要在您的应用支持多个并发请求，请不要重复创建NlsClient对象。正确的做法是构建不同的NlsRequest对象，同时创建不同的NlsListener，并传入NlsRequest对象。这样就可以并发不同请求并且拿到正确的相应的结果。

重要接口说明



com.alibaba.idst.nls.NlsClient

---

语音sdk对外暴露的类，调用程序通过调用该类的init()、close()、createNlsFuture()等方法来打开、关闭或发送语音数据。

初始化NlsClient


public void init((boolean sslMode, int port)

• 说明 初始化NlsClient，创建好websocket client factory
• 
  参数 sslMode 是否采用ssl模式，一般设置为true
• port 端口号，一般为443

返回值 null

设置服务器地址


public void setHost(String host)

• 说明 设置服务器地址
• 
  参数
• 
  返回值 null

实例化NlsFuture请求


public NlsFuture createNlsFuture(NlsRequest req,com.alibaba.idst.nls.event.NlsListener listener)

• 说明 实例化NlsFuture请求，传入请求和监 听 器
• 
  参数req 请求对象
• listener 回调数据的监 听 器

返回值 future

关闭NlsClient


public void close()

• 说明 关闭websocket client factory，释放资源
• 
  参数
  null
• 
  返回值 null

com.alibaba.idst.nls.event.NlsListener

---

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

识别结果回调


void onMessageReceived(NlsEvent e);

• 说明 识别结果回调
• 
  参数NlsEvent Nls服务结果的对象 识别结果在e.getResponse()中

返回值 null

识别失败回调


void onOperationFailed(NlsEvent e);

• 说明 识别失败回调
• 
  参数NlsEvent Nls服务结果的对象 错误信息在e.getErrorMessage()中

返回值 null

socket 连接关闭的回调


void onChannelClosed(NlsEvent e);

• 说明 socket 连接关闭的回调
• 
  参数NlsEvent Nls服务结果的对象

返回值 null

com.alibaba.idst.nls.protocol.NlsRequest

---

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

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


public void setAppKey(String app_key)

• 说明 设置应用的appkey，appkey需要先申请再使用。
• 参数app_key

返回值 null
public void setAsrFormat(String sc)

• 
  说明 设置语音识别的语音格式，一般为pcm。若使用opu格式的语音，请参考opus编解码文档说明进行编码设置。
  该项在使用语音识别服务时必须设置，起到初始化作用。
• 参数sc 一般为pcm。

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

• 
  说明 设置asr识别结果的返回方式。
  默认为流式。
• 参数mode.STREAMING:逐词返回,流式效果;mode.NORMAL:逐句返回

返回值 null
public void setAsrSampleRate(String sampleRate)

• 
  说明 设置输入asr音频的采样率。
  默认为16 即16k采样率。
• 参数可设置为8 或 16 分别代表8k，16k 采样率

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

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

返回值 null
public void setAsrVocabularyId(String vocabularyId)

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

返回值 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.

com.alibaba.idst.nls.NlsFuture

---

NlsFuture是具体操作语音的对象类，语音数据的发送/接收都通过这个类进行操作。 public NlsFuturesendVoice(byte[] data, int offset, int length)

• 说明 语音识别时，发送语音文件的方法
• 参数data byte[]类型的语音流
• offset
• length

返回值 NlsFuture
public NlsFuture sendFinishSignal()

• 说明 语音识别结束时，发送结束符
• 
  参数
• 
  返回值 NlsFuture

public boolean await(int timeout)

• 说明 请求超时时间
• 参数timeout 请求发送出去后，等待服务端结果返回的超时时间，单位ms

返回值 true false

com.alibaba.idst.nls.protocol.NlsResponse

---

语音识别的返回结果封装对象。返回结果告知语音识别是否成功，语音识别结果或部分结果(视调用程序需要的返回方式而定)，语音识别是否已经结束。
public String getAsr_ret()

• 说明 获取语音识别的结果
• 参数null

返回值 String

错误码

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

结果回调说明


返回的识别结果result是一个response的对象：

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.     }

完整示例

1. package com.demo;
3. import java.io.File;
4. import java.io.FileInputStream;
6. import com.alibaba.idst.nls.NlsClient;
7. import com.alibaba.idst.nls.NlsFuture;
8. import com.alibaba.idst.nls.event.NlsEvent;
9. import com.alibaba.idst.nls.event.NlsListener;
10. import com.alibaba.idst.nls.protocol.NlsRequest;
11. import com.alibaba.idst.nls.protocol.NlsResponse;
13. public class AsrDemo implements NlsListener {
14.     private static NlsClient client = new NlsClient();
16.     public AsrDemo() {
17.         System.out.println("init Nls client...");
18.         // 初始化NlsClient
19.         client.init();
20.     }
22.     public void shutDown() {
23.         System.out.println("close NLS client");
24.         // 关闭客户端并释放资源
25.         client.close();
26.         System.out.println("demo done");
27.     }
29.     public void startAsr() {
30.         //开始发送语音
31.         System.out.println("open audio file...");
32.         FileInputStream fis = null;
33.         try {
34.             String filePath = "src/main/java/resources/sample.pcm";
35.             File file = new File(filePath);
36.             fis = new FileInputStream(file);
37.         } catch (Exception e) {
38.             e.printStackTrace();
39.         }
41.         if (fis != null) {
42.             System.out.println("create NLS future");
43.             try {
44.                 NlsRequest req = new NlsRequest();
45.                 req.setAppKey("nls-service"); // appkey请从 "快速开始" 帮助页面的appkey列表中获取
46.                 req.setAsrFormat("pcm"); // 设置语音文件格式为pcm,我们支持16k 16bit 的无头的pcm文件。
48.                 /*热词相关配置*/
49.                 //req.setAsrVocabularyId("Vocabulary_id");//热词词表id
50.                 /*热词相关配置*/
53.                 req.authorize("", ""); // 请替换为用户申请到的Access Key ID和Access Key Secret
54.                 NlsFuture future = client.createNlsFuture(req, this); // 实例化请求,传入请求和监 听 器
55.                 System.out.println("call NLS service");
56.                 byte[] b = new byte[8000];
57.                 int len = 0;
58.                 while ((len = fis.read(b)) > 0) {
59.                     future.sendVoice(b, 0, len); // 发送语音数据
60.                     Thread.sleep(50);
61.                 }
62.                 future.sendFinishSignal(); // 语音识别结束时，发送结束符
63.                 System.out.println("main thread enter waiting for less than 10s.");
64.                 future.await(10000); // 设置服务端结果返回的超时时间
65.             } catch (Exception e) {
66.                 e.printStackTrace();
67.             }
68.             System.out.println("calling NLS service end");
69.         }
70.     }
72.     public void onMessageReceived(NlsEvent e) {
73.         //识别结果的回调
74.         NlsResponse response = e.getResponse();
75.         String result = "";
76.         int statusCode = response.getStatus_code();
77.         if (response.getAsr_ret() != null) {
78.             result += "\nget asr result: statusCode=[" + statusCode + "], " + response.getAsr_ret(); //识别结果
79.         }
80.         if (result != null) {
81.             System.out.println(result);
82.         } else {
83.             System.out.println(response.jsonResults.toString());
84.         }
85.     }
87.     @Override
88.     public void onOperationFailed(NlsEvent e) {
89.         //识别失败的回调
90.         String result = "";
91.         result += "on operation failed: statusCode=[" + e.getResponse().getStatus_code() + "], " + e.getErrorMessage();
92.         System.out.println(result);
93.     }
95.     @Override
96.     public void onChannelClosed(NlsEvent e) {
97.         //socket 连接关闭的回调
98.         System.out.println("on websocket closed.");
99.     }
101.     public static void main(String[] args) {
102.         AsrDemo asrDemo = new AsrDemo();
103.         asrDemo.startAsr();
104.         asrDemo.shutDown();
105.     }
106. }