使用 iOS NUI SDK 将录音数据实时发送到智能语音交互服务,并通过回调获取识别结果。本文介绍 SDK 集成、调用步骤、代码示例和关键接口。
前提条件
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++ 混合接口调用。
-
解压 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。
将选定的 Framework 或 XCFramework 添加到 Xcode 工程。在 Target 的 Build Phases > Link Binary With Libraries 中添加该库,并在 General > Frameworks, Libraries, and Embedded Content 中设置为 Embed & Sign。
-
导入 SDK 头文件:
#import <nuisdk/NeoNui.h> 在
Info.plist中配置NSMicrophoneUsageDescription,说明麦克风用途,并在录音前获取麦克风使用权限。录音模块需要配置并激活AVAudioSession。
SDK 包内的 Demo 工程提供录音、播放和文件操作工具类。实时语音识别示例为 SpeechTranscriberViewController,录音模块为 AudioController;替换 Appkey 和 Token 后可运行示例。Framework 内已包含 Resources.bundle。从 SDK 2.6.2 开始,纯云端识别不需要设置资源目录 workspace。
调用步骤
创建 SDK 和录音实例,设置代理并初始化 SDK。
调用
nui_set_params配置识别参数,将service_type设置为SERVICE_TYPE_SPEECH_TRANSCRIBER。调用
nui_dialog_start:MODE_P2T开始识别。在
onNuiAudioStateChanged回调中控制录音,在onNuiNeedAudioData回调中填充音频数据。在
EVENT_ASR_PARTIAL_RESULT和EVENT_SENTENCE_END事件中获取中间结果和句子结果。调用
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;
|
事件 |
说明 |
|
|
检测到人声起点。 |
|
|
检测到人声尾点。 |
|
|
语音识别中间结果。 |
|
|
语音识别最终结果事件。 |
|
|
识别错误,根据错误码判断原因。 |
|
|
录音错误,表示 SDK 连续 2 秒未收到任何音频,检查录音系统和数据供给。 |
|
|
实时语音识别检测到一句话开始。 |
|
|
实时语音识别检测到一句话结束,返回该句完整结果。 |
|
|
暂不使用。 |
|
|
停止实时语音识别后上报任务完成。 |
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 配置相应能力,并保持录音模块和音频会话工作。集成后台录音时:
在
Info.plist的 Required background modes 中添加 App plays audio or streams audio/video using AirPlay,对应UIBackgroundModes的audio值。检查录音模块进入后台时的处理。如果使用旧 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 的各平台分支分别存放,按目标平台选择对应分支。