iOS SDK

Updated at:

Use the Short File Transcription SDK for iOS to upload local audio files and receive transcription results through event callbacks. This page describes SDK integration, a code example, and key methods.

Prerequisites and limitations

  • Activate the commercial edition of Short File Transcription. This service does not offer a free trial. For service limits and billing, see the Short File Transcription API reference.

  • Obtain a project Appkey and a valid NLS token. See Manage projects and Obtain a token.

  • Prepare a local audio file. Supported formats are WAV, MP3, AAC, MP4, and OPUS. The file must not exceed 100 MB or two hours in duration. Select a recognition model in the project that matches the audio language.

Important

Keep the AccessKey ID and AccessKey secret on your server. Do not embed them in app code or store them on mobile devices. Obtain an NLS token on the server, deliver it to the app, and update it before it expires. Initialization parameters contain credentials and must not be logged in full.

Download and install

  1. Download an iOS SDK package that supports Short File Transcription from Select and download mobile SDK. Check the compatibility and compliance requirements on that page.

  2. Extract the SDK package and add nuisdk.xcframework to your app project. In the app target's section, set the embedding option to Embed & Sign. The XCFramework contains separate device and simulator variants. Xcode selects the variant for the target platform.

  3. Import the header in your source file.

#import <nuisdk/NeoNui.h>

The sample project in the SDK package includes FileTranscriberViewController.m and utilities for audio playback, recording, and file operations. Use these utilities as needed. Before running the sample project, configure the project Appkey and the NLS token delivered by your server.

iOS SDK releases after V2.5.14 expose Objective-C methods. Starting with V2.6.2, cloud-only features do not require resource files or the workspace parameter.

Procedure

  1. Create a NeoNui instance and assign a delegate that implements NeoNuiSdkDelegate.

  2. On a non-UI thread, call nui_initialize with the Appkey, NLS token, device identifier, and service URL.

  3. Build a JSON string with the local file path, audio format, and other task settings. Call nui_file_trans_start to start transcription.

  4. Obtain the final result from EVENT_FILE_TRANS_RESULT, and handle errors in EVENT_ASR_ERROR.

  5. Call nui_release when the task finishes or the SDK is no longer needed. To stop a task, pass the task ID returned when transcription starts to nui_file_trans_cancel.

Important

Do not call SDK methods directly from SDK event callbacks because this can cause deadlocks. Submit cancellation, release, and other SDK operations to a work queue outside the callback. Update the UI on the main thread.

Code example

The following Objective-C example uses SDK V2.7.4-01B to transcribe example.wav from the app bundle. Add a WAV file to the app target's resources. Replace the Appkey and token placeholders with the project Appkey and a valid NLS token delivered by your server. To use another audio file, update both file_path and nls_config.format.

The example runs SDK operations on a dedicated work queue, releases resources when the task finishes, and cancels an unfinished task when the page closes.

#import <UIKit/UIKit.h>
#import <nuisdk/NeoNui.h>

@interface FileTranscriberViewController : UIViewController <NeoNuiSdkDelegate> {
    char _taskId[33];
}
@property(nonatomic, strong) NeoNui *nui;
@property(nonatomic, strong) dispatch_queue_t sdkQueue;
@end

@implementation FileTranscriberViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.sdkQueue = dispatch_queue_create("com.example.file-transcriber", DISPATCH_QUEUE_SERIAL);
    self.nui = [[NeoNui alloc] init];
    self.nui.delegate = self;
    [self startRecognition];
}

- (void)startRecognition {
    NSString *filePath = [[NSBundle mainBundle] pathForResource:@"example" ofType:@"wav"];
    NSString *appkey = @"<APPKEY>";
    NSString *token = @"<NLS_TOKEN>";
    if (filePath.length == 0) {
        NSLog(@"Audio file not found");
        return;
    }

    dispatch_async(self.sdkQueue, ^{
        NSDictionary *initParams = @{
            @"app_key": appkey,
            @"token": token,
            @"device_id": [[NSUUID UUID] UUIDString],
            @"url": @"https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer"
        };
        NSData *initData = [NSJSONSerialization dataWithJSONObject:initParams options:0 error:nil];
        NSString *initJSON = [[NSString alloc] initWithData:initData encoding:NSUTF8StringEncoding];
        int ret = [self.nui nui_initialize:[initJSON UTF8String]
                                 logLevel:NUI_LOG_LEVEL_NONE saveLog:NO];
        if (ret != 0) {
            NSLog(@"Initialize failed: %d", ret);
            [self releaseSDK];
            return;
        }

        NSDictionary *taskParams = @{
            @"file_path": filePath,
            @"nls_config": @{@"format": @"wav", @"sample_rate": @16000}
        };
        NSData *taskData = [NSJSONSerialization dataWithJSONObject:taskParams options:0 error:nil];
        NSString *taskJSON = [[NSString alloc] initWithData:taskData encoding:NSUTF8StringEncoding];
        ret = [self.nui nui_file_trans_start:[taskJSON UTF8String] taskId:self->_taskId];
        if (ret != 0) {
            NSLog(@"Start failed: %d", ret);
            [self releaseSDK];
        }
    });
}

- (void)onFileTransEventCallback:(NuiCallbackEvent)event
                     asrResult:(const char *)asrResult
                        taskId:(const char *)taskId
                      ifFinish:(BOOL)finish
                       retCode:(int)code {
    if (event != EVENT_FILE_TRANS_RESULT && event != EVENT_ASR_ERROR) {
        return;
    }
    NSString *result = asrResult ? [NSString stringWithUTF8String:asrResult] : @"";
    dispatch_async(self.sdkQueue, ^{
        if (self.nui == nil) {
            return;
        }
        if (event == EVENT_FILE_TRANS_RESULT) {
            NSLog(@"Recognition result: %@", result);
        } else {
            NSLog(@"Recognition failed: %d; %@", code, result);
        }
        [self releaseSDK];
    });
}

- (void)cancelRecognition {
    dispatch_async(self.sdkQueue, ^{
        if (self.nui != nil && self->_taskId[0] != '\0') {
            int ret = [self.nui nui_file_trans_cancel:self->_taskId];
            if (ret != 0) {
                NSLog(@"Cancel failed: %d", ret);
            }
        }
        [self releaseSDK];
    });
}

- (void)releaseSDK {
    [self.nui nui_release];
    self.nui.delegate = nil;
    self.nui = nil;
}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [self cancelRecognition];
}
@end

For complete initialization settings, task parameters, and result fields, see Mobile SDK guide.

Key SDK methods

Use [NeoNui get_instance] to obtain the shared instance, or use [[NeoNui alloc] init] to create a separate instance. Release existing SDK resources before initializing the same instance again.

Initialization and parameter configuration

nui_initialize initializes the SDK. nui_set_params configures parameters using a JSON string.

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

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

Parameter

Type

Description

parameters

const char *

A JSON string with initialization settings.

level

NuiSdkLogLevel

The log level. Smaller enumeration values produce more detailed logs.

saveLog

BOOL

Whether to save logs to files. When set to YES, logs are saved to the directory specified by debug_path in the initialization parameters.

params

const char *

A JSON string with parameter settings for nui_set_params.

For initialization settings and configurable parameters, see Mobile SDK guide. To update the token, pass a JSON string with the token field to nui_set_params.

Start and cancel transcription

nui_file_trans_start starts transcription and writes the generated task ID to the buffer pointed to by taskId. nui_file_trans_cancel cancels the specified task.

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

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

Parameter

Type

Description

params

const char *

A JSON string with transcription settings, including file_path and nls_config.

taskId (start)

char *

An output buffer that receives the task ID generated by the SDK. The example uses a 33-byte buffer.

taskId (cancel)

const char *

The ID of the task to cancel.

Release resources

Call nui_release to release SDK resources.

- (NuiResultCode)nui_release;

The methods above return 0 for a successful method call. A value other than 0 indicates an error. Transcription results are returned through event callbacks.

For error codes and solutions, see Error codes.

Event callback

Handle transcription events in the delegate object that implements NeoNuiSdkDelegate.

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

Parameter

Type

Description

event

NuiCallbackEvent

The event type.

asrResult

const char *

The transcription result or error information.

taskId

const char *

The unique ID of the current task.

finish

BOOL

Whether the current task has finished.

code

int

The error code. This parameter is valid for EVENT_ASR_ERROR.

The main events are listed below.

Event

Description

EVENT_FILE_TRANS_CONNECTED

Connected to the transcription service.

EVENT_FILE_TRANS_UPLOADED

The file has been uploaded.

EVENT_FILE_TRANS_RESULT

Returns the final transcription result.

EVENT_ASR_ERROR

An error occurred. Handle it based on the error code.

FAQ

Does iOS support background processing?

The SDK does not restrict foreground or background calls. iOS manages the time available for background execution. File transcription uploads local files over the network and does not require microphone access or background recording settings.

To continue a network task after the app enters the background, call beginBackgroundTaskWithExpirationHandler: before starting a long-running task to request a limited extension of execution time. End the background task when the work finishes or the extension expires. For details, see Apple's Extending your app's background execution time.

How do I resolve no suitable image found on a device?

Check that the linked and embedded libraries support the device platform, and check framework embedding and code signing settings. The current SDK uses an XCFramework with separate device and simulator variants. After correcting the configuration, you can clean the project, remove the old app from the device, and reinstall it.

For signing errors, correct the certificate and provisioning profile settings for the app, then sign and package it again.

How do I resolve a NeoNui.h import error?

Import the header using #import <nuisdk/NeoNui.h>. Check that the SDK is added to the app target and that the framework search paths can locate nuisdk.framework for the target platform. Configure dynamic library embedding and signing as described in the installation steps.

How do I resolve a framework built for both iOS and iOS Simulator?

Integrate nuisdk.xcframework from the current SDK package so Xcode can select the device or simulator variant. For an older framework package, choose a library that matches the target platform. For details about platform variants, see Apple's Creating a multiplatform binary framework bundle.

How do I resolve unsupported simulator architectures when submitting to the App Store?

Use the XCFramework's device variant when archiving for a device. For an older combined framework that includes simulator architectures such as x86_64 and i386, use lipo -info to inspect the architectures of the binary inside the framework. Use a library without simulator architectures for the device archive.

Is Legacy Build System required for integration?

Use the current SDK's XCFramework and configure integration for the project's target platform. If an older project has a library platform mismatch, update or replace the SDK library with one for that platform. The choice of build system does not change a library's target platform.