Paraformer non-real-time speech recognition Android SDK

Paraformer models are available only in the China North 2 (Beijing) region. Use an API key created in that region. See Regions and endpoints.

User guide: For an introduction to the models and for selection advice, see Audio file recognition.

Getting started

Obtain an API key: Obtain and configure an API key. For security, configure the API key as an environment variable.

You can use a temporary API key to grant temporary access permissions or to strictly control risky operations, such as accessing or deleting sensitive data. A temporary API key is valid for 60 seconds by default and must be retrieved again after it expires.

Download the SDK and run the sample code:
- Download the latest SDK package.
- Unzip the package. In the app/libs directory, find the SDK in AAR format and add it to your project dependencies.
  For Android C++ integration, use the android_libs and android_include directories in the ZIP package to obtain the dynamic libraries and header files.
- Open the project in Android Studio. The sample code is located in DashParaformerFileTranscriberActivity.java. Replace the API key and test the feature.

Invocation steps

Synchronous mode
Asynchronous mode

Initialize the SDK.
Configure the parameters as needed.
You can start a synchronous recognition task by calling startFileTranscriber with async_request set to false.
In the onFileTransEventCallback interface, you can listen for the EVENT_FILE_TRANS_RESULT event to obtain the final recognition result.
You can call release to release SDK resources.

Initialize the SDK.
Configure the parameters as needed.
Call startFileTranscriber to start the recognition task (set async_request to true).
Call queryFileTranscriber to query the recognition progress or results.
In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_QUERY_RESULT event to retrieve the current query result.
In the onFileTransEventCallback interface, listen for the EVENT_FILE_TRANS_RESULT event to obtain the final recognition result.
Call release to release the SDK resources.

Request parameters

Connection and control parameters

To configure these settings, pass a JSON string to the parameters parameter of the initialize interface.

Example: The following JSON string is an example that does not list all available parameters. Add parameters as needed.

The following uses the China North 2 (Beijing) endpoint. Paraformer is available only in this region. API keys are region-specific. See Regions and endpoints.

{
    "url": "wss://cn-beijing.maas.qwencloudapi.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

Parameter descriptions

Parameter	Type	Required	Description
`url`	`String`	Yes	The endpoint. This is fixed at `wss://cn-beijing.maas.qwencloudapi.com/api-ws/v1/inference`.
`apikey`	`String`	Yes	The API key. Use a more secure temporary API key with a short validity period to reduce the risk of leaking a long-term key.
`service_mode`	`String`	Yes	The operating mode. For non-real-time speech recognition, this is fixed at `"1"`.
`device_id`	`String`	Yes	A unique string that identifies the end user. You can set this to an in-app user ID or a unique device identifier generated by the client. This ID is mainly used for log tracking and troubleshooting.
`debug_path`	`String`	No	The storage path for log files. This parameter is effective only if you set `save_log` to true when you call the initialize interface. In this case, you must specify a log file path. Otherwise, an error occurs. A maximum of two log files are kept locally.
`max_log_file_size`	`int`	No	Sets the maximum size of a log file in bytes. This parameter is effective only if you set `save_log` to true when you call the initialize interface. Default value: 104857600 (100 × 1024 × 1024 bytes, or 100 MiB).
`log_track_level`	`int`	No	Controls the filtering level of log content sent externally through the log callback (`onFileTransLogTrackCallback`). Default value: 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 (disables this feature) Note: `log_track_level` and `level` (set through the initialize interface) together determine which logs are sent to the callback. A log's level value must be greater than or equal to both the `log_track_level` and `level` values to trigger the callback. For example, if you set `log_track_level` to 2 (INFO) and `level` to 3 (WARNING), only logs at the WARNING level or higher (value >= 3) trigger the callback.

Speech recognition effect parameters

Use the setParams interface to configure the nls_config parameter. You can also use the startFileTranscriber interface to configure all speech recognition effect parameters.

Example: The following JSON string is an example that does not list all available parameters. Add parameters as needed.

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}

Parameter descriptions

Parameter	Type	Required	Description
`file_urls`	`array[string]`	Yes	A list of URLs for the audio or video files to transcribe. The HTTP and HTTPS protocols are supported. A single request supports only 1 URL. If audio files are stored in Alibaba Cloud OSS, the SDK does not support temporary URLs with the oss:// prefix. Audio formats: `aac`, `amr`, `avi`, `flac`, `flv`, `m4a`, `mkv`, `mov`, `mp3`, `mp4`, `mpeg`, `ogg`, `opus`, `wav`, `webm`, `wma`, `wmv` Tip: Because of the many audio and video formats and their variations, it is not technically possible to test all of them. The API cannot guarantee that all formats are recognized correctly. Test your files to verify that you get normal speech recognition results. Audio sampling rate Varies by model: paraformer-v2 supports any sample rate. paraformer-8k-v2 supports only the 8 kHz sample rate. Audio file size and duration: The audio file cannot exceed 2 GB. The duration must be within 12 hours. If you want to process a file that exceeds these limits, you can pre-process the file to reduce its size. For best practices on file pre-processing, see Pre-process video files to improve transcription efficiency (for audio file recognition scenarios).
`async_request`	`boolean`	No	Specifies whether the speech recognition is an asynchronous request. Default value: `false`. Valid values: true: asynchronous request false: synchronous request
`apikey`	`string`	No	If the `apikey` in the Connection and control parameters is a temporary API key, you can update it here to prevent it from expiring.
`nls_config`	`object`	Yes	The core configuration object for speech recognition. It includes key parameters such as model selection and recognition effect control.
`nls_config.model`	`string`	Yes	The speech recognition model.
`nls_config.language_hints`	`array[string]`	No	Specifies the language codes of the speech to be recognized. This parameter applies only to the paraformer-v2 model. Default value: `["zh", "en"]`. Supported language codes: zh: Chinese en: English ja: Japanese yue: Cantonese ko: Korean de: German fr: French ru: Russian
`nls_config.disfluency_removal_enabled`	`boolean`	No	Specifies whether to filter disfluent words, such as "um" and "ah". Default value: false. Valid values: true: filter false: do not filter
`nls_config.timestamp_alignment_enabled`	`boolean`	No	Specifies whether to enable the timestamp alignment feature. Default value: false. Valid values: true: enable false: disable
`nls_config.special_word_filter`	`object`	No	Specifies the sensitive words to process during speech recognition and supports different processing methods for different sensitive words. If this parameter is not passed, the system enables the built-in sensitive word filtering logic. Words in the recognition result that match the QwenCloud sensitive word list are replaced with an equal number of asterisks (``). If you pass this parameter, you can implement the following sensitive word processing policies: Replace with ``: Replaces matching sensitive words with an equal number of asterisks (``). Direct filtering: Removes matching sensitive words from the recognition result completely. The value of this parameter should be a JSON object with the following structure: See Example 1 below JSON field descriptions: `filter_with_signed` Type: object. Required: No. Description: Configures the list of sensitive words to be replaced with ``. Matching words in the recognition result are replaced with an equal number of asterisks (``). Example: Using the JSON above, the speech recognition result for "Help me test this piece of code" will be "Help me *** this piece of code". Internal fields: `word_list`: A string array that lists the sensitive words to be replaced. `filter_with_empty` Type: object. Required: No. Description: Configures the list of sensitive words to be removed (filtered) from the recognition result. Matching words in the recognition result are completely deleted. Example: Using the JSON above, the speech recognition result for "Is the game about to start?" will be "Is the game about to?". Internal fields: `word_list`: A string array that lists the sensitive words to be completely removed (filtered). `system_reserved_filter` Type: Boolean value. Required: No. Default value: true. Description: Specifies whether to enable the system's preset sensitive word rules. If set to `true`, the system's built-in sensitive word filtering logic is also enabled. Words in the recognition result that match the QwenCloud sensitive word list are replaced with an equal number of asterisks (`*`).
`nls_config.channel_id`	`array[integer]`	No	Specifies the audio track indexes to recognize in a multi-track audio file. Indexes start from 0. For example, [0] means recognizing the first track, and [0, 1] means recognizing both the first and second tracks simultaneously. If this parameter is omitted, only the first track is processed by default. Tip: 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_enabled`	`boolean`	No	Automatic speaker diarization. Disabled by default. Only applicable to mono audio. Multi-channel audio does not support speaker diarization. When this feature is enabled, the recognition results will include a `speaker_id` field to distinguish different speakers. Note: If speaker diarization is enabled, it is recommended that the audio duration does not exceed 2 hours, otherwise recognition may fail or time out. For an example of `speaker_id`, see Recognition result description.
`nls_config.speaker_count`	`integer`	No	A reference value for the number of speakers. To use this feature, set `diarization_enabled` to `true`. By default, the number of speakers is automatically determined. If you configure this parameter, it only helps the algorithm try to output the specified number of speakers. It does not guarantee that the exact number will be output. Value range: `[2, 100]`. This feature is used to distinguish multiple speakers, so you must set it to at least 2.
`nls_config.vocabulary_id`	`string`	No	The ID of the hotword vocabulary, used to improve the recognition accuracy of specific words. This parameter applies to v2 and later models. For information on how to use hotwords, see Customize hotwords.

Example 1 (Description):

{
  "filter_with_signed": {
    "word_list": ["test"]
  },
  "filter_with_empty": {
    "word_list": ["start", "happen"]
  },
  "system_reserved_filter": true
}

Key interfaces

NativeNui

initialize

Initializes the speech recognition SDK instance. The SDK uses the singleton pattern. Do not initialize it again before you call release. This method is blocking and must be called from a non-UI thread.

Method signature

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

Parameter descriptions

Parameter	Type	Description
`callback`	`INativeFileTransCallback`	The implementation of the event and data callback interface.
`parameters`	`String`	A JSON string that contains authentication, connection, and debugging parameters. See Connection and control parameters.
`level`	`Constants.LogLevel`	Controls the logging level of the SDK itself.
`save_log`	`boolean`	Specifies whether to save binary logs. If `true`, you must specify a path using `debug_path` in the Connection and control parameters. You can also set the file size using `max_log_file_size`.

Return value description

setParams

You can use this method to set or update the nls_config parameter independently. You do not need to call this method if all parameters are provided at once in startFileTranscriber.

Method signature

public synchronized int setParams(String params);

Parameter descriptions

Parameter	Type	Description
`params`	`String`	The `nls_config` parameter from Speech recognition effect parameters. Parameters other than `nls_config` cannot be set using this method. Example: See Example 1 below

Example 1 (Description):

{
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}

Return value description

startFileTranscriber

Starts recognition.

Method signature

public synchronized int startFileTranscriber(String params, byte[] task_id)

Parameter descriptions

Parameter	Type	Description
`params`	`String`	Speech recognition effect parameters. Example: See Example 1 below
`task_id`	`byte[]`	The task ID. The SDK internally generates a random string. You can get the task_id after this method is called successfully.

Example 1 (Description):

{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"paraformer-v2",
        "disfluency_removal_enabled":false,
        "timestamp_alignment_enabled": false
    }
}

Return value description

queryFileTranscriber

You can use this method to query the current status and result of an asynchronous task. After a successful call, the result is returned in the onFileTransEventCallback callback through the EVENT_FILE_TRANS_QUERY_RESULT event.

Method signature

public synchronized int queryFileTranscriber(String task_id)

Parameter descriptions

Parameter	Type	Description
`task_id`	`byte[]`	The ID of the task to query.

Return value description

cancelFileTranscriber

Immediately cancels the current task.

Method signature

public synchronized int cancelFileTranscriber(String task_id)

Parameter descriptions

Parameter	Type	Description
`task_id`	`byte[]`	The ID of the task to cancel.

Return value description

release

Releases all internal resources of the SDK. After this method is called, the SDK instance becomes unavailable. To use the SDK again, you must call initialize.

Method signature

public synchronized int release();

Return value description

GetVersion

Retrieves the current SDK version information.

Method signature

public synchronized String GetVersion();

Return value description The current SDK version information.

INativeFileTransCallback: Listener callback

onFileTransEventCallback: Listen for events and speech recognition results

Method signature

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

Parameter descriptions

Parameter	Type	Description
`event`	`NuiEvent`	The callback event.
`resultCode`	`int`	Valid only when the `EVENT_ASR_ERROR` event occurs.
`asrResult`	`AsrResult`	The speech recognition result.
`taskId`	`String`	The task ID.
`arg2`	`int`	A reserved parameter.

onFileTransLogTrackCallback: Listen for trace logs

You can use this callback to receive detailed internal logs from the SDK for troubleshooting and debugging.

default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

`NuiEvent`: Event types

Event	Description
EVENT_FILE_TRANS_CONNECTED	Successfully connected to the service.
EVENT_FILE_TRANS_UPLOADED	Successfully uploaded the audio file for recognition.
EVENT_FILE_TRANS_QUERY_RESULT	The result of a task query.
EVENT_FILE_TRANS_RESULT	The final recognition result.
EVENT_ASR_ERROR	An error occurred during speech recognition.

​Getting started

​Invocation steps

​Request parameters

​Connection and control parameters

​Speech recognition effect parameters

​Key interfaces

​NativeNui

​initialize

​setParams

​startFileTranscriber

​queryFileTranscriber

​cancelFileTranscriber

​release

​GetVersion

​INativeFileTransCallback: Listener callback

​onFileTransEventCallback: Listen for events and speech recognition results

​onFileTransLogTrackCallback: Listen for trace logs

​NuiEvent: Event types

Getting started

Invocation steps

Request parameters

Connection and control parameters

Speech recognition effect parameters

Key interfaces

NativeNui

initialize

setParams

startFileTranscriber

queryFileTranscriber

cancelFileTranscriber

release

GetVersion

INativeFileTransCallback: Listener callback

onFileTransEventCallback: Listen for events and speech recognition results

onFileTransLogTrackCallback: Listen for trace logs

`NuiEvent`: Event types