Android SDK

Prerequisites

• Read the API Reference before you use the SDK.

• Prepare your project's app key. For details, see Create a Project.

• Obtain an access token. For details, see Get an Access Token.

Download and install

1. Select and download mobile SDKs.

2. Unzip the ZIP package, locate the SDK package in AAR format in the app/libs directory, and add it as a dependency to your project.

3. Open the project in Android Studio to view the reference implementation. The sample code is in the FileTranscriberActivity.java file. You can run the project directly after you replace the app key and token.

Key SDK APIs

• initialize: Initializes the SDK.

  /**
   * Initializes the SDK, which uses a singleton pattern. To re-initialize, you must first release the existing instance.
   * Do not call this method on the UI thread, as it may cause blocking.
   * @param callback The event listener for transcription events.
   * @param parameters: The initialization parameters. See the API Reference.
   * @param level: The log level. A smaller value results in more detailed logs.
   * @return: See error codes.
   */
  public synchronized int initialize(final INativeFileTransCallback callback,
                                     String parameters,
                                     final Constants.LogLevel level)

  You must implement the onFileTransEventCallback method for the INativeFileTransCallback interface.

  onFileTransEventCallback: File transcription event callback.

  /**
       * The main SDK event callback.
       * @param event: The callback event. See the event list below.
       * @param resultCode The error code. This parameter is valid only for EVENT_ASR_ERROR events.
       * @param arg2: Reserved parameter.
       * @param asrResult: The speech recognition result.
       * @param taskId: The transcription task ID.
       */
      void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);

  Event list:

  Name	Description
  EVENT_FILE_TRANS_CONNECTED	Successfully connected to the file transcription service.
  EVENT_FILE_TRANS_UPLOADED	File uploaded successfully.
  EVENT_FILE_TRANS_RESULT	The final recognition result.
  EVENT_ASR_ERROR	An error occurred. Use the resultCode to determine the cause.

• setParams: Sets SDK parameters in JSON format.

  /**
   * Sets parameters in JSON format.
   * @param params: See the API Reference.
   * @return: See error codes.
   */
  public synchronized int setParams(String params)

• startFileTranscriber: Starts file transcription.

  /**
   * Starts the transcription.
   * @param params: The transcription parameters. See the API Reference.
   * @param taskId An output parameter. The SDK populates this byte array with the generated task ID.
   * @return: See error codes.
   */
  public synchronized int startFileTranscriber(String params, byte[] taskId)

• stopFileTranscriber: Stops the transcription.

  /**
   * Stops the transcription.
   * @return: See error codes.
   */
  public synchronized int stopFileTranscriber(String taskId)

• release: Releases the SDK.

  /**
   * Releases SDK resources.
   * @return: See error codes.
   */
  public synchronized int release()

Procedure

1. Initialize the SDK.

2. Set parameters based on your business requirements.

3. Call startFileTranscriber to start transcription.

4. Get the final recognition result from the EVENT_FILE_TRANS_RESULT event.

5. When you are finished, call the release() method to free up SDK resources.

Proguard configuration

If your code uses obfuscation, add the following rule to proguard-rules.pro:

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

Code samples

Initialize the NUI SDK

// Call this to copy the SDK configuration files.
CommonUtils.copyAssetsData(this);
// Get the workspace path.
String assets_path = CommonUtils.getModelPath(this);
Log.i(TAG, "use workspace " + assets_path);
int ret = nui_instance.initialize(this, genInitParams(assets_path, debug_path), Constants.LogLevel.LOG_LEVEL_VERBOSE);

The genInitParams method generates a JSON string that includes the resource directory and user information. The user information contains the following fields.

private String genInitParams(String workpath, String debugpath) {
    String str = "";
    try{
        // How to obtain a token:
        JSONObject object = new JSONObject();
        // Account and project creation
        // To learn how to obtain an ak_id, ak_secret, and app_key, see https://help.aliyun.com/document_detail/72138.html
        object.put("app_key", "<your_app_key>"); // Required
        // Method 1 (Highly recommended)
        //  First, see https://help.aliyun.com/document_detail/72138.html to learn how to obtain an ak_id, ak_secret, and app_key.
        //  Then, see https://help.aliyun.com/document_detail/466615.html and use Method 1 to obtain temporary credentials.
        //  Summary: Your remote server generates temporary credentials with a limited validity period and sends them to the mobile client. This prevents your `ak_id` and `ak_secret` from being leaked.
        //  To learn how to obtain a token (this runs on your app server), see https://help.aliyun.com/document_detail/450255.html?spm=a2c4g.72153.0.0.79176297EyBj4k
        object.put("token", "<your_time_limited_temporary_token>"); // Required
        // Method 2:
        //  Obtaining temporary credentials through STS is not currently supported.
        // Method 3 (Strongly not recommended due to the risk of exposing your Alibaba Cloud account credentials)
        //  Use the implementation in the Auth class to access the Alibaba Cloud Token service from the client side. Do not store your AK/SK locally or in the client-side environment.
        //  Pro: The token is obtained on the client side, so you do not need a dedicated app server.
        //  Con: The AK/SK information on the client side is highly vulnerable to leakage.
//            JSONObject object = Auth.getAliYunTicket();
        object.put("url", "https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer"); // Required. This is the endpoint for the China (Shanghai) region.
        object.put("device_id", Utils.getDeviceId()); // Required. We recommend using a unique ID for easier troubleshooting. You can also use the provided Utils.getDeviceId().
        // The workspace path from which the SDK reads configuration files.
        object.put("workspace", workpath); // Required. Must have read and write permissions.
        // The debug directory. If the save_log parameter is set to true during SDK initialization, this directory is used to save intermediate audio files.
        object.put("debug_path", debugpath);
        // FullMix = 0   // Select this mode to enable local functions. This requires authentication and registration.
        // FullCloud = 1
        // FullLocal = 2 // Select this mode to enable local functions. This requires authentication and registration.
        // AsrMix = 3    // Select this mode to enable local functions. This requires authentication and registration.
        // AsrCloud = 4
        // AsrLocal = 5  // Select this mode to enable local functions. This requires authentication and registration.
        // Only FullMix and FullCloud can be selected here.
        object.put("service_mode", Constants.ModeFullCloud); // Required
        str = object.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }
    return str;
}

Start transcription

Call the startFileTranscriber method to start transcription.

byte[] task_id = new byte[32];
NativeNui.GetInstance().startFileTranscriber(genDialogParams(), taskId);
private String genDialogParams() {
    String params = "";
    try {
        JSONObject dialog_param = new JSONObject();
        // To switch the app_key at runtime:
        //dialog_param.put("app_key", "");
        dialog_param.put("file_path", "/sdcard/test.wav");
        JSONObject nls_config = new JSONObject();
        nls_config.put("format", "wav");
        dialog_param.put("nls_config", nls_config);
        params = dialog_param.toString();
    } catch (JSONException e) {
        e.printStackTrace();
    }
    Log.i(TAG, "dialog params: " + params);
    return params;
}

Handle callbacks

onFileTransEventCallback: This is the NUI SDK event callback. To prevent a deadlock, do not call other SDK APIs from within this callback.

public void onFileTransEventCallback(Constants.NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId) {
        Log.i(TAG, "event=" + event);
    	if (event == Constants.NuiEvent.EVENT_FILE_TRANS_RESULT) {
            showText(asrView, asrResult.asrResult);
        } else if (event == Constants.NuiEvent.EVENT_ASR_ERROR) {
            ;
        }
    }

FAQ