Skip to main content

Fun-ASR non-real-time speech recognition Android SDK

This guide shows you how to convert speech to text with the Fun-ASR non-real-time speech recognition Android SDK.

For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.

Quick start

  1. Get an API key: Obtain an API key. For better security, store the API key in an environment variable.
  2. Download the SDK and run the sample code:
    • Download the latest SDK package.
    • Extract the ZIP package. Find the AAR-format SDK in the app/libs directory and add it to your project dependencies. For Android C++ integration, use android_libs and android_include in the ZIP package to get the dynamic libraries and header files.
    • Open the project in Android Studio. The sample code is in DashFunAsrFileTranscriberActivity.java. Replace the API key, then try out the feature.

Call procedure

  • Synchronous mode
  • Asynchronous mode
  1. Initialize the SDK.
  2. Configure the parameters that your business requires.
  3. Set async_request to false and call startFileTranscriber to submit a non-real-time speech recognition request and wait for the result.
  4. Listen for the EVENT_FILE_TRANS_RESULT event in the onFileTransEventCallback interface to get the final recognition result.
  5. Call release to release the SDK resources.

Request parameters

Connection and control parameters

Configure these parameters by passing a JSON string in the parameters argument of the initialize interface. Parameter example The following JSON string is an example and does not list every parameter. Add the parameters you need when you write your code: 
{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Parameter description
ParameterTypeRequiredDescription
urlStringYesService endpoints:
  • wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
  • China (Beijing): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
  • Singapore: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Replace {WorkspaceId} with your actual Workspace ID.
apikeyStringYesThe API key.
service_modeStringYesThe run mode. Fixed to "1" for recorded speech recognition.
device_idStringYesA unique string that identifies the end user. Set it to an in-app user ID or a device identifier generated by the client. This ID is mainly used for log tracing and troubleshooting.
debug_pathStringNoThe storage path for the log file.This parameter takes effect only when save_log is set to true in the initialize interface. In that case, you must set the log file path, or an error is reported.At most two log files are kept locally.
max_log_file_sizeintNoThe maximum size of the log file, in bytes.This parameter takes effect only when save_log is set to true in the initialize interface.Default: 104857600 (100 * 1024 * 1024 bytes, that is, 100 MiB).
log_track_levelintNoThe filter level for the log content sent through the log callback (onFileTransLogTrackCallback).Default: 2.Valid values:
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (turns off this feature)
Note: log_track_level and level (set through the initialize interface) together determine which logs are ultimately sent to the callback. A log is sent to the callback only when its level value is greater than or equal to both log_track_level and level. For example, if log_track_level is set to 2 (INFO) and level is set to 3 (WARNING), only logs at WARNING level or higher (value >= 3) are sent to the callback.

Speech recognition parameters

Configure all speech recognition parameters through the startFileTranscriber interface. Parameter example The following JSON string is an example and does not list every parameter. Add the parameters you need when you write your code: 
{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}
Parameter description
ParameterTypeRequiredDescription
file_urlsarray[string]YesA list of URLs of the audio or video files to transcribe. HTTP and HTTPS are supported. A single request supports only one URL. For input requirements such as supported audio formats, file size limits, and duration limits, see Audio specifications.If the recording is stored in Alibaba Cloud OSS, the RESTful API supports temporary URLs prefixed with oss://, whereas the SDK does not support oss://-prefixed temporary URLs.
  • A temporary URL is valid for 48 hours and cannot be used after it expires. Do not use it in production.
  • The upload credential interface is rate-limited to 100 QPS and cannot be scaled up. Do not use it in production, high-concurrency, or load-testing scenarios.
  • For production, use stable storage such as Alibaba Cloud OSS to keep files available long-term and avoid rate limiting.
  • If an audio file URL set to an OSS temporary public URL is unreachable, set X-DashScope-OssResourceResolve to enable in the request header (not recommended). The SDK does not support configuring request headers.
async_requestbooleanNoWhether the recognition request is asynchronous.Default: false.Valid values:
  • true: asynchronous request
  • false: synchronous request
apikeystringNoIf the apikey in Connection and control parameters is a temporary API key, you can update it here to avoid expiration.
nls_configobjectYesThe core configuration object for speech recognition. It contains key parameters such as model selection and recognition control.
nls_config.modelstringYesThe model name.
nls_config.special_word_filterobjectNoThe sensitive words to process during speech recognition. You can set a different handling method for each sensitive word. For details, see Sensitive word filtering.
nls_config.channel_idarray[integer]NoThe index of the audio tracks to recognize in a multi-track audio file. The index starts at 0. For example, [0] recognizes the first track, and [0, 1] recognizes the first and second tracks at the same time. If you omit this parameter, only the first track is processed.
Each specified track is billed independently. For example, requesting [0, 1] for a single file incurs two separate charges.
Default value: [0].
nls_config.diarization_enabledbooleanNoWhether to enable speaker diarization. Disabled by default.Applies only to mono audio. Multi-channel audio does not support speaker diarization.When enabled, the recognition result includes a speaker_id field that distinguishes different speakers.
When speaker diarization is enabled, keep the audio duration within 2 hours. Otherwise, recognition may fail or time out.
Default: false.For an example of speaker_id, see Recognition result description.
nls_config.speaker_countintegerNo
Takes effect only when speaker diarization is enabled (diarization_enabled is set to true).
A reference value for the number of speakers. The valid range is an integer from 2 to 100 (inclusive).By default, the number of speakers is detected automatically. If you set this value, it only guides the algorithm to output the specified count when possible and does not guarantee that exact count.No default value.
nls_config.vocabulary_idstringNoThe ID of a precompiled hot word list.Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list.Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests.For usage details, see Precompiled hotwords.
nls_config.instant_vocabularyobjectNoInstant hotwords. Pass key-value pairs whose keys are hotword strings (string) and whose values are integer weights (integer). No precompiled hotword list is required.For usage, see Instant hotwords.
{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]NoThe language codes to recognize. If you can't determine the language in advance, leave it unset and the model detects the language automatically.You can set up to 1 value. If you set more, only the first 1 take effect.
  • zh: Chinese
  • en: English
  • ja: Japanese
  • ko: Korean
  • vi: Vietnamese
  • th: Thai
  • id: Indonesian
  • ms: Malay
  • tl: Filipino
  • hi: Hindi
  • ar: Arabic
  • fr: French
  • de: German
  • es: Spanish
  • pt: Portuguese
  • ru: Russian
  • it: Italian
  • nl: Dutch
  • sv: Swedish
  • da: Danish
  • fi: Finnish
  • no: Norwegian
  • el: Greek
  • pl: Polish
  • cs: Czech
  • hu: Hungarian
  • ro: Romanian
  • bg: Bulgarian
  • hr: Croatian
  • sk: Slovak

Key interfaces

NativeNui

initialize

Initializes the speech recognition SDK instance. The SDK is a singleton. Do not initialize it again before you call release. This interface blocks, so call it on a non-UI thread. Method signature 
public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
Parameter description
ParameterTypeDescription
callbackINativeFileTransCallbackThe implementation of the event and data callback interface.
parametersStringA JSON string that contains the authentication, connection, and debugging parameters. See Connection and control parameters.
levelConstants.LogLevelControls the print level of the SDK's own logs.
save_logbooleanWhether to save logs locally. If true, specify the path with debug_path in Connection and control parameters, and optionally set the file size with max_log_file_size.

setParams

Use this interface to set or update the nls_config parameters separately. If you provide all parameters at once in startFileTranscriber, you don't need to call this method. Method signature 
public synchronized int setParams(String params);
Parameter description
ParameterTypeDescription
paramsStringThe nls_config parameter in Speech recognition parameters. Parameters other than nls_config cannot be set through this method.Example:
{
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}

startFileTranscriber

Starts recognition. Method signature 
public synchronized int startFileTranscriber(String params, byte[] task_id)
Parameter description
ParameterTypeDescription
paramsStringSpeech recognition parameters.Example:
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}
task_idbyte[]The task ID. The SDK generates a random string internally. You get the task_id after this interface returns successfully.

queryFileTranscriber

Use this interface to query the current status and result of an asynchronous task. After the call succeeds, the result is returned through the EVENT_FILE_TRANS_QUERY_RESULT event in the onFileTransEventCallback callback.
Obtain the task_id passed to this method from the EVENT_FILE_TRANS_UPLOADED event.
Method signature 
public synchronized int queryFileTranscriber(String task_id)
Parameter description
ParameterTypeDescription
task_idStringThe ID of the task to query, obtained from the EVENT_FILE_TRANS_UPLOADED event.

cancelFileTranscriber

Cancels the current task immediately. Method signature 
public synchronized int cancelFileTranscriber(String task_id)
Parameter description
ParameterTypeDescription
task_idStringThe ID of the task to cancel, obtained from the EVENT_FILE_TRANS_UPLOADED event.

release

Releases all internal resources of the SDK. After you call this method, the SDK instance becomes unusable. To use it again, you must call initialize to initialize it again. Method signature 
public synchronized int release();

GetVersion

Gets the current SDK version information. Method signature 
public synchronized String GetVersion();
Return value The current SDK version information.

INativeFileTransCallback: listener callbacks

onFileTransEventCallback: listen for events and recognition results

Method signature 
void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);
Parameter description
ParameterTypeDescription
eventNuiEventThe callback event.
resultCodeintValid only when the EVENT_ASR_ERROR event occurs.
asrResultAsrResultThe speech recognition result.
taskIdStringThe task ID.
arg2intA reserved parameter.

onFileTransLogTrackCallback: listen for trace logs

This callback receives the SDK's detailed internal logs for problem diagnosis and debugging. 
default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent: event types

EventDescription
EVENT_FILE_TRANS_CONNECTEDThe service connection succeeded.
EVENT_FILE_TRANS_UPLOADEDThe audio file to recognize was uploaded successfully. You can now obtain the task_id of the current task.
EVENT_FILE_TRANS_QUERY_RESULTA task result query.
EVENT_FILE_TRANS_RESULTThe final recognition result.
EVENT_ASR_ERRORAn error occurred during speech recognition.