Android SDK
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.
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
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.
-
Extract the SDK package. Copy
MinSizeRel/nuisdk-release.aarto the app module'slibsdirectory, and add the dependency to the module'sbuild.gradlefile.dependencies { implementation files('libs/nuisdk-release.aar') } -
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
Create a
NativeNuiinstance. Pass an event callback that implementsINativeFileTransCallbackwhen initializing the SDK.Configure parameters with
setParamsas needed, or pass task parameters when starting transcription.Call
startFileTranscriberto upload the local file, and save the task ID returned in the output buffer.Obtain the final result in the
EVENT_FILE_TRANS_RESULTevent, and handle errors in theEVENT_ASR_ERRORevent.Call
releasewhen the SDK is no longer needed. To cancel a task, pass its task ID tocancelFileTranscriber.
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 |
|
|
INativeFileTransCallback |
File transcription event callback. Implement |
|
|
String |
Initialization parameters in JSON format, including the Appkey, NLS token, device ID, and service URL. |
|
|
Constants.LogLevel |
SDK log level. Smaller enum values produce more logs. |
|
|
boolean |
Whether to save SDK logs to the directory specified by |
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 |
|
|
Starts transcription. |
|
|
Cancels the specified task. Convert the task ID returned when transcription starts to a String and pass it to this method. |
|
|
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 |
|
|
Connected to the file transcription service. |
|
|
File uploaded. |
|
|
Final recognition result. Obtain it through |
|
|
Recognition error. Handle it based on |
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.