Android SDK

前提条件

• 使用SDK前，首先阅读接口说明，详情请参见接口说明。

• 已获取项目Appkey，详情请参见创建项目。

• 已获取Access Token，详情请参见获取Token概述。

下载安装

1. 下载SDK和示例代码。

   重要

   请下载后在样例初始化代码中替换您的阿里云账号信息、Appkey和Token才可运行。

   类别	兼容范围
   系统	支持Android 4.0 以上版本，API LEVEL 14
   架构	armeabi-v7a，arm64-v8a

   此SDK还包含如下功能，若未支持您想要的功能，请去对应文档获取SDK。

   功能	是否支持
   一句话识别	是
   实时语音识别	是
   语音合成	是
   实时长文本语音合成	是
   录音文件识别极速版	是
   唤醒及命令词	否

2. 解压ZIP包，在app/libs目录下获取AAR格式的SDK包，将AAR包集成到您的工程项目中进行依赖。

3. 使用Android Studio打开此工程查看参考代码实现，其中一句话识别示例代码为SpeechRecognizerActivity.java文件，替换Appkey和Token后可直接运行。

SDK关键接口

• initialize：初始化SDK。

  /**
       * 初始化SDK，SDK为单例，请先释放后再次进行初始化。请勿在UI线程调用，可能会引起阻塞。
       * @param callback：事件监听回调，参见下文具体回调。
       * @param parameters：json string形式的初始化参数，参见下方说明或接口说明：https://help.aliyun.com/document_detail/173298.html。
       * @param level：log打印级别，值越小打印越多。
       * @param save_log：是否保存log为文件，存储目录为parameter中的debug_path字段值。
       * @return：参见错误码：https://help.aliyun.com/document_detail/459864.html。
       */
  public synchronized int initialize(final INativeNuiCallback callback,
                                             String parameters,
                                             final Constants.LogLevel level,
                                             final boolean save_log);

  其中，INativeNuiCallback类型包含如下回调。

  • onNuiAudioStateChanged：根据音频状态进行录音功能的开关。

    /**
         * 当start/stop/cancel等接口调用时，SDK通过此回调通知App进行录音的开关操作。
         * @param state：录音需要的状态（打开/关闭）。
         */
        void onNuiAudioStateChanged(AudioState state);

  • onNuiNeedAudioData：在回调中提供音频数据。

    /**
         * 开始识别时，此回调被连续调用，App需要在回调中进行语音数据填充。
         * @param buffer：填充语音的存储区。
         * @param len：需要填充语音的字节数。
         * @return：实际填充的字节数。
         */
        int onNuiNeedAudioData(byte[] buffer, int len);

  • onNuiEventCallback：SDK事件回调。

    /**
         * SDK主要事件回调
         * @param event：回调事件，参见如下事件列表。
         * @param resultCode：参见错误码，在出现EVENT_ASR_ERROR事件时有效。
         * @param arg2：保留参数。
         * @param kwsResult：语音唤醒功能。
         * @param asrResult：语音识别结果。
         */
        void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

  • onNuiAudioRMSChanged：音频能量值回调。

    /**
         * 音频能量值回调
         * @param val: 音频数据能量值回调，范围-160至0，一般用于UI展示语音动效
         */
        public void onNuiAudioRMSChanged(float val);

    事件列表：

    名称	说明
    EVENT_VAD_START	检测到人声起点。
    EVENT_VAD_END	检测到人声尾点。
    EVENT_ASR_PARTIAL_RESULT	语音识别中间结果。
    EVENT_ASR_RESULT	语音识别最终结果。
    EVENT_ASR_ERROR	根据错误码信息判断出错原因。
    EVENT_MIC_EEROR	录音错误，表示SDK连续2秒未收到任何音频，可检查录音系统是否正常。

• setParams：以JSON格式设置SDK参数。

  /**
       * 以JSON格式设置参数
       * @param params：参见接口说明:https://help.aliyun.com/document_detail/173298.html。
       * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
       */
      public synchronized int setParams(String params);

• startDialog：开始识别。

  /**
       * 开始识别
       * @param vad_mode：多种模式，对于识别场景，请使用P2T。
       * @param dialog_params：json string形式的对话参数，参见接口说明：https://help.aliyun.com/document_detail/173298.html。
       * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
       */
      public synchronized int startDialog(VadMode vad_mode, String dialog_params);

• stopDialog：结束识别。

  /**
       * 结束识别，调用该接口后，服务端将返回最终识别结果并结束任务。
       * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
       */
      public synchronized int stopDialog();

• release：释放SDK。

  /**
       * 释放SDK资源
       * @return：参见错误码:https://help.aliyun.com/document_detail/459864.html。
       */
      public synchronized int release();

调用步骤

1. 初始化SDK、录音实例。

2. 根据业务需求设置参数。

3. 调用startDialog开始识别。

4. 根据音频状态回调onNuiAudioStateChanged，打开录音机。

5. 在onNuiNeedAudioData回调中提供录音数据。

6. 在EVENT_ASR_PARTIAL_RESULT事件回调中获取识别结果。

7. 调用stopDialog结束识别。并从EVENT_ASR_RESULT事件回调中获得最终识别结果。

8. 结束调用，使用release接口释放SDK资源。

Proguard配置

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

-keep class com.alibaba.idst.nui.*{*;}

代码示例

NUI SDK初始化

//这里获得资源路径, 即工作路径
//  内部通过context.getApplicationContext().getFilesDir().toString() + "/asr_my" 创建工作路径，
//  例如 /data/user/0/mit.alibaba.nuidemo/files/asr_my
String workspace = CommonUtils.getModelPath(this);

//创建debug路径
String debug_path = getExternalCacheDir().getAbsolutePath() + "/debug_" + System.currentTimeMillis();
Utils.createDir(debug_path);

//从nuisdk.aar中assets资源拷贝到workspace中
CommonUtils.copyAssetsData(this);

//SDK初始化
NativeNui nui_instance = new NativeNui();
int ret = nui_instance.initialize(this, genInitParams(workspace, debug_path), Constants.LogLevel.LOG_LEVEL_VERBOSE, true);

其中，genInitParams生成String JSON字符串，包含资源目录和用户信息。其中用户信息包含如下字段。

private String genInitParams(String workpath, String debugpath) {
    String str = "";
    try{
        //获取token方式一般有两种：

        //方法1：
        //参考Auth类的实现在端上访问阿里云Token服务获取SDK进行获取
        //JSONObject object = Auth.getAliYunTicket();

        //方法2：（推荐做法）
        //在您的服务端进行token管理，此处获取服务端的token进行语音服务访问


        //请输入您申请的id与token，否则无法使用语音服务，获取方式请参考阿里云官网文档：
        //https://help.aliyun.com/document_detail/72153.html?spm=a2c4g.11186623.6.555.59bd69bb6tkTSc
        JSONObject object = new JSONObject();

        //token 24小时过期，因此需要通过阿里云SDK来进行更新
        //接口说明可见: https://help.aliyun.com/document_detail/173298.html
        //查看 1. 鉴权和初始化
        object.put("app_key", ""); // 必填
        object.put("token", ""); // 必填
        object.put("workspace", workpath); // 必填
        object.put("device_id", Utils.getDeviceId()); // 必填
        object.put("url", "wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1");
        object.put("debug_path", debugpath);

        // FullMix = 0   // 选用此模式开启本地功能并需要进行鉴权注册
        // FullCloud = 1
        // FullLocal = 2 // 选用此模式开启本地功能并需要进行鉴权注册
        // AsrMix = 3    // 选用此模式开启本地功能并需要进行鉴权注册
        // AsrCloud = 4
        // AsrLocal = 5  // 选用此模式开启本地功能并需要进行鉴权注册
        object.put("service_mode", Constants.ModeAsrCloud); // 必填
        str = object.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }

    Log.i(TAG, "InsideUserContext:" + str);
    return str;
}

参数设置

以JSON字符串形式进行设置。

nui_instance.setParams(genParams());

private String genParams() {
    String params = "";
    try {
        JSONObject nls_config = new JSONObject();

        //开启语音识别中间结果
        nls_config.put("enable_intermediate_result", true);

        //当未设置如下参数，在Constants.VadMode.TYPE_P2T模式startDialog时，只有stopDialog()后才能获得最终结果。
        //当开启如下人声检测参数，在Constants.VadMode.TYPE_P2T模式中当停止说话会自动返回一句话识别最终结果。
        //nls_config.put("enable_voice_detection", true);
        //nls_config.put("max_start_silence", 10000);
        //nls_config.put("max_end_silence", 800);
        
        //更多参数可根据实际业务进行配置
        //接口说明可见: https://help.aliyun.com/document_detail/173298.html
        //nls_config.put("enable_punctuation_prediction", true);
        //nls_config.put("enable_inverse_text_normalization", true);
        //nls_config.put("customization_id", "test_id");
        //nls_config.put("vocabulary_id", "test_id");
        //nls_config.put("sample_rate", 16000);
        //nls_config.put("sr_format", "opus");
        JSONObject parameters = new JSONObject();

        parameters.put("nls_config", nls_config);
        parameters.put("service_type", Constants.kServiceTypeASR); // 必填

        //如果有HttpDns则可进行设置
        //parameters.put("direct_ip", Utils.getDirectIp());

        params = parameters.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }
    return params;
}

开始识别

通过startDialog接口开启监听。

//默认使用Constants.VadMode.TYPE_P2T。
//Constants.VadMode.TYPE_VAD只在具有离线功能的SDK中支持，若想要启动VAD，请设置参数enable_voice_detection。
nui_instance.startDialog(Constants.VadMode.TYPE_P2T, genDialogParams());

private String genDialogParams() {
    String params = "";
    try {
        JSONObject dialog_param = new JSONObject();
        params = dialog_param.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }
    return params;
}

回调处理

• onNuiAudioStateChanged：录音状态回调，SDK内部维护录音状态，调用时根据该状态的回调进行录音机的开关操作。

  public void onNuiAudioStateChanged(Constants.AudioState state) {
          Log.i(TAG, "onNuiAudioStateChanged");
          if (state == Constants.AudioState.STATE_OPEN) {
              Log.i(TAG, "audio recorder start");
              mAudioRecorder.startRecording();
          } else if (state == Constants.AudioState.STATE_CLOSE) {
              Log.i(TAG, "audio recorder close");
              mAudioRecorder.release();
          } else if (state == Constants.AudioState.STATE_PAUSE) {
              Log.i(TAG, "audio recorder pause");
              mAudioRecorder.stop();
          }
      }

• onNuiNeedAudioData：录音数据回调，在该回调中填充录音数据。

  public int onNuiNeedAudioData(byte[] buffer, int len) {
          int ret = 0;
          if (mAudioRecorder.getState() != AudioRecord.STATE_INITIALIZED) {
              Log.e(TAG, "audio recorder not init");
              return -1;
          }
          ret = mAudioRecorder.read(buffer, 0, len);
          //返回值告知SDK读到了多少数据，如果返回<0，则表示出错，返回0，则表示无录音数据。
          return ret;
      }

• onNuiEventCallback：NUI SDK事件回调，请勿在事件回调中调用SDK的接口，可能引起死锁。

  public void onNuiEventCallback(Constants.NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult) {
          Log.i(TAG, "event=" + event);
          if (event == Constants.NuiEvent.EVENT_ASR_RESULT) {
              showText(asrView, asrResult.asrResult);
          } else if (event == Constants.NuiEvent.EVENT_ASR_PARTIAL_RESULT) {
              showText(asrView, asrResult.asrResult);
          } else if (event == Constants.NuiEvent.EVENT_ASR_ERROR) {
              ;
          }
      }

结束识别

nui_instance.stopDialog();

释放SDK

nui_instance.release();

if (CommonUtils.copyAssetsData(this)) {
Log.i(TAG, "copy assets data done");
} else {
Log.i(TAG, "copy assets failed");
return;
}