全部产品
Search

搜索本产品

    java SDK 2.0

    文档中心

    java SDK 2.0

    更新时间： 2020-11-03

    提示:

    • 在使用SDK之前，请先确保已阅读了 接口说明文档。
    • 从2.1.0版本开始原有nls-sdk-long-asr 更名为 nls-sdk-transcriber.升级时需确认删除掉nls-sdk-long-asr,并按编译提示添加相应回调方法即可。

    下载安装

    可从maven 服务器下载最新版本SDK：

    1. <dependency>
    2.     <groupId>com.alibaba.nls</groupId>
    3.     <artifactId>nls-sdk-transcriber</artifactId>
    4.     <version>2.1.0</version>
    5. </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 调用注意事项

    1. NlsClient对象创建一次可以重复使用，每次创建消耗性能。NlsClient使用了netty的框架，创建时比较消耗时间和资源，但创建之后可以重复利用。建议调用程序将NlsClient的创建和关闭与程序本身的生命周期结合。
    2. SpeechTranscriber对象不能重复使用，一个识别任务对应一个SpeechTranscriber对象。例如有N个音频文件，则要进行N次识别任务，创建N个SpeechTranscriber对象。
    3. 实现的SpeechTranscriberListener对象和SpeechTranscriber对象是一一对应的，不能将一个SpeechTranscriberListener对象设置到多个SpeechTranscriber对象中，否则不能区分是哪个识别任务。
    4. Java SDK依赖了Netty网络库，版本需设置为4.1.17.Final及以上。如果您的应用中依赖了Netty，请确保版本符合要求。

    代码示例

    说明：Demo中使用的音频文件为16000Hz采样率，请在管控台中将appKey对应项目的模型设置为通用模型，以获取正确的识别结果；如果使用其他音频，请设置为支持该音频场景的模型，模型设置请阅读管理项目一节。

    nls-sample-16k.wav

    示例:

    1. package com.alibaba.nls.client;
    3. import java.io.File;
    4. import java.io.FileInputStream;
    6. import com.alibaba.nls.client.protocol.InputFormatEnum;
    7. import com.alibaba.nls.client.protocol.NlsClient;
    8. import com.alibaba.nls.client.protocol.SampleRateEnum;
    9. import com.alibaba.nls.client.protocol.asr.SpeechTranscriber;
    10. import com.alibaba.nls.client.protocol.asr.SpeechTranscriberListener;
    11. import com.alibaba.nls.client.protocol.asr.SpeechTranscriberResponse;
    13. import org.slf4j.Logger;
    14. import org.slf4j.LoggerFactory;
    16. /**
    17.  * 此示例演示了
    18.  *      ASR实时识别API调用
    19.  *      动态获取token
    20.  *      通过本地模拟实时流发送
    21.  *      识别耗时计算
    22.  * (仅作演示，需用户根据实际情况实现)
    23.  */
    24. public class SpeechTranscriberDemo {
    25.     private String appKey;
    26.     private NlsClient client;
    28.     private static final Logger logger = LoggerFactory.getLogger(SpeechTranscriberDemo.class);
    30.     public SpeechTranscriberDemo(String appKey, String token, String url) {
    31.         this.appKey = appKey;
    32.         //Create an NlsClient object. You can globally create an NlsClient object and specify the endpoint.
    33.         if(url.isEmpty()) {
    34.             client = new NlsClient("wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1", token);
    35.         }else {
    36.             client = new NlsClient(url, token);
    37.         }
    38.     }
    40.     private static SpeechTranscriberListener getTranscriberListener() {
    41.         SpeechTranscriberListener listener = new SpeechTranscriberListener() {
    42.             // Return intermediate results. The server returns this message when it recognizes a word.
    43.             // This message is returned only when the setEnableIntermediateResult parameter is set to true.
    44.             @Override
    45.             public void onTranscriptionResultChange(SpeechTranscriberResponse response) {
    46.                 System.out.println("task_id: " + response.getTaskId() +
    47.                     ", name: " + response.getName() +
    48.                     //The status code. The code 20000000 indicates that the request is successful.
    49.                     ", status: " + response.getStatus() +
    50.                     //The sequence number of the sentence, which starts from 1.
    51.                     ", index: " + response.getTransSentenceIndex() +
    52.                     //The recognition result of the sentence.
    53.                     ", result: " + response.getTransSentenceText() +
    54.                     //The duration of currently processed audio streams, in milliseconds.
    55.                     ", time: " + response.getTransSentenceTime());
    56.             }
    58.             @Override
    59.             public void onTranscriberStart(SpeechTranscriberResponse response) {
    60.                 System.out.println("task_id: " + response.getTaskId() + ", name: " + response.getName() + ", status: " + response.getStatus());
    61.             }
    63.             @Override
    64.             public void onSentenceBegin(SpeechTranscriberResponse response) {
    65.                 System.out.println("task_id: " + response.getTaskId() + ", name: " + response.getName() + ", status: " + response.getStatus());
    67.             }
    69.             //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.
    70.             @Override
    71.             public void onSentenceEnd(SpeechTranscriberResponse response) {
    72.                 System.out.println("task_id: " + response.getTaskId() +
    73.                     ", name: " + response.getName() +
    74.                     //The status code. The code 20000000 indicates that the request is successful.
    75.                     ", status: " + response.getStatus() +
    76.                     //The sequence number of the sentence, which starts from 1.
    77.                     ", index: " + response.getTransSentenceIndex() +
    78.                     //The recognition result of the sentence.
    79.                     ", result: " + response.getTransSentenceText() +
    80.                     //The confidence level.
    81.                     ", confidence: " + response.getConfidence() +
    82.                     //The time when the server detects the beginning of the sentence.
    83.                     ", begin_time: " + response.getSentenceBeginTime() +
    84.                     //The duration of currently processed audio streams, in milliseconds.
    85.                     ", time: " + response.getTransSentenceTime());
    86.             }
    88.             //Indicate that the recognition is completed.
    89.             @Override
    90.             public void onTranscriptionComplete(SpeechTranscriberResponse response) {
    91.                 System.out.println("task_id: " + response.getTaskId() + ", name: " + response.getName() + ", status: " + response.getStatus());
    92.             }
    94.             @Override
    95.             public void onFail(SpeechTranscriberResponse response) {
    96.                 System.out.println("task_id: " + response.getTaskId() +  ", status: " + response.getStatus() + ", status_text: " + response.getStatusText());
    97.             }
    98.         };
    100.         return listener;
    101.     }
    103.     // calculate the corresponding equivalent voice length based on the binary data size
    104.     public static int getSleepDelta(int dataSize, int sampleRate) {
    105.         int sampleBytes = 16;
    106.         // only supports single channel
    107.         int soundChannel = 1;
    108.         return (dataSize * 10 * 8000) / (160 * sampleRate);
    109.     }
    111.     public void process(String filepath) {
    112.         SpeechTranscriber transcriber = null;
    113.         try {
    114.             //Create an object and establish a connection
    115.             transcriber = new SpeechTranscriber(client, getTranscriberListener());
    116.             transcriber.setAppKey(appKey);
    117.             //Specify the audio coding format
    118.             transcriber.setFormat(InputFormatEnum.PCM);
    119.             //Specify the audio sampling rate
    120.             transcriber.setSampleRate(SampleRateEnum.SAMPLE_RATE_16K);
    121.             //Specify whether to return intermediate results
    122.             transcriber.setEnableIntermediateResult(false);
    123.             //Specify whether to add punctuation marks to the recognition result
    124.             transcriber.setEnablePunctuation(true);
    125.             //Specify whether to enable inverse text normalization (ITN). A value of true indicates that Chinese numerals are converted to Arabic numerals
    126.             transcriber.setEnableITN(false);
    128.             //Serialize preceding parameters to the JSON format and send them to the server for confirmation
    129.             transcriber.start();
    131.             File file = new File(filepath);
    132.             FileInputStream fis = new FileInputStream(file);
    133.             byte[] b = new byte[3200];
    134.             int len;
    135.             while ((len = fis.read(b)) > 0) {
    136.                 logger.info("send data pack length: " + len);
    137.                 transcriber.send(b);
    138.                 // if it is real-time speech, then no sleep, if it is 8k sample rate, the second parameter is changed to 8000
    139.                 // if 8000 sample rate, 3200 bytes is recommended for sleep 200ms. if 16000 sample rate, 3200 bytes is recommended for sleep 100ms.
    140.                 int deltaSleep = getSleepDelta(len, 16000);
    141.                 Thread.sleep(deltaSleep);
    142.             }
    144.             //Notify the server that all audio data has been sent and wait for the completion message from the server.
    145.             long now = System.currentTimeMillis();
    146.             logger.info("ASR wait for complete");
    147.             transcriber.stop();
    148.             logger.info("ASR latency : " + (System.currentTimeMillis() - now) + " ms");
    149.         } catch (Exception e) {
    150.             System.err.println(e.getMessage());
    151.         } finally {
    152.             if (null != transcriber) {
    153.                 transcriber.close();
    154.             }
    155.         }
    156.     }
    158.     public void shutdown() {
    159.         client.shutdown();
    160.     }
    162.     public static void main(String[] args) throws Exception {
    163.         String appKey = null;
    164.         String token = null;
    165.         String url = ""; // 默认即可，默认值：wss://nls-gateway-ap-southeast-1.aliyuncs.com/ws/v1
    167.         if (args.length == 2) {
    168.             appKey   = args[0];
    169.             token    = args[1];
    170.         } else if (args.length == 3) {
    171.             appKey   = args[0];
    172.             token    = args[1];
    173.             url      = args[2];
    174.         } else {
    175.             System.err.println("run error, need params(url is optional): " + "<app-key> <token> [url]");
    176.             System.exit(-1);
    177.         }
    179.         String filepath = "nls-sample-16k.wav";
    180.         SpeechTranscriberDemo demo = new SpeechTranscriberDemo(appKey, token, url);
    181.         demo.process(filepath);
    182.         demo.shutdown();
    183.     }
    184. }