iOS SDK

Prerequisites

• Read the API reference.

• An AppKey for your project. For instructions, see Create a project.

• An Access Token. For instructions, see Get an Access Token.

Download and install

1. Select and download the mobile SDK.

   Important

   After downloading the SDK, replace the placeholders in the sample initialization code with your Alibaba Cloud account details, AppKey, and Access Token to run the demo.

   To simplify integration, iOS interfaces in version 2.5.14 and later are pure Objective-C and no longer use mixed C++ interfaces.

2. Unzip the ZIP package. Add the nuisdk.framework file from the package to your project. In the BuildPhases tab of your project settings, add nuisdk.framework to the LinkBinaryWithLibraries section. Then, go to the Generaltab and ensure that in the Frameworks,Libraries,andEmbeddedContent section, nuisdk.framework is set to Embed&Sign.

3. Open the project in Xcode. The project includes reference code and utility classes for tasks like audio playback, recording, and file operations, which you can copy to your own project. The sample code for Short File Transcription is in the FileTranscriberViewController class.

Key SDK interfaces

• nui_initialize: Initializes the SDK.

    /**
     * Initializes the SDK. This is a singleton. Before re-initializing, you must release the existing instance. To avoid blocking the UI, do not call this method on the main thread.
     * @param parameters: The initialization parameters. For more information, see the API reference.
     * @param level: The log level. A smaller value indicates more detailed logs.
     * @param save_log: Specifies whether to save logs to a file. The logs are saved to the directory specified by the debug_path field in the parameters.
     * @return See the error codes.
     */
  -(NuiResultCode) nui_initialize:(const char *)parameters
                         logLevel:(NuiSdkLogLevel)level
                          saveLog:(BOOL)save_log;

• nui_set_params: Sets SDK parameters in JSON format.

  /**
   * Sets parameters in JSON format.
   * @param params: For more information about the parameters, see the API reference.
   * @return See the error codes.
   */
  -(NuiResultCode) nui_set_params:(const char *)params;

• nui_file_trans_start: Starts a file transcription task.

  /**
   * Starts a file transcription task.
   * @param params: The transcription parameters. For more information, see the API reference.
   * @param task_id: An output parameter that receives the task ID. The SDK generates a random string for this ID.
   * @return See the error codes.
   */
  NuiResultCode nui_file_trans_start(const char *params, char *task_id);

• nui_file_trans_cancel: Cancels a running transcription task.

  /**
   * Cancels the transcription.
   * @param task_id: The ID of the transcription task to cancel.
   * @return See the error codes.
   */                    
  NuiResultCode nui_file_trans_cancel(const char *task_id);

• nui_release: Releases the SDK.

  /**
   * Releases SDK resources.
   * @return See the error codes.
   */
  -(NuiResultCode) nui_release;

• NeoNuiSdkDelegate: Event delegate.

  onFileTransEventCallback: Handles SDK transcription events.

  /**
   * The main event callback of the SDK.
   * @param nuiEvent: The callback event. See the event list below.
   * @param asrResult: The speech recognition result.
   * @param taskId: The unique ID for the task.
   * @param ifFinish: Indicates whether the current recognition round is complete.
   * @param retCode: The error code. This parameter is valid when an EVENT_ASR_ERROR event occurs.
   */
  -(void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                         asrResult:(const char *)asr_result
                            taskId:(const char *)task_id
                          ifFinish:(BOOL)finish
                           retCode:(int)code;

  NuiCallbackEvent event list:

  Parameter	Description
  EVENT_FILE_TRANS_CONNECTED	Indicates a successful connection to the file transcription service.
  EVENT_FILE_TRANS_UPLOADED	Indicates that the file has been uploaded successfully.
  EVENT_FILE_TRANS_RESULT	Returns the final recognition result.
  EVENT_ASR_ERROR	An error occurred. Use the error code to identify the cause.

Procedure

1. Initialize the SDK.

2. Set parameters based on your business requirements.

3. Call nui_file_trans_start to start the transcription.

4. Obtain the final transcription result from the EVENT_FILE_TRANS_RESULT event.

5. When finished, call the nui_release method to free up SDK resources.

Code examples

Initialize the NUI SDK

// Note the parameter configuration. You must set account-related fields as described in genInitParams to access the service.
NSString * initParam = [self genInitParams];

[_nui nui_initialize:[initParam UTF8String] logLevel:LOG_LEVEL_VERBOSE saveLog:save_log];

The genInitParams method generates a JSON string that contains resource directory and user information. The string includes the following fields.

-(NSString*) genInitParams {
    NSString *strResourcesBundle = [[NSBundle mainBundle] pathForResource:@"Resources" ofType:@"bundle"];
    NSString *bundlePath = [[NSBundle bundleWithPath:strResourcesBundle] resourcePath];
    NSString *id_string = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
    NSString *debug_path = [_utils createDir];
    TLog(@"id: %s", [id_string UTF8String]);

    // Method to obtain a token:
    NSMutableDictionary *dictM = [NSMutableDictionary dictionary];

    // Account and project creation
    //  For information about how to obtain an ak_id, ak_secret, and AppKey, see https://help.aliyun.com/document_detail/72138.html
    [dictM setObject:@"<Your AppKey>" forKey:@"app_key"]; // Required

    // Method 1:
    //  First, for information about how to obtain an ak_id, ak_secret, and AppKey, see https://help.aliyun.com/document_detail/72138.html
    //  Then, see https://help.aliyun.com/document_detail/466615.html and use Method 1 to obtain a temporary credential.
    //  Description: Your server obtains a temporary credential with a limited validity period and sends it to the mobile client. This prevents your ak_id and ak_secret from being exposed.
    //  Method to obtain a token (run on your app server): https://help.aliyun.com/document_detail/450255.html?spm=a2c4g.72153.0.0.79176297EyBj4k
    [dictM setObject:@"<A time-limited temporary credential generated by your server>" forKey:@"token"]; // Required

    // Method 2:
    //  Obtaining a temporary credential by using STS is not supported.

    // Method 3: (Strongly not recommended. This method poses a risk of exposing your Alibaba Cloud account credentials.)
    //  Use the implementation in the NuiSdkUtils class to access the Alibaba Cloud Token service on the client to obtain a token. Do not store your ak_id and ak_secret in the local or client-side environment.
    //  Advantage: The client obtains the token without requiring an app server.
    //  Disadvantage: Your ak_id and ak_secret credentials can be easily exposed on the client side.
    //    [_utils getTicket:dictM];

    // The working directory from which the SDK reads configuration files.
    [dictM setObject:bundlePath forKey:@"workspace"]; // Required
    // The debug directory. When save_log is set to true during SDK initialization, this directory is used to save intermediate audio files.
    [dictM setObject:debug_path forKey:@"debug_path"];
    [dictM setObject:id_string forKey:@"device_id"]; // Required. We recommend that you use a unique ID to help troubleshoot issues.
    [dictM setObject:@"https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer" forKey:@"url"]; // Required

    //FullMix = 0   // Select this mode to enable local features, which requires authentication.
    //FullCloud = 1 // Select this mode for real-time speech recognition.
    //FullLocal = 2 // Select this mode to enable local features, which requires authentication.
    //AsrMix = 3    // Select this mode to enable local features, which requires authentication.
    //AsrCloud = 4  // Select this mode for real-time speech recognition.
    //AsrLocal = 5  // Select this mode to enable local features, which requires authentication.
    [dictM setObject:@"1" forKey:@"service_mode"]; // Required

    NSData *data = [NSJSONSerialization dataWithJSONObject:dictM options:NSJSONWritingPrettyPrinted error:nil];
    NSString * jsonStr = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding];
    return jsonStr;
}

Start transcription

Call the nui_file_trans_start interface to start the transcription.

char task_id[33] = {0};
[_nui nui_file_trans_start:param:[param_string UTF8String] taskId:task_id];

Handle callbacks

onFileTransEventCallback: Handles file transcription events. To prevent deadlocks, do not call other SDK methods from within this callback.

-(void)onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                      asrResult:(const char *)asr_result
                         taskId:(const char *)task_id
                       ifFinish:(bool)finish
                        retCode:(int)code {
    TLog(@"onNuiEventCallback event %d finish %d", nuiEvent, finish);
    if (nuiEvent == EVENT_FILE_TRANS_CONNECTED) {
        [myself showAsrResult:@"Connected. Uploading..."];
    } else if (nuiEvent == EVENT_FILE_TRANS_UPLOADED) {
        [myself showAsrResult:@"Upload complete. Transcribing..."];
    } else if (nuiEvent == EVENT_FILE_TRANS_RESULT) {
        NSString *result = [NSString stringWithUTF8String:asr_result];
        [myself showAsrResult:result];
    } else if (nuiEvent == EVENT_ASR_ERROR) {
        TLog(@"EVENT_ASR_ERROR error[%d]", code);
        NSString *result = [NSString stringWithUTF8String:asr_result];
        [myself showAsrResult:result];
    }

    if (finish) {
        // The task is complete.
        [myself showStart];
    }
    return;
}      

Cancel transcription

[_nui nui_file_trans_cancel:[task_id UTF8String]];

FAQ

# Other code is omitted.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
    end
  end
end