iOS SDK

初始化

在控制器中实现 NeoNuiSdkDelegate 和录音模块的 ConvVoiceRecorderDelegate，持有 SDK 实例、录音实例及音频缓冲区：

#import <nuisdk/NeoNui.h>
#import "audio/AudioController.h"

@interface SpeechRecognizerViewController () <NeoNuiSdkDelegate, ConvVoiceRecorderDelegate>
@property(nonatomic, strong) NeoNui *nui;
@property(nonatomic, strong) AudioController *audioController;
@property(nonatomic, strong) NSMutableData *recordedVoiceData;
@end

get_instance 用于获取单例；需要多个实例时，可以使用 [[NeoNui alloc] init]。同一实例再次初始化前，应先调用 nui_release。

配置服务地址：

NSString *gateway = @"wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1";

将 <Appkey> 和 <NLS Token> 替换为项目 Appkey 和服务端下发的有效 Token，在工作队列中执行初始化：

_nui = [NeoNui get_instance];
_nui.delegate = self;
_recordedVoiceData = [NSMutableData data];
_audioController = [[AudioController alloc] init:only_recorder];
_audioController.delegate = self;

NSDictionary *initParams = @{
    @"app_key": @"<Appkey>",
    @"token": @"<NLS Token>",
    @"url": gateway,
    @"service_mode": @"4"
};
NSData *initData = [NSJSONSerialization dataWithJSONObject:initParams options:0 error:nil];
NSString *initJSON = [[NSString alloc] initWithData:initData encoding:NSUTF8StringEncoding];
NuiResultCode result = [_nui nui_initialize:initJSON.UTF8String
                                 logLevel:NUI_LOG_LEVEL_NONE
                                  saveLog:NO];
if (result != 0) {
    NSLog(@"nui_initialize failed: %d", result);
    return;
}

自 2.6.2 起，纯云端功能可以不设置 workspace 和 device_id。旧版本需要 workspace 时，将其设置为 Resources.bundle 的资源路径。device_id 用于辅助定位问题，不要求使用广告标识符。

调试时可将日志级别设置为 NUI_LOG_LEVEL_VERBOSE。启用 saveLog 时，需设置可写的 debug_path；save_wav 用于控制是否保存调试音频。日志文件没有大小上限，应及时清理，避免占满存储空间。

设置参数

通过 JSON 设置识别参数。enable_intermediate_result 为可选参数；需要中间结果时设置为 YES。

NSMutableDictionary *nlsConfig = [@{
    @"enable_intermediate_result": @YES,
    @"sample_rate": @16000,
    @"sr_format": @"pcm"
} mutableCopy];
NSDictionary *params = @{
    @"service_type": @(SERVICE_TYPE_ASR),
    @"nls_config": nlsConfig
};
NSData *paramsData = [NSJSONSerialization dataWithJSONObject:params options:0 error:nil];
NSString *paramsJSON = [[NSString alloc] initWithData:paramsData encoding:NSUTF8StringEncoding];
NuiResultCode result = [_nui nui_set_params:paramsJSON.UTF8String];
if (result != 0) {
    NSLog(@"nui_set_params failed: %d", result);
    return;
}

01B 版本不包含本地 VAD 模块；带唤醒功能的 029 版本包含本地 VAD 模块。需要自动判断一句话结束时，可以在上述 nlsConfig 创建后、序列化前添加在线 VAD 参数，开始识别时仍使用 MODE_P2T：

nlsConfig[@"enable_voice_detection"] = @YES;
nlsConfig[@"max_start_silence"] = @10000;
nlsConfig[@"max_end_silence"] = @800;

标点预测、逆文本规整、采样率、音频传输格式等参数的含义及取值，请参见接口说明。

如果使用 HTTPDNS，可通过顶层参数 direct_ip 设置解析得到的 IP。对于服务支持、但 SDK 尚未单独列出的参数，可通过顶层对象 extend_config 传入。

开始识别

NuiResultCode result = [_nui nui_dialog_start:MODE_P2T dialogParam:"{}"];
if (result != 0) {
    NSLog(@"nui_dialog_start failed: %d", result);
}

需要为当前识别任务更新 Appkey 或 Token 时，将 app_key、token 放入 dialogParam 的 JSON 字符串。下一轮任务未传入这些临时参数时，继续使用初始化时的参数。

处理回调

录音状态与数据供给

根据 SDK 音频状态启动或停止录音，将录音模块回调的数据存入缓冲区，再通过 onNuiNeedAudioData 提供给 SDK。

- (void)onNuiAudioStateChanged:(NuiAudioState)state {
    if (state == STATE_OPEN) {
        @synchronized (self) {
            [_recordedVoiceData setLength:0];
        }
        [_audioController startRecorder];
    } else if (state == STATE_CLOSE || state == STATE_PAUSE) {
        [_audioController stopRecorder:NO];
    }
}

- (void)voiceDidFail:(NSError *)error {
    NSLog(@"Recording failed: %@", error.localizedDescription);
}

- (void)voiceRecorded:(unsigned char *)buffer Length:(int)len {
    @synchronized (self) {
        [_recordedVoiceData appendBytes:buffer length:(NSUInteger)len];
    }
}

- (int)onNuiNeedAudioData:(char *)audioData length:(int)len {
    @synchronized (self) {
        NSUInteger count = MIN(_recordedVoiceData.length, (NSUInteger)len);
        if (count == 0) return 0;
        [_recordedVoiceData getBytes:audioData length:count];
        [_recordedVoiceData replaceBytesInRange:NSMakeRange(0, count)
                                     withBytes:NULL length:0];
        return (int)count;
    }
}

识别结果与错误

asr_result 包含识别结果或错误信息，task_id 可用于排查请求问题。finish 为真表示本轮任务结束，可能是正常完成，也可能是发生错误。

- (void)onNuiEventCallback:(NuiCallbackEvent)event
                   dialog:(long)dialog
                kwsResult:(const char *)wuw
                asrResult:(const char *)asrResult
                 ifFinish:(BOOL)finish
                  retCode:(int)code {
    NSString *message = asrResult ? [NSString stringWithUTF8String:asrResult] : @"";
    if (event == EVENT_ASR_PARTIAL_RESULT || event == EVENT_ASR_RESULT) {
        NSLog(@"ASR result: %@", message);
    } else if (event == EVENT_ASR_ERROR || event == EVENT_MIC_ERROR) {
        NSLog(@"ASR error: %d, %@", code, message);
    }
    if (finish) {
        dispatch_async(dispatch_get_main_queue(), ^{
            // 更新界面状态，允许开始下一轮识别。
        });
    }
}

结束识别与释放资源

正常停止时使用 NO，等待最终结果和任务结束回调。没有有效语音时，最终识别文本可能为空。

[_nui nui_dialog_cancel:NO];

不再需要结果时，可以使用 nui_dialog_cancel:YES 强制结束，并由应用执行清理操作。不再使用 SDK 时，在 SDK 回调之外释放资源并解除代理绑定：

[_audioController stopRecorder:NO];
[_nui nui_release];
_nui.delegate = nil;
_audioController.delegate = nil;

找不到 NeoNui.h，如何处理？

确认 SDK 已添加到工程并参与链接，头文件使用 #import <nuisdk/NeoNui.h>，不要使用 #import "nuisdk.framework/Headers/NeoNui.h"。动态库还需设置 Embed & Sign。

移动端 SDK 能否用于专有云？

移动端 SDK 可以调用公共云的 ASR、TTS 服务，也可以用于专有云环境。专有云安装包默认不包含移动端 SDK，可从对应服务的文档下载，例如实时语音识别的Android SDK和iOS SDK。

是否支持后台处理？

SDK 本身不限制前后台，后台录音还受 iOS 音频会话及应用配置约束。需要后台录音时：

1. 在 Info.plist 的 Required background modes（UIBackgroundModes）中添加 audio，对应 App plays audio or streams audio/video using AirPlay。

2. 检查录音模块的后台处理，避免进入后台时主动停止录音或停用音频会话。旧版 NLSVoiceRecorder.m 的 _appResignActive 方法需去掉 AudioSessionSetActive(NO) 调用。

2.7.4 Demo 使用 AudioController 录音模块，已配置 UIBackgroundModes=audio，且后台处理不调用 AudioSessionSetActive(NO)。

真机提示 no suitable image found，如何处理？

先确认链接的是适用于真机的库，再尝试删除设备上的应用、清理构建产物并重新安装。同时检查应用和动态库的签名、证书及 provisioning profile 是否匹配。若确认使用的企业证书无效，重新制作有效证书和 provisioning profile，并重新签名、打包。

出现 EVENT_MIC_ERROR，如何处理？

检查麦克风权限、录音设备是否被其他模块占用，以及 onNuiNeedAudioData 是否持续提供音频。连续 2 秒没有音频数据会触发该事件。

提示库同时面向 iOS 和 iOS Simulator，如何处理？

出现 Building for iOS, but the linked and embedded framework ... was built for iOS + iOS Simulator 时，检查是否使用了旧版混合平台的 Framework。改为集成 SDK 包中的 nuisdk.xcframework，由 Xcode 根据构建目标选择对应平台的库，不要将模拟器库嵌入真机应用。

App Store 提示 Unsupported Architectures，如何处理？

如果旧版 Framework 包含 x86_64、i386 等模拟器架构，可通过 lipo -info <Framework二进制文件> 检查，并在真机分发包中移除模拟器架构。使用 XCFramework 时，应归档真机构建目标，由 Xcode 选择真机库。

旧工程需要 Legacy Build System 才能构建，如何处理？

对于仍提供 Validate Workspace 配置的旧版 Xcode 工程，可尝试将其设置为 Yes 后重新编译。新工程应按当前 SDK 包结构集成 XCFramework。