Paraformer real-time speech recognition Android SDK

​

Getting started

1. Obtain an API key: Get an API key. For security purposes, configure the API key as an environment variable.
   To grant temporary access permissions to third-party applications or users, or to strictly control risky operations such as accessing or deleting sensitive data, use a temporary API key. A temporary API key is valid for 60 seconds by default and must be reacquired after it expires.
2. Download the SDK and run the sample code:
   • Download the latest SDK package.
   • Unzip the package. Obtain the AAR-format SDK from the app/libs folder and add it to your project dependencies.
     For Android C++ integration, use the android_libs and android_include folders in the ZIP package to obtain the dynamic libraries and header files.
     
     
   • Open the project in Android Studio. The sample code is in DashParaformerSpeechTranscriberActivity.java. Replace the API key to test the feature.

​

Invocation steps

1. Initialize the SDK.
2. Set the required parameters. Use the parameters parameter of the initialize method to set connection and control parameters. Use the setParams method to set speech recognition effect parameters.
3. Call startDialog to start the recognition process.
4. In the onNuiAudioStateChanged callback, start the recording device based on the audio state.
5. In the onNuiNeedAudioData callback, continuously provide recording data.
6. In the onNuiEventCallback callback, listen for events and retrieve the speech recognition results.
7. Call stopDialog to stop recognition. Confirm that recognition has ended by listening for the EVENT_TRANSCRIBER_COMPLETE event.
8. When the recognition feature is no longer needed, call the release method to release SDK resources.

​

Request parameters

​

Connection and control parameters

• Parameter example: The following code provides a sample JSON string. Not all parameters are listed. You can add parameters as needed during encoding:

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.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 service endpoint. This is fixed at wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Replace {WorkspaceId} with your actual workspace ID.
  apikey	String	Yes	The API key. To reduce the risk of a long-term key being exposed, use a more secure temporary API key with a short validity period.
  service_mode	String	Yes	The operating mode. For 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 takes effect only when save_log is set to true in the initialize call. You must set a log file path, otherwise an error will occur. A maximum of two log files are kept locally.
  save_wav	String	No	Specifies whether to save audio files for debugging. The audio files are saved to the path specified by debug_path. Default value: "false". Valid values: "true": Yes "false": No This parameter takes effect only when save_log is set to true in the initialize call. The debug_path parameter must also be set.
  max_log_file_size	int	No	The maximum size of a log file in bytes. This parameter takes effect only when save_log is set to true in the initialize call. Default value: 104857600 (100 × 1024 × 1024 bytes, which is 100 MiB).
  log_track_level	int	No	Controls the filter level of log content sent externally through the log callback (onNuiLogTrackCallback). 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 the final logs that are sent to the callback. A log is sent to the callback only if its level value is greater than or equal to both the log_track_level and level values. For example, if log_track_level is set to 2 (INFO) and level is set to 3 (WARNING), only logs at the WARNING level and higher (value >= 3) are sent to the callback.

​

Speech recognition effect parameters

• Parameter example: The following code provides a sample JSON string. Not all parameters are listed. You can add parameters as needed during encoding:

{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

• Parameter descriptions

  Top-level parameter	Type	Required	Description
  service_type	int	Yes	The Voice Service type. For real-time speech recognition, this is fixed at 4.
  nls_config	object	Yes	The core configuration object for speech recognition. It contains key parameters such as model selection and recognition effect controls.
  nls_config.model	string	Yes	The speech recognition model.
  nls_config.sr_format	string	Yes	The format of the audio to be recognized.Supported audio formats: pcm, wav, opus. opus: Must be PCM encoded. The SDK internally encodes it into the OPUS format. wav/pcm: Must be PCM encoded.
  nls_config.sample_rate	int	Yes	The sample rate of the audio to be recognized, in Hz.This varies by model: paraformer-realtime-v2 supports any sample rate. paraformer-realtime-8k-v2 only supports an 8000 Hz sample rate.
  nls_config.disfluency_removal_enabled	boolean	No	Specifies whether to filter out filler words, such as "um" and "ah".Default value: false.
  nls_config.language_hints	array[string]	No	Sets the language codes for recognition. If you cannot determine the language in advance, you can leave this unset. The model will automatically detect the language.Supported language codes: zh: Chinese en: English ja: Japanese yue: Cantonese ko: Korean de: German fr: French ru: Russian This parameter only takes effect for multilingual models.
  nls_config.semantic_punctuation_enabled	boolean	No	Sets the sentence segmentation mode.Default value: false.Valid values: true: Enables semantic segmentation and disables VAD segmentation. false: Enables VAD segmentation and disables semantic segmentation. Semantic segmentation provides higher accuracy and is suitable for meeting transcription scenarios. Voice Activity Detection (VAD) segmentation has lower latency and is suitable for real-time interactive scenarios.This parameter takes effect only for v2 and later models.
  nls_config.max_sentence_silence	int	No	The silence duration threshold for VAD segmentation, in ms.Default value: 800.Value range: [200, 6000].When the silence duration after a speech segment exceeds this threshold, the system determines that the sentence has ended.This parameter takes effect only when the semantic_punctuation_enabled parameter is false and for v2 and later models.
  nls_config.multi_threshold_mode_enabled	boolean	No	Specifies whether to enable the long-segment prevention mode. Enabling this prevents VAD from creating excessively long segments.Default value: false (disabled).Valid values: true: Enabled false: Disabled This parameter takes effect only when the semantic_punctuation_enabled parameter is false and for v2 and later models.
  nls_config.punctuation_prediction_enabled	boolean	No	Specifies whether to automatically add punctuation to the recognition results.Default value: true (yes).Valid values: true: Yes false: No This parameter takes effect only for v2 and later models.
  nls_config.heartbeat	boolean	No	Specifies whether to maintain a persistent connection with the server.Default value: false.Valid values: true: The connection to the server can be maintained without interruption by continuously sending silent audio. false: Even when silent audio is continuously sent, the connection times out and closes after a period of time. This timeout is a default server-side behavior and cannot be configured by the client. This parameter takes effect only for v2 and later models.
  nls_config.inverse_text_normalization_enabled	boolean	No	Specifies whether to enable Inverse Text Normalization (ITN). When enabled, Chinese numerals are converted to Arabic numerals.Default value: true (enabled).Valid values: true: Enabled false: Disabled This parameter takes effect only for v2 and later models.
  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 about how to use hotwords, see Customize hotwords.

​

Key interfaces

​

NativeNui

​

initialize

• Method signature

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

• Parameter descriptions

  Parameter	Type	Description
  callback	INativeNuiCallback	The implementation of the event and data callback interface.
  parameters	String	A JSON string that contains authentication, connection, and debugging parameters. For more information, see Connection and control parameters.
  level	Constants.LogLevel	Controls the print level of the SDK's own logs.
  save_log	boolean	Specifies whether to save binary logs. If set to true, you must specify a path with debug_path in the connection and control parameters. You can also set the file size with max_log_file_size.

• Return value

​

setParams

• Method signature

public synchronized int setParams(String params)

• Parameter descriptions

  Parameter	Type	Description
  params	String	Speech recognition effect parameters.

• Return value

​

startDialog

• Method signature

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

• Parameter descriptions

  Parameter	Type	Description
  vad_mode	VadMode	The VAD mode. This is fixed at VadMode.TYPE_P2T.
  dialog_params	String	When the temporary API key corresponding to the apikey parameter in the connection and control parameters expires, you can update it here.The content is in JSON format: Copy { "apikey": "st-****" }

• Return value

​

stopDialog

• Method signature

public synchronized int stopDialog();

• Return value

​

cancelDialog

• Method signature

public synchronized int cancelDialog();

• Return value

​

release

• Method signature

public synchronized int release();

• Return value

​

GetVersion

• Method signature

public synchronized String GetVersion();

• Return value The current SDK version information.

​

INativeNuiCallback: Listener callbacks

​

onNuiEventCallback: Listen for events and speech recognition results

• Method signature

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

• 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.
  kwsResult	KwsResult	The voice wake-up feature. You do not need to follow this parameter.
  arg2	int	Reserved parameter.

​

onNuiAudioStateChanged: Listen for audio state

• Method signature

void onNuiAudioStateChanged(AudioState state);

• AudioState descriptions

  State	Description
  STATE_OPEN	The interaction starts. You can open the recording device to record audio.
  STATE_PAUSE	The interaction stops. You can stop recording.
  STATE_CLOSE	The SDK instance is released. You can completely shut down the recording device.

​

onNuiNeedAudioData: Fill in audio data for recognition

• Method signature

int onNuiNeedAudioData(byte[] buffer, int len);

• Parameter descriptions

  Parameter	Type	Description
  buffer	byte[]	The audio data to fill.
  len	int	The number of bytes of the audio data to fill.

• Return value The actual number of bytes filled.

​

onNuiLogTrackCallback: Listen for tracking logs

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

​

NuiEvent: Event types