iOS SDK

更新时间:
复制 MD 格式

使用 iOS NUI SDK 将录音数据实时发送到智能语音交互服务,并通过回调获取识别结果。本文介绍 SDK 集成、调用步骤、代码示例和关键接口。

前提条件

  • 已开通智能语音交互服务,并获取项目 Appkey。项目配置请参见管理项目。

  • 已获取 NLS Token,获取方法请参见获取 Token。

重要

AccessKey ID 和 AccessKey Secret 应保存在服务端,不得写入 App 代码或存储在移动端。云端实时语音识别使用 Appkey 和 NLS Token 鉴权;由服务端获取 Token 后下发给 App,并在 Token 过期前更新。

下载和集成 SDK

从移动端 SDK 选择与下载下载支持实时语音识别的 iOS NUI SDK 包。

以下集成说明和示例使用 V2.7.4-01B-20260904_iOS_TLS 包。SDK 未提供 CocoaPods 集成包,采用手动集成方式。2.5.14 版本后的 iOS 接口使用 Objective-C,不再需要通过 C++ 混合接口调用。

  1. 解压 SDK 包,选择与运行平台匹配的产物。

    产物

    用途

    Release/nuisdk.xcframework

    推荐用于真机和 Apple Silicon Mac 模拟器,分别包含 iOS arm64 和 iOS Simulator arm64 分支。

    Release/nuisdk.framework

    包含真机 arm64 和 Intel Mac 模拟器 x86_64。用于真机发布时,需要移除模拟器架构。

    Release-iphoneos/nuisdk.xcframework

    仅包含真机 arm64。

  2. 将选定的 Framework 或 XCFramework 添加到 Xcode 工程。在 Target 的 Build Phases > Link Binary With Libraries 中添加该库,并在 General > Frameworks, Libraries, and Embedded Content 中设置为 Embed & Sign。

  3. 导入 SDK 头文件:

    #import <nuisdk/NeoNui.h>
  4. 在 Info.plist 中配置 NSMicrophoneUsageDescription,说明麦克风用途,并在录音前获取麦克风使用权限。录音模块需要配置并激活 AVAudioSession。

SDK 包内的 Demo 工程提供录音、播放和文件操作工具类。实时语音识别示例为 SpeechTranscriberViewController,录音模块为 AudioController;替换 Appkey 和 Token 后可运行示例。Framework 内已包含 Resources.bundle。从 SDK 2.6.2 开始,纯云端识别不需要设置资源目录 workspace。

调用步骤

  1. 创建 SDK 和录音实例,设置代理并初始化 SDK。

  2. 调用 nui_set_params 配置识别参数,将 service_type 设置为 SERVICE_TYPE_SPEECH_TRANSCRIBER。

  3. 调用 nui_dialog_start:MODE_P2T 开始识别。

  4. 在 onNuiAudioStateChanged 回调中控制录音,在 onNuiNeedAudioData 回调中填充音频数据。

  5. 在 EVENT_ASR_PARTIAL_RESULT 和 EVENT_SENTENCE_END 事件中获取中间结果和句子结果。

  6. 调用 nui_dialog_cancel:NO 正常结束识别,等待任务结束回调,再调用 nui_release 释放 SDK 资源。

代码示例

以下示例使用 Demo 中的 AudioController.h 和 AudioController.m,录音格式为 16 kHz、16-bit、单声道 PCM。将辅助类及其依赖加入工程后,按顺序配置、开始和结束识别。初始化可能阻塞,应在非 UI 线程执行;同一实例的控制接口按顺序调用。

SDK 可通过 [NeoNui get_instance] 获取默认单例,也可通过 [[NeoNui alloc] init] 创建实例。以下示例使用后者。

配置网关

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

初始化、识别和回调

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

@interface SpeechRecognizer : NSObject <NeoNuiSdkDelegate, ConvVoiceRecorderDelegate>
@property(nonatomic, strong) NeoNui *nui;
@property(nonatomic, strong) AudioController *recorder;
@property(nonatomic, strong) NSMutableData *audioBuffer;
@property(atomic) BOOL finished;
@property(nonatomic, copy) void (^onFinished)(void);
- (int)configureWithAppkey:(NSString *)appkey token:(NSString *)token
                  gateway:(NSString *)gateway;
- (int)start;
- (int)stop;
- (int)releaseSdk;
@end

@implementation SpeechRecognizer
- (NSString *)jsonString:(NSDictionary *)value {
    NSData *data = [NSJSONSerialization dataWithJSONObject:value options:0 error:nil];
    return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
}

- (int)configureWithAppkey:(NSString *)appkey token:(NSString *)token
                  gateway:(NSString *)gateway {
    self.audioBuffer = [NSMutableData data];
    self.finished = YES;
    self.nui = [[NeoNui alloc] init];
    self.nui.delegate = self;
    self.recorder = [[AudioController alloc] init:only_recorder recorderSampleRate:16000];
    self.recorder.delegate = self;

    NSDictionary *initParams = @{
        @"app_key": appkey,
        @"token": token,
        @"url": gateway,
        @"device_id": [[NSUUID UUID] UUIDString],
        @"service_mode": @"1"
    };
    int code = [self.nui nui_initialize:[self jsonString:initParams].UTF8String
                              logLevel:NUI_LOG_LEVEL_VERBOSE saveLog:NO];
    if (code != 0) {
        return code;
    }

    NSDictionary *params = @{
        @"service_type": @(SERVICE_TYPE_SPEECH_TRANSCRIBER),
        @"nls_config": @{
            @"sample_rate": @16000,
            @"enable_intermediate_result": @YES
        }
    };
    code = [self.nui nui_set_params:[self jsonString:params].UTF8String];
    return code;
}

- (int)start {
    @synchronized(self) {
        [self.audioBuffer setLength:0];
    }
    self.finished = NO;
    int code = [self.nui nui_dialog_start:MODE_P2T dialogParam:"{}"];
    if (code != 0) {
        self.finished = YES;
    }
    return code;
}

- (int)stop {
    return [self.nui nui_dialog_cancel:NO];
}

- (int)releaseSdk {
    [self.recorder stopRecorder:NO];
    int code = [self.nui nui_release];
    self.nui.delegate = nil;
    self.recorder.delegate = nil;
    return code;
}

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

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

- (void)onNuiAudioStateChanged:(NuiAudioState)state {
    if (state == STATE_OPEN) {
        [self.recorder startRecorder];
    } else if (state == STATE_PAUSE || state == STATE_CLOSE) {
        [self.recorder stopRecorder:NO];
    }
}

- (void)onNuiEventCallback:(NuiCallbackEvent)event dialog:(long)dialog
                kwsResult:(const char *)wuw asrResult:(const char *)result
                 ifFinish:(BOOL)finish retCode:(int)code {
    if (event == EVENT_ASR_PARTIAL_RESULT || event == EVENT_SENTENCE_END) {
        if (result != NULL) {
            NSLog(@"Recognition result: %s", result);
        }
    } else if (event == EVENT_ASR_ERROR) {
        NSLog(@"Recognition error: %d, %s", code, result ?: "");
        const char *response = [self.nui nui_get_all_response];
        if (response != NULL) {
            NSLog(@"Error response: %s", response);
        }
    } else if (event == EVENT_MIC_ERROR) {
        NSLog(@"Audio input error");
    }
    if (finish) {
        self.finished = YES;
        if (self.onFinished) {
            self.onFinished();
        }
    }
}

- (void)onNuiRmsChanged:(float)rms {}
- (void)recorderDidStart {}
- (void)recorderDidStop {}
- (void)voiceDidFail:(NSError *)error {
    NSLog(@"Recorder error: %@", error);
}
- (void)playerDidStart {}
- (void)playerDrainDataFinish {}
- (void)playerDidFinish {}
- (void)playSoundLevel:(int)level {}
- (void)playData:(unsigned char *)buffer Length:(int)len {}
@end

App 持有 SpeechRecognizer 实例,在获得麦克风权限后调用以下初始化和开始代码。appkey、token 由业务服务端提供,gateway 使用前面的网关配置。

SpeechRecognizer *recognizer = [[SpeechRecognizer alloc] init];
dispatch_queue_t controlQueue = dispatch_queue_create("speech.control", DISPATCH_QUEUE_SERIAL);
__weak SpeechRecognizer *weakRecognizer = recognizer;
recognizer.onFinished = ^{
    dispatch_async(controlQueue, ^{
        [weakRecognizer releaseSdk];
    });
};
dispatch_async(controlQueue, ^{
    int code = [recognizer configureWithAppkey:appkey token:token gateway:gateway];
    if (code == 0) {
        code = [recognizer start];
    }
    if (code != 0) {
        NSLog(@"SDK call failed: %d", code);
        [recognizer releaseSdk];
    }
});

device_id 用于标识设备或 App 实例,建议使用具有唯一性的标识以便排查问题。示例生成应用侧 UUID;需要跨启动保持一致时,可由 App 保存并复用该值。

重要

事件回调中不要调用初始化、开始、停止或释放等 SDK 控制接口,以免发生死锁。nui_get_all_response 用于在当前事件回调中获取完整响应;需要更新 UI 时,将 UI 操作切换到主线程。

结束识别和释放资源

需要结束识别时,在同一控制队列中调用 stop。任务完成或发生错误后,回调的 finish 为 YES,示例通过 onFinished 将资源释放派发到控制队列,不在事件回调线程直接释放。

dispatch_async(controlQueue, ^{
    int code = [recognizer stop];
    if (code != 0) {
        NSLog(@"Stop failed: %d", code);
    }
});

nui_dialog_cancel:NO 等待正常结束,不保证每次停止都会产生句子结果;没有有效语音时,任务可以结束而不产生 EVENT_SENTENCE_END。

设置和更新参数

识别参数放在 nls_config 中,service_type 必须设置为 SERVICE_TYPE_SPEECH_TRANSCRIBER。enable_intermediate_result 是可选参数,开启后返回中间结果。其他可选配置如下,按业务需要设置,不需要全部启用。用以下片段替换 configureWithAppkey 中构造 params 并调用 nui_set_params 的部分。

NSMutableDictionary *nlsConfig = [NSMutableDictionary dictionary];
nlsConfig[@"enable_intermediate_result"] = @YES;
nlsConfig[@"enable_punctuation_prediction"] = @YES;
nlsConfig[@"enable_inverse_text_normalization"] = @YES;
// nlsConfig[@"enable_voice_detection"] = @YES;
// nlsConfig[@"max_start_silence"] = @10000;
// nlsConfig[@"max_end_silence"] = @800;
// nlsConfig[@"max_sentence_silence"] = @800;
// nlsConfig[@"enable_words"] = @NO;
// nlsConfig[@"sample_rate"] = @16000;
// nlsConfig[@"sr_format"] = @"opus";
NSDictionary *params = @{
    @"nls_config": nlsConfig,
    @"service_type": @(SERVICE_TYPE_SPEECH_TRANSCRIBER)
};
NSData *data = [NSJSONSerialization dataWithJSONObject:params options:0 error:nil];
NSString *json = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
code = [self.nui nui_set_params:json.UTF8String];

初始化字段及 direct_ip、extend_config 等 SDK 参数请参见移动端 SDK 接口说明。使用 HttpDNS 时可通过 direct_ip 设置地址;extend_config 用于传递 SDK 支持但未在专用字段中列出的扩展参数。

识别请求参数请参见实时语音识别接口说明。

需要在识别开始前更新 Appkey 或 Token 时,可在 SpeechRecognizer 中添加以下方法及对应声明,使用 startWithAppkey:token: 替代 start。若在同一已初始化实例上连续识别多轮,应在全部调用结束后释放资源,而不是每轮都在 onFinished 中释放。下一轮未设置相应临时参数时,继续使用初始化时传入的值。

- (int)startWithAppkey:(NSString *)appkey token:(NSString *)updatedToken {
    @synchronized(self) {
        [self.audioBuffer setLength:0];
    }
    self.finished = NO;
    NSDictionary *dialogParams = @{@"app_key": appkey, @"token": updatedToken};
    NSString *json = [self jsonString:dialogParams];
    int code = [self.nui nui_dialog_start:MODE_P2T dialogParam:json.UTF8String];
    if (code != 0) {
        self.finished = YES;
    }
    return code;
}

关键接口与回调

SDK 接口

初始化、参数配置、识别控制和释放接口返回 NuiResultCode,0 表示调用成功。识别结果和任务状态通过回调返回。

初始化和参数配置

nui_initialize:parameters 为初始化 JSON 字符串;level 为日志级别,值越小日志越详细;save_log 控制是否将日志保存到 debug_path。同一实例重新初始化前应先释放资源,初始化不要在 UI 线程执行。

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

开启文件日志时,确保 debug_path 有效且可写,并管理日志文件占用的存储空间。save_wav 在 save_log 开启时控制是否保存音频调试文件,文件保存在调试目录。

nui_set_params:以 JSON 字符串设置 SDK 和识别参数。

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

识别控制和释放

nui_dialog_start:开始识别,实时识别使用 MODE_P2T。dialog_params 可设置本轮临时参数;无需设置时传入空 JSON 对象。使用在线 VAD 时,通过 nls_config 启用相应配置。

- (NuiResultCode)nui_dialog_start:(NuiVadMode)vad_mode
                    dialogParam:(const char *)dialog_params;

nui_dialog_cancel:force=NO 停止送音并等待正常结束;force=YES 强制结束,不等待最终结果。

- (NuiResultCode)nui_dialog_cancel:(BOOL)force;

nui_release:释放 SDK 资源。

- (NuiResultCode)nui_release;

版本和响应查询

nui_get_version:返回 SDK 版本字符串。

- (const char *)nui_get_version;

nui_get_all_response:在事件回调中返回当前事件的完整 JSON 字符串。

- (const char *)nui_get_all_response;

NeoNuiSdkDelegate 回调

onNuiEventCallback:SDK 事件回调。dialog 是会话编号,暂不使用;wuw 用于语音唤醒,本文场景不使用;asr_result 包含识别结果或错误信息;finish 表示本轮任务结束;code 在 EVENT_ASR_ERROR 中提供错误码。可保留响应中的 task_id 用于排查问题。

- (void)onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                   dialog:(long)dialog kwsResult:(const char *)wuw
                asrResult:(const char *)asr_result
                 ifFinish:(BOOL)finish retCode:(int)code;

事件

说明

EVENT_VAD_START

检测到人声起点。

EVENT_VAD_END

检测到人声尾点。

EVENT_ASR_PARTIAL_RESULT

语音识别中间结果。

EVENT_ASR_RESULT

语音识别最终结果事件。

EVENT_ASR_ERROR

识别错误,根据错误码判断原因。

EVENT_MIC_ERROR

录音错误,表示 SDK 连续 2 秒未收到任何音频,检查录音系统和数据供给。

EVENT_SENTENCE_START

实时语音识别检测到一句话开始。

EVENT_SENTENCE_END

实时语音识别检测到一句话结束,返回该句完整结果。

EVENT_SENTENCE_SEMANTICS

暂不使用。

EVENT_TRANSCRIBER_COMPLETE

停止实时语音识别后上报任务完成。

onNuiNeedAudioData:识别开始后连续调用,App 向 audioData 填充音频;len 是请求的字节数,返回实际填充的字节数。

- (int)onNuiNeedAudioData:(char *)audioData length:(int)len;

onNuiAudioStateChanged:通知 App 控制录音,STATE_OPEN 打开录音,STATE_PAUSE 或 STATE_CLOSE 停止录音。

- (void)onNuiAudioStateChanged:(NuiAudioState)state;

onNuiRmsChanged:通知音频能量值,范围为 -160~0。

- (void)onNuiRmsChanged:(float)rms;

常见问题

Android 和 iOS SDK 能否用于专有云?

移动端 SDK 可以调用公共云的 ASR、TTS 服务,也可用于专有云环境。专有云安装包默认不包含移动端 SDK,可从帮助中心相应服务的 SDK 文档下载。

iOS 是否支持后台处理?

SDK 本身不限制前后台,后台录音还需要 App 配置相应能力,并保持录音模块和音频会话工作。集成后台录音时:

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

  2. 检查录音模块进入后台时的处理。如果使用旧 Demo 的 NLSVoiceRecorder.m,在 _appResignActive 中取消 AudioSessionSetActive(NO),避免进入后台时停止音频会话。当前包 Demo 使用 AudioController,按该模块的实现管理录音和音频会话。

- (void)_appResignActive {
    _inBackground = true;
    // AudioSessionSetActive(NO);
}

真机运行报错 no suitable image found,如何处理?

根据完整错误检查 Framework 是否包含真机架构、是否已嵌入 App,以及签名和 provisioning profile 是否匹配。使用当前包时,优先集成包含真机分支的 XCFramework。修正配置后,可删除设备上的旧 App,在 Xcode 中执行 Product > Clean Build Folder,重新构建并安装。签名错误应修正相应签名配置并重新打包。

出现 EVENT_MIC_ERROR,如何处理?

检查麦克风权限、录音设备是否被其他模块占用,以及录音模块是否持续提供音频数据。确认 onNuiNeedAudioData 返回实际填充的字节数,音频格式与识别参数一致。

导入 NeoNui.h 报错,如何处理?

确认已将 SDK 加入工程,并检查 Framework 搜索路径。头文件使用 #import <nuisdk/NeoNui.h>。动态库还需加入 Link Binary With Libraries,并设置为 Embed & Sign。

报错 built for iOS + iOS Simulator,或需要切换 Legacy Build System,如何处理?

该问题涉及将真机和模拟器架构合并的旧式 Framework。优先使用按平台分支组织的 XCFramework,并选择与目标平台匹配的产物。

旧包和旧版 Xcode 的处理

继续使用旧式 Framework 且对应 Xcode 提供 Validate Workspace 配置时,可将其设置为 Yes 后重新编译。这是旧集成方式的处理措施,当前 XCFramework 集成无需以切换 Legacy Build System 为前提。

Flutter 工程报 std::__1::mutex 等未定义符号,如何处理?

这些符号属于 C++ 运行库。检查 iOS Target 是否链接 libc++,并检查包含 C++ 代码的静态库及其依赖是否正确加入链接阶段。可在 Link Binary With Libraries 中添加 libc++.tbd。构建产物的架构也应与目标平台一致。

与 TRTC 同时使用麦克风时发生冲突,如何处理?

由一个录音模块采集音频,再向需要音频的 SDK 提供数据,可避免多个模块争用麦克风。NUI 侧通过 onNuiNeedAudioData 回调输入符合识别要求的 PCM 数据;TRTC 侧按其原生 iOS SDK 的音频输入接口接入。

App Store 提示 Unsupported Architectures,如何处理?

提交的真机 App 不应包含模拟器的 x86_64、i386 架构。优先使用 XCFramework,由构建过程选择真机分支。如果仍使用包含模拟器架构的旧式 Framework,检查其可执行文件,并在发布包中移除模拟器架构:

lipo -info /path/to/nuisdk.framework/nuisdk

lipo 操作对象是 Framework 内的可执行文件;XCFramework 的各平台分支分别存放,按目标平台选择对应分支。