提示:
- 在使用SDK之前,请先确保已阅读了 接口说明文档。
- 从2.1.0版本开始原有nls-sdk-long-asr 更名为 nls-sdk-transcriber.升级时需确认删除掉nls-sdk-long-asr,并按编译提示添加相应回调方法即可。
下载安装
可从maven 服务器下载最新版本SDK:
<dependency>
<groupId>com.alibaba.nls</groupId>
<artifactId>nls-sdk-transcriber</artifactId>
<version>2.1.0</version>
</dependency>
使用方式参见下面代码示例。Demo 源码下载链接。
demo 解压后,在pom 目录运行mvn package ,会在target目录生成可执行jar nls-example-transcriber-2.0.0-jar-with-dependencies.jar 将此jar拷贝到目标服务器,可用于快速验证及压测服务。
服务验证
java -cp nls-example-transcriber-2.0.0-jar-with-dependencies.jar com.alibaba.nls.client.SpeechTranscriberDemo并按提示提供相应参数,运行后在命令执行目录生成logs/nls.log
服务压测
java -jar nls-example-transcriber-2.0.0-jar-with-dependencies.jar并按提示提供相应参数,其中阿里云服务url参数为: wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1 ,语音文件请提供16k采样率 pcm 格式文件,并发数根据用户已购买并发谨慎选择。
温馨提示:自行压测超过2并发会产生费用。
关键接口
- NlsClient:语音处理client,相当于所有语音相关处理类的factory,全局创建一个实例即可。线程安全。
- SpeechTranscriber:实时语音识别类,设置请求参数,发送请求及声音数据。非线程安全。
- SpeechTranscriberListener:实时语音识别结果监听类,监听识别结果。非线程安全。
更多介绍参见API文档链接: Java API接口说明
SDK 调用注意事项
- NlsClient对象创建一次可以重复使用,每次创建消耗性能。NlsClient使用了netty的框架,创建时比较消耗时间和资源,但创建之后可以重复利用。建议调用程序将NlsClient的创建和关闭与程序本身的生命周期结合。
- SpeechTranscriber对象不能重复使用,一个识别任务对应一个SpeechTranscriber对象。例如有N个音频文件,则要进行N次识别任务,创建N个SpeechTranscriber对象。
- 实现的SpeechTranscriberListener对象和SpeechTranscriber对象是一一对应的,不能将一个SpeechTranscriberListener对象设置到多个SpeechTranscriber对象中,否则不能区分是哪个识别任务。
- Java SDK依赖了Netty网络库,版本需设置为4.1.17.Final及以上。如果您的应用中依赖了Netty,请确保版本符合要求。
代码示例
说明:Demo中使用的音频文件为16000Hz采样率,请在管控台中将appKey对应项目的模型设置为通用模型,以获取正确的识别结果;如果使用其他音频,请设置为支持该音频场景的模型,模型设置请阅读管理项目一节。
nls-sample-16k.wav
示例:
package com.alibaba.nls.client;
import java.io.File;
import java.io.FileInputStream;
import com.alibaba.nls.client.protocol.InputFormatEnum;
import com.alibaba.nls.client.protocol.NlsClient;
import com.alibaba.nls.client.protocol.SampleRateEnum;
import com.alibaba.nls.client.protocol.asr.SpeechTranscriber;
import com.alibaba.nls.client.protocol.asr.SpeechTranscriberListener;
import com.alibaba.nls.client.protocol.asr.SpeechTranscriberResponse;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
/**
* 此示例演示了
* ASR实时识别API调用
* 动态获取token
* 通过本地模拟实时流发送
* 识别耗时计算
* (仅作演示,需用户根据实际情况实现)
*/
public class SpeechTranscriberDemo {
private String appKey;
private NlsClient client;
private static final Logger logger = LoggerFactory.getLogger(SpeechTranscriberDemo.class);
public SpeechTranscriberDemo(String appKey, String token, String url) {
this.appKey = appKey;
//Create an NlsClient object. You can globally create an NlsClient object and specify the endpoint.
if(url.isEmpty()) {
client = new NlsClient("wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1", token);
}else {
client = new NlsClient(url, token);
}
}
private static SpeechTranscriberListener getTranscriberListener() {
SpeechTranscriberListener listener = new SpeechTranscriberListener() {
// Return intermediate results. The server returns this message when it recognizes a word.
// This message is returned only when the setEnableIntermediateResult parameter is set to true.
@Override
public void onTranscriptionResultChange(SpeechTranscriberResponse response) {
System.out.println("task_id: " + response.getTaskId() +
", name: " + response.getName() +
//The status code. The code 20000000 indicates that the request is successful.
", status: " + response.getStatus() +
//The sequence number of the sentence, which starts from 1.
", index: " + response.getTransSentenceIndex() +
//The recognition result of the sentence.
", result: " + response.getTransSentenceText() +
//The duration of currently processed audio streams, in milliseconds.
", time: " + response.getTransSentenceTime());
}
@Override
public void onTranscriberStart(SpeechTranscriberResponse response) {
System.out.println("task_id: " + response.getTaskId() + ", name: " + response.getName() + ", status: " + response.getStatus());
}
@Override
public void onSentenceBegin(SpeechTranscriberResponse response) {
System.out.println("task_id: " + response.getTaskId() + ", name: " + response.getName() + ", status: " + response.getStatus());
}
//Recognize a complete sentence. The server can detect the beginning and end of a sentence. When the server detects the end of the sentence, it returns this message.
@Override
public void onSentenceEnd(SpeechTranscriberResponse response) {
System.out.println("task_id: " + response.getTaskId() +
", name: " + response.getName() +
//The status code. The code 20000000 indicates that the request is successful.
", status: " + response.getStatus() +
//The sequence number of the sentence, which starts from 1.
", index: " + response.getTransSentenceIndex() +
//The recognition result of the sentence.
", result: " + response.getTransSentenceText() +
//The confidence level.
", confidence: " + response.getConfidence() +
//The time when the server detects the beginning of the sentence.
", begin_time: " + response.getSentenceBeginTime() +
//The duration of currently processed audio streams, in milliseconds.
", time: " + response.getTransSentenceTime());
}
//Indicate that the recognition is completed.
@Override
public void onTranscriptionComplete(SpeechTranscriberResponse response) {
System.out.println("task_id: " + response.getTaskId() + ", name: " + response.getName() + ", status: " + response.getStatus());
}
@Override
public void onFail(SpeechTranscriberResponse response) {
System.out.println("task_id: " + response.getTaskId() + ", status: " + response.getStatus() + ", status_text: " + response.getStatusText());
}
};
return listener;
}
// calculate the corresponding equivalent voice length based on the binary data size
public static int getSleepDelta(int dataSize, int sampleRate) {
int sampleBytes = 16;
// only supports single channel
int soundChannel = 1;
return (dataSize * 10 * 8000) / (160 * sampleRate);
}
public void process(String filepath) {
SpeechTranscriber transcriber = null;
try {
//Create an object and establish a connection
transcriber = new SpeechTranscriber(client, getTranscriberListener());
transcriber.setAppKey(appKey);
//Specify the audio coding format
transcriber.setFormat(InputFormatEnum.PCM);
//Specify the audio sampling rate
transcriber.setSampleRate(SampleRateEnum.SAMPLE_RATE_16K);
//Specify whether to return intermediate results
transcriber.setEnableIntermediateResult(false);
//Specify whether to add punctuation marks to the recognition result
transcriber.setEnablePunctuation(true);
//Specify whether to enable inverse text normalization (ITN). A value of true indicates that Chinese numerals are converted to Arabic numerals
transcriber.setEnableITN(false);
//Serialize preceding parameters to the JSON format and send them to the server for confirmation
transcriber.start();
File file = new File(filepath);
FileInputStream fis = new FileInputStream(file);
byte[] b = new byte[3200];
int len;
while ((len = fis.read(b)) > 0) {
logger.info("send data pack length: " + len);
transcriber.send(b);
// if it is real-time speech, then no sleep, if it is 8k sample rate, the second parameter is changed to 8000
// if 8000 sample rate, 3200 bytes is recommended for sleep 200ms. if 16000 sample rate, 3200 bytes is recommended for sleep 100ms.
int deltaSleep = getSleepDelta(len, 16000);
Thread.sleep(deltaSleep);
}
//Notify the server that all audio data has been sent and wait for the completion message from the server.
long now = System.currentTimeMillis();
logger.info("ASR wait for complete");
transcriber.stop();
logger.info("ASR latency : " + (System.currentTimeMillis() - now) + " ms");
} catch (Exception e) {
System.err.println(e.getMessage());
} finally {
if (null != transcriber) {
transcriber.close();
}
}
}
public void shutdown() {
client.shutdown();
}
public static void main(String[] args) throws Exception {
String appKey = null;
String token = null;
String url = ""; // 默认即可,默认值:wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1
if (args.length == 2) {
appKey = args[0];
token = args[1];
} else if (args.length == 3) {
appKey = args[0];
token = args[1];
url = args[2];
} else {
System.err.println("run error, need params(url is optional): " + "<app-key> <token> [url]");
System.exit(-1);
}
String filepath = "nls-sample-16k.wav";
SpeechTranscriberDemo demo = new SpeechTranscriberDemo(appKey, token, url);
demo.process(filepath);
demo.shutdown();
}
}