Android SDK

Updated at:

Use the Android SDK for Short File Transcription to upload local audio files and receive transcription results through event callbacks. This page covers SDK integration, code samples, and key APIs.

Prerequisites and limitations

  • Activate the commercial service for Short File Transcription. This service does not offer a free trial. For the full service limitations, see the Short File Transcription API reference.

  • Obtain a project Appkey and a valid NLS token. See Manage projects and Obtain an access token.

  • Prepare a local audio file that the app can read. Supported formats are WAV, MP3, AAC, MP4, and OPUS. The file must not exceed 100 MB or 2 hours. The recognition model configured for the project must match the language of the audio.

Important

Keep the AccessKey ID and AccessKey secret on the server. Do not embed them in app code or store them on the mobile device. Obtain an NLS token on the server, send it to the app, and update it before it expires. Initialization parameters contain credentials and must not be logged in full.

Download and install

  1. Download an Android SDK package that supports Short File Transcription from Select and download mobile SDKs. Check the compatibility and compliance requirements on that page.

  2. Extract the SDK package. Copy MinSizeRel/nuisdk-release.aar to the app module's libs directory, and add the dependency to the module's build.gradle file.

    dependencies {
        implementation files('libs/nuisdk-release.aar')
    }
  3. Declare the network permission in AndroidManifest.xml.

    <uses-permission android:name="android.permission.INTERNET" />

The SDK package's example directory contains a ZIP archive of the demo project. Extract it and open the project in Android Studio to view FileTranscriberActivity.java. Before running the demo, configure the project Appkey, a valid NLS token, and the audio file to transcribe.

Starting with V2.6.2, cloud-only features do not require copying resource files or setting workspace.

ProGuard configuration

If code obfuscation is enabled, preserve the SDK classes in proguard-rules.pro.

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

Procedure

  1. Create a NativeNui instance. Pass an event callback that implements INativeFileTransCallback when initializing the SDK.

  2. Configure parameters with setParams as needed, or pass task parameters when starting transcription.

  3. Call startFileTranscriber to upload the local file, and save the task ID returned in the output buffer.

  4. Obtain the final result in the EVENT_FILE_TRANS_RESULT event, and handle errors in the EVENT_ASR_ERROR event.

  5. Call release when the SDK is no longer needed. To cancel a task, pass its task ID to cancelFileTranscriber.

Important

Run synchronous calls such as initialization off the UI thread. To avoid deadlocks, do not call SDK APIs directly from an SDK event callback. Submit cancellation, release, and similar operations to a worker thread outside the callback. Update the UI on the main thread.

Code samples

Transcribe a local file

The following example uses SDK V2.7.4-01B to transcribe example.wav in the app's private directory. Save a WAV file to the directory returned by getFilesDir(), and replace the Appkey, token, and device ID. Obtain the token on the server and send it to the app. A unique device ID is recommended. For a different file, update both the file path and nls_config.format. Add this Activity to the app project and register it in AndroidManifest.xml.

import android.app.Activity;
import android.os.Bundle;
import android.os.Handler;
import android.os.HandlerThread;
import android.util.Log;
import com.alibaba.idst.nui.AsrResult;
import com.alibaba.idst.nui.Constants;
import com.alibaba.idst.nui.INativeFileTransCallback;
import com.alibaba.idst.nui.NativeNui;
import org.json.JSONException;
import org.json.JSONObject;
import java.io.File;
import java.nio.charset.StandardCharsets;

public class FileTranscriberActivity extends Activity implements INativeFileTransCallback {
    private HandlerThread sdkThread;
    private Handler sdkHandler;
    private NativeNui nui;
    private String taskId;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        sdkThread = new HandlerThread("file-transcriber");
        sdkThread.start();
        sdkHandler = new Handler(sdkThread.getLooper());
        sdkHandler.post(() -> {
            try {
                startRecognition();
            } catch (JSONException e) {
                Log.e("FileTranscriber", "Invalid JSON parameters", e);
                releaseSDK();
            }
        });
    }

    private void startRecognition() throws JSONException {
        String filePath = new File(getFilesDir(), "example.wav").getAbsolutePath();
        JSONObject initParams = new JSONObject();
        initParams.put("app_key", "<APPKEY>");
        initParams.put("token", "<NLS_TOKEN>");
        initParams.put("device_id", "<DEVICE_ID>");
        initParams.put("url", "https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer");
        initParams.put("service_mode", Constants.ModeFullCloud);

        nui = new NativeNui();
        int ret = nui.initialize(this, initParams.toString(), Constants.LogLevel.LOG_LEVEL_NONE, false);
        if (ret != 0) {
            Log.e("FileTranscriber", "Initialize failed: " + ret);
            releaseSDK();
            return;
        }

        JSONObject config = new JSONObject();
        config.put("format", "wav");
        JSONObject params = new JSONObject();
        params.put("file_path", filePath);
        params.put("nls_config", config);

        byte[] taskIdBuffer = new byte[32];
        ret = nui.startFileTranscriber(params.toString(), taskIdBuffer);
        if (ret != 0) {
            Log.e("FileTranscriber", "Start failed: " + ret);
            releaseSDK();
            return;
        }
        taskId = new String(taskIdBuffer, StandardCharsets.UTF_8);
    }

    @Override
    public void onFileTransEventCallback(Constants.NuiEvent event, int resultCode,
                                        int arg2, AsrResult asrResult, String taskId) {
        if (event == Constants.NuiEvent.EVENT_FILE_TRANS_RESULT) {
            if (asrResult != null) {
                Log.i("FileTranscriber", asrResult.asrResult);
            }
            sdkHandler.post(this::releaseSDK);
        } else if (event == Constants.NuiEvent.EVENT_ASR_ERROR) {
            Log.e("FileTranscriber", "Recognition failed: " + resultCode);
            sdkHandler.post(this::releaseSDK);
        }
    }

    private void releaseSDK() {
        if (nui != null) {
            nui.release();
            nui = null;
            taskId = null;
        }
    }

    @Override
    protected void onDestroy() {
        sdkHandler.post(() -> {
            if (nui != null && taskId != null) {
                nui.cancelFileTranscriber(taskId);
            }
            releaseSDK();
            sdkThread.quitSafely();
        });
        super.onDestroy();
    }
}

Cancel transcription

To cancel an unfinished task, use the following code in the same Activity. SDK calls still run on the worker thread associated with sdkHandler.

sdkHandler.post(() -> {
    if (nui != null && taskId != null) {
        int ret = nui.cancelFileTranscriber(taskId);
        Log.i("FileTranscriber", "Cancel result: " + ret);
    }
});

Key SDK APIs

NativeNui.GetInstance() returns a singleton. To create an independent instance, use new NativeNui(). Release an instance before initializing it again. A return value of 0 from a synchronous method indicates that the call succeeded. Recognition results and asynchronous errors are delivered through event callbacks. For error codes and solutions, see Error codes.

Initialization and configuration

Initialize the SDK

public synchronized int initialize(INativeFileTransCallback callback,
                                   String parameters,
                                   Constants.LogLevel level);

public synchronized int initialize(INativeFileTransCallback callback,
                                   String parameters,
                                   Constants.LogLevel level,
                                   boolean save_log);

Parameter

Type

Description

callback

INativeFileTransCallback

File transcription event callback. Implement onFileTransEventCallback.

parameters

String

Initialization parameters in JSON format, including the Appkey, NLS token, device ID, and service URL.

level

Constants.LogLevel

SDK log level. Smaller enum values produce more logs.

save_log

boolean

Whether to save SDK logs to the directory specified by debug_path in the initialization parameters.

Set parameters

public synchronized int setParams(String params);

params is a JSON string used to configure recognition or update the NLS token. For initialization and task parameter fields, see the Mobile SDK guide.

Task control

public synchronized int startFileTranscriber(String params, byte[] taskId);
public synchronized int cancelFileTranscriber(String taskId);
public synchronized int release();

Method

Description

startFileTranscriber

Starts transcription. params is a task parameter JSON string containing file_path, audio format, and other settings. taskId is an output buffer that receives the task ID generated by the SDK. The example uses a 32-byte array.

cancelFileTranscriber

Cancels the specified task. Convert the task ID returned when transcription starts to a String and pass it to this method.

release

Releases resources when the SDK is no longer needed.

Event callbacks

void onFileTransEventCallback(Constants.NuiEvent event,
                             int resultCode,
                             int arg2,
                             AsrResult asrResult,
                             String taskId);

event is the event type. resultCode is the error code for EVENT_ASR_ERROR, arg2 is reserved, asrResult contains the recognition result, and taskId is the ID of the current task.

Event

Description

EVENT_FILE_TRANS_CONNECTED

Connected to the file transcription service.

EVENT_FILE_TRANS_UPLOADED

File uploaded.

EVENT_FILE_TRANS_RESULT

Final recognition result. Obtain it through asrResult.asrResult.

EVENT_ASR_ERROR

Recognition error. Handle it based on resultCode.

FAQ

How do I troubleshoot missing callbacks after starting transcription?

Check the return value of initialize, the INativeFileTransCallback implementation passed to it, and the SDK instance's lifecycle. Keep the instance while the task is running, and release it after the final result or error callback. Starting with V2.6.2, cloud-only features do not require copying model resource files.

How do I obtain task status and results?

Use onFileTransEventCallback to obtain status and results for the current task. EVENT_FILE_TRANS_UPLOADED indicates that the upload is complete, EVENT_FILE_TRANS_RESULT provides the final result, and EVENT_ASR_ERROR reports an error. Use the callback's taskId to associate the event with its task.

Are OPUS files supported?

Yes. Set file_path to an OPUS file that the app can read, and set nls_config.format to opus.

Related information

For secure credential retrieval and use on mobile devices, see Secure access to Intelligent Speech Interaction from mobile apps.