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

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

Quick start

Get an API Key:Obtain an API key
Download the SDK and run the sample code:
- Download the latest SDK bundle.
- Unzip the ZIP package and add the included nuisdk.framework to your project.
- Under Build Phases → Link Binary With Libraries, add nuisdk.xcframework.
- Under General → Frameworks, Libraries, and Embedded Content, set nuisdk.xcframework to Embed & Sign.
- Open the sample project in Xcode. The sample code is located in DashFunAsrFileTranscriberViewController.m. Replace the API Key to try out the feature.

Call steps

Synchronous mode
Asynchronous mode

Initialize the SDK.
Configure the relevant parameters for your use case.
Set async_request to false and call nui_file_trans_start to submit a non-real-time speech recognition request and wait for the result.
In the onFileTransEventCallback callback, listen for the EVENT_FILE_TRANS_RESULT event to get the final recognition result.
Call nui_release to release the SDK resources.

Initialize the SDK.
Configure the relevant parameters for your use case.
Set async_request to true and call nui_file_trans_start to submit a non-real-time speech recognition request.
Call nui_file_trans_query to actively query the recognition progress or result.
In the onFileTransEventCallback callback, listen for the EVENT_FILE_TRANS_QUERY_RESULT event to get the current query result.
In the onFileTransEventCallback callback, listen for the EVENT_FILE_TRANS_RESULT event to get the final recognition result.
Call nui_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 nui_initialize interface. Example parameters The following is a sample JSON string. Not all parameters are listed. Add the ones 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 descriptions

Parameter	Type	Required	Description
`url`	`String`	Yes	Service 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.
`apikey`	`String`	Yes	The API Key.
`service_mode`	`String`	Yes	The run mode. Fixed to `"1"` for non-real-time speech recognition.
`device_id`	`String`	Yes	A 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 used mainly for log tracing and troubleshooting.
`debug_path`	`String`	No	The storage path for the log file.This parameter takes effect only when `save_log` is set to `YES` when you call the `nui_initialize` interface. In that case, you must set the log file path; otherwise, an error is returned.A maximum of two log files are kept locally.
`max_log_file_size`	`int`	No	The maximum size of the log file, in bytes.This parameter takes effect only when `save_log` is set to `YES` when you call the `nui_initialize` interface.Default value: 104857600 (100 * 1024 * 1024 bytes, that is, 100 MiB).
`log_track_level`	`int`	No	Controls the filter level of the log content sent out 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 `nui_initialize` interface) together determine which logs are ultimately sent to the callback. A log's level value must be greater than or equal to both `log_track_level` and `level` before it is sent to the callback. For example, if `log_track_level` is set to 2 (INFO) and `level` is set to 3 (WARNING), only logs at WARNING or higher (value >= 3) are sent to the callback.

Speech recognition effect parameters

Configure all speech recognition parameters through the nui_file_trans_start interface. Example parameters The following is a sample JSON string. Not all parameters are listed. Add the ones 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 descriptions

Parameter	Type	Required	Description
`file_urls`	`array[string]`	Yes	A 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_request`	`boolean`	No	Whether the speech recognition request is asynchronous.Default value: `false`.Valid values: true: asynchronous request false: synchronous request
`apikey`	`string`	No	If the `apikey` in 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 speech recognition configuration object. It contains key parameters such as model selection and recognition effect controls.
`nls_config.model`	`string`	Yes	The model name.
`nls_config.special_word_filter`	`object`	No	The 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_id`	`array[integer]`	No	The 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_enabled`	`boolean`	No	Whether 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 value: false.For an example of `speaker_id`, see Recognition result description.
`nls_config.speaker_count`	`integer`	No	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_id`	`string`	No	The 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_vocabulary`	`object`	No	Instant 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_hints`	`array[string]`	No	The 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. Click to view the supported language codes 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

NeoNui

nui_initialize

Initializes the speech recognition SDK instance. The SDK is a singleton. Do not initialize it again before you call nui_release. Method signature

-(NuiResultCode) nui_initialize:(const char *)parameters
                       logLevel:(NuiSdkLogLevel)level
                        saveLog:(BOOL)save_log;

Parameter descriptions

Parameter	Type	Description
`parameters`	`char*`	A JSON string that contains the authentication, connection, and debugging parameters. See Connection and control parameters.
`level`	`NuiSdkLogLevel`	Controls the print level of the SDK's own logs.
`save_log`	`BOOL`	Whether to save logs locally. If set to `YES`, you must specify a path through `debug_path` in Connection and control parameters, and you can set the file size through `max_log_file_size`.

nui_set_params

Use this interface to set or update the nls_config parameter independently. If you provide all parameters at once in nui_file_trans_start, you don't need to call this method. Method signature

-(NuiResultCode) nui_set_params:(const char *)params;

Parameter descriptions

Parameter	Type	Description
`params`	`char*`	The `nls_config` parameter in Speech recognition effect parameters. Parameters other than `nls_config` cannot be set through this method.Example: `{ "nls_config": { "model":"fun-asr", "diarization_enabled": false } }`

nui_file_trans_start

Starts recognition. Method signature

-(NuiResultCode) nui_file_trans_start:(const char *)params
                               taskId:(char *)task_id;

Parameter descriptions

Parameter	Type	Description
`params`	`char*`	Speech recognition effect parameters.Example: `{ "file_urls": [ "{YOUR_AUDIO_URL}" ], "async_request": false, "nls_config": { "model":"fun-asr", "diarization_enabled": false } }`
`task_id`	`char*`	The task ID. The SDK generates a random string internally and returns the task_id when this interface is called successfully.

nui_file_trans_query

Use this interface to actively query the current status and result of an asynchronous task. After a successful call, 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

-(NuiResultCode) nui_file_trans_query:(const char *)task_id;

Parameter descriptions

Parameter	Type	Description
`task_id`	`char*`	The ID of the task to query, obtained from the `EVENT_FILE_TRANS_UPLOADED` event.

nui_file_trans_cancel

Cancels the current task immediately. Method signature

-(NuiResultCode) nui_file_trans_cancel:(const char *)task_id;

Parameter descriptions

Parameter	Type	Description
`task_id`	`char*`	The ID of the task to cancel, obtained from the `EVENT_FILE_TRANS_UPLOADED` event.

nui_release

Releases all internal SDK resources and forcibly terminates all ongoing tasks. After you call this method, the SDK instance becomes unavailable. To use it again, you must call nui_initialize again to initialize it. Method signature

-(NuiResultCode) nui_release;

nui_get_version

Gets the current SDK version information. Method signature

-(const char*) nui_get_version;

Return value The current SDK version information.

NeoNuiSdkDelegate: monitor callbacks

onFileTransEventCallback: monitor events and speech recognition results

Method signature

-(void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                       asrResult:(const char *)asr_result
                          taskId:(const char *)task_id
                        ifFinish:(BOOL)finish
                         retCode:(int)code;

Parameter descriptions

Parameter	Type	Description
`nuiEvent`	`NuiCallbackEvent`	The callback event.
`asr_result`	`char*`	The speech recognition result.
`task_id`	`char*`	The task ID.
`finish`	`BOOL`	Indicates whether this round of recognition has finished.
`code`	`int`	Valid only when the `EVENT_ASR_ERROR` event occurs.

onFileTransLogTrackCallback: monitor trace logs

Use this callback to receive detailed internal SDK logs for troubleshooting and debugging.

-(void)onFileTransLogTrackCallback:(NuiSdkLogLevel)level
                        logMessage:(const char *)log;

NuiCallbackEvent: event types

Event	Description
`EVENT_FILE_TRANS_CONNECTED`	Connected to the service successfully.
`EVENT_FILE_TRANS_UPLOADED`	The audio file to recognize was uploaded successfully. You can now obtain the `task_id` of the current task.
`EVENT_FILE_TRANS_QUERY_RESULT`	The query task result.
`EVENT_FILE_TRANS_RESULT`	The final recognition result.
`EVENT_ASR_ERROR`	An error occurred during speech recognition.

​Quick start

​Call steps

​Request parameters

​Connection and control parameters

​Speech recognition effect parameters

​Key interfaces

​NeoNui

​nui_initialize

​nui_set_params

​nui_file_trans_start

​nui_file_trans_query

​nui_file_trans_cancel

​nui_release

​nui_get_version

​NeoNuiSdkDelegate: monitor callbacks

​onFileTransEventCallback: monitor events and speech recognition results

​onFileTransLogTrackCallback: monitor trace logs

​NuiCallbackEvent: event types

Quick start

Call steps

Request parameters

Connection and control parameters

Speech recognition effect parameters

Key interfaces

NeoNui

nui_initialize

nui_set_params

nui_file_trans_start

nui_file_trans_query

nui_file_trans_cancel

nui_release

nui_get_version

NeoNuiSdkDelegate: monitor callbacks

onFileTransEventCallback: monitor events and speech recognition results

onFileTransLogTrackCallback: monitor trace logs

NuiCallbackEvent: event types