iOS SDK

前提条件与使用限制

• 已开通录音文件识别极速版商用服务。极速版不支持试用，服务限制与计费请参见录音文件识别极速版接口说明。

• 已获取项目 Appkey 和有效的 NLS Token，分别参见管理项目和获取 Token。

• 准备待识别的本地音频文件。支持 WAV、MP3、AAC、MP4、OPUS，文件大小不超过 100 MB，时长不超过 2 小时。项目中的识别模型应与音频语种匹配。

下载安装

1. 从移动端 SDK 选择与下载获取支持录音文件识别极速版的 iOS SDK 包，并按该页核对兼容性与合规使用要求。

2. 解压 SDK 包，将 nuisdk.xcframework 添加到 App 工程。在目标的中，将其嵌入方式设置为Embed & Sign。XCFramework 分别提供真机和模拟器变体，由 Xcode 按目标平台选择。

3. 在源文件中导入头文件。

#import <nuisdk/NeoNui.h>

SDK 包内的示例工程提供 FileTranscriberViewController.m，以及音频播放、录音和文件操作工具类，可按 App 需要使用。运行示例工程前，配置项目 Appkey 和服务端下发的 NLS Token。

V2.5.14 之后的 iOS SDK 使用 Objective-C 接口。V2.6.2 起，纯云端功能无需复制资源文件或设置 workspace。

调用步骤

1. 创建 NeoNui 实例，设置实现 NeoNuiSdkDelegate 的事件代理。

2. 在非 UI 线程调用 nui_initialize，传入 Appkey、NLS Token、设备标识和服务地址。

3. 构造包含本地文件路径、音频格式等配置的 JSON 参数，调用 nui_file_trans_start 发起识别。

4. 在 EVENT_FILE_TRANS_RESULT 事件中获取最终结果，在 EVENT_ASR_ERROR 事件中处理错误。

5. 任务结束或不再使用时调用 nui_release 释放资源。需要中止任务时，使用开始识别返回的任务 ID 调用 nui_file_trans_cancel。

代码示例

以下 Objective-C 示例使用 SDK V2.7.4-01B，将 App 包中的 example.wav 提交到服务端识别。将待识别的 WAV 文件加入 App 目标的资源，并将 Appkey、Token 替换为项目 Appkey 和服务端下发的有效 NLS Token。使用其他音频文件时，同时调整 file_path 和 nls_config.format。

示例通过独立工作队列执行 SDK 调用，在任务完成后释放资源，离开页面时取消未完成的任务。

#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

初始化、任务参数和识别结果字段的完整说明，请参见移动端 SDK 说明。

SDK 关键接口

使用 [NeoNui get_instance] 获取共享实例，也可以使用 [[NeoNui alloc] init] 创建独立实例。同一实例再次初始化前，先释放已有 SDK 资源。

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

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

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

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

- (NuiResultCode)nui_release;

事件回调

在实现 NeoNuiSdkDelegate 的代理对象中处理文件识别事件。

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

主要事件如下。

常见问题