文档

Android SDK

更新时间:
一键部署

本文介绍了如何使用阿里云智能语音服务提供的Android NUI SDK,包括SDK下载安装、关键接口及代码示例。

前提条件

下载安装

  1. 下载SDK和示例代码

    重要

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

    类别

    兼容范围

    系统

    支持Android 4.0以上版本,API LEVEL 14

    架构

    armeabi-v7a,arm64-v8a,x86,x86_64

    此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为文件,存储目录为ticket中的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.*{*;}

代码示例

说明

您如果有多例需求,也可以直接new对象进行使用。也可采用GetInstance获得单例。

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,注意用户需要在genInitParams中填入相关ID信息才可以使用。
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方式:

        JSONObject object = new JSONObject();

        //账号和项目创建
        //  ak_id ak_secret app_key如何获得,请查看https://help.aliyun.com/document_detail/72138.html
        object.put("app_key", "<您申请创建的app_key>"); // 必填

        //方法1:
        //  首先ak_id ak_secret app_key如何获得,请查看https://help.aliyun.com/document_detail/72138.html
        //  然后请看 https://help.aliyun.com/document_detail/466615.html 使用其中方案一获取临时凭证
        //  此方案简介: 远端服务器运行STS生成具有有效时限的临时凭证, 下发给移动端进行使用, 保证账号信息ak_id和ak_secret不被泄露
        //  获得Token方法(运行在APP服务端): https://help.aliyun.com/document_detail/450255.html?spm=a2c4g.72153.0.0.79176297EyBj4k
        object.put("token", "<服务器生成的具有时效性的临时凭证>"); // 必填

        //方法2:
        //  STS获取临时凭证方法暂不支持

        object.put("device_id", Utils.getDeviceId()); // 必填, 推荐填入具有唯一性的id, 方便定位问题
        object.put("url", "wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1"); // 默认
        object.put("workspace", workpath); // 必填, 且需要有读写权限

        //debug目录,当初始化SDK时的save_log参数取值为true时,该目录用于保存中间音频文件。
        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字符串形式进行设置。

//设置相关识别参数,具体参考API文档
//  initialize()之后startDialog之前调用
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。
NativeNui.GetInstance().startDialog(Constants.VadMode.TYPE_P2T, genDialogParams());

private String genDialogParams() {
    String params = "";
    try {
        JSONObject dialog_param = new JSONObject();
        //运行过程中可以在startDialog时更新参数,尤其是更新过期token
        //dialog_param.put("token", "");
        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();

常见问题

Android SDK是否可以上传OPUS音频数据,实现实时语音转文字?

ASR中一句话识别和录音文件极速版支持OPUS数据,实时语音转文字仅支持PCM编码、16 bit采样位数、单声道(mono)。具体详情请参见接口说明

在模拟器上运行下载的Android Demo程序,语音合成功能正常,但一句话识别功能单击“开始”后,程序出现闪退现象,是什么原因?

模拟器可能会出现未知问题,建议您使用真机测试。

频繁出现语音识别(一句话识别)一直回调onNuiNeedAudioData,但在onNuiEventCallback(识别结果回调)中没收到回调相应,大概过了几十秒后才在onNuiEventCallback中回调显示状态码50000000是什么原因?

服务错误,可能和SDK运行状态异常有关。建议您提供从SDK初始化到问题出现的完整Logcat有助于问题定位。

调用Android SDK时,手机报错提示“audio recoder not init”如何解决?

您可以通过以下方式排查:

  • 检查AudioRecord是否初始化正常。

  • 检查语音播放器是否有问题。

  • 系统的录音模块代码如下,也可单独编写AudioRecord录音代码,测试是否正常。编写AudioRecord录音代码

int ret = nui_instance.initialize(this, genInitParams(assets_path,debug_path), Constants.LogLevel.LOG_LEVEL_VERBOSE, true)。录音权限已打开,但代码仍然报错240021是什么原因?

240021表示FILE_ACCESS_FAIL文件访问错误。请完成以下操作:

  • 检查是否有文件读写权限。

  • 检查是否完成SDK调用、是否完成SDK配置文件的拷贝。

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

  • 本页导读 (1)
文档反馈