本文介绍如何使用阿里云智能语音服务提供的iOS NUI SDK,包括SDK下载安装、关键接口及代码示例。
前提条件
下载安装
请下载后在样例初始化代码中替换您的阿里云账号信息、Appkey和Token才可运行。
类别 | 兼容范围 |
系统 | 最低支持iOS9。 |
架构 | arm64,x86_64 |
接口说明
create_conversation:创建交互,设置回调。对应销毁接口为destroy_conversation。
/** * @return:参见错误码 */ -(ConversationResultCode) create_conversation;
destroy_conversation:销毁交互。对应创建接口为create_conversation。
/** * @return:参见错误码 */ -(ConversationResultCode) destroy_conversation;
connect:与服务端建立链接。
/** * 初始化SDK并连接AI服务。 * @param parameters:json string形式的初始化参数,参见下方说明或接口说明: * @return:参见错误码 */ -(ConversationResultCode) connect:(const char *)parameters;
参数设置:
参数
类型
是否必选
说明
appkey
String
是
项目Appkey。详情请参见创建项目。
token
String
是
鉴权信息。
url
String
是
域名地址。生产环境网关URL:
wss://nls-gateway-cn-beijing.aliyuncs.com/ws/v1
dialog_id
String
否
对话ID,空代表新的对话,传入则代表继续通话。格式为32位随机字符串。
mode
String
否
运行模式。取值如下:
duplex(默认):在tap2talk的模式上提供语音打断能力,端侧具备移动端AEC算法处理能力。
tap2talk:语音起点由端侧VAD给出。
push2talk:按键语音交互,语音的起点和尾点由按键时间给出。
user_agent
String
否
客户端userAgent,用来记录和鉴权。
workspace
String
是
资源为resources目录下的相关文件。
例如以下示例工程中,通过拷贝aar包的资源文件,获得资源文件所处的路径,即为workspace。
NSString *strResourcesBundle = [[NSBundle mainBundle] pathForResource:@"TyResources" ofType:@"bundle"]; _workspace = [[NSBundle bundleWithPath:strResourcesBundle] resourcePath];
debug_path
String
否
日志和音频文件存储目录,不设置则在workspace下创建debug目录。
save_log
Boolean
否
是否存储日志,默认false。
save_wav
Boolean
否
是否存储音频,默认false。
log_level
String
否
日志级别,取值范围:
verbose
debug
info(默认)
warn
warning
error
device_id
String
否
设备唯一标识#utdid。
dialog_attributes
JSONObject
是
AI角色属性。
dialog_attributes.model_id
String
是
大模型ID(枚举,给出支持的列表)。
dialog_attributes.prompt
String
是
大模型prompt,最长800个字符。
dialog_attributes.voice
String
是
TTS音色(成品音色,比如 longxiaochun,或者客户克隆voiceName, 补充权限校验)。
dialog_attributes.voice_detection_enabled
Boolean
否
是否开启语音检测,去掉开始和结束的静音,并且当句尾静音长度超过X(服务端控制)的时候认为指令结束。
默认为true,push2talk模式可设为false。
advanced_attributes
JSONObject
否
高级属性。
advanced_attributes.context_depth
String
否
控制用户问题调大模型服务时附加多少历史对话,取值:
0:表示不附加历史。
n:大于0的整数表示附加n轮问答历史,范围 [1, 10]。
all(默认):表示附加本次通话中所有历史。
advanced_attributes.enable_search
String
否
是否开启LLM搜索增强,默认为false(不开启)。
advanced_attributes.xingchen
String
否
model_id为xingchen-model时表示调用星辰的模型,必传此内容。JSON格式字符串,JSON内容为:
"{\"character_id\":\"xxxxx\",\"user_id\":\"xxxx\"}"
character_id和user_id是星辰的参数,必传。
disconnect:断开链接。
/** * @param false:true则内部进行cancel再disconnect,false则内部进行stop再disconnect. * @return:参见错误码 */ -(ConversationResultCode) disconnect:(bool)force;
interrupt:打断交互,使AI进入听状态。在PushToTalk模式下,在AI说和AI思考状态下打断返回空闲状态。
/** * 打断交互。 * @return:返回打断结果,允许打断返回SUCCESS,拒绝打断返回REQUEST_DENIED */ -(ConversationResultCode) interrupt;
send_audio_data:推送音频数据。
/** * @return:参见错误码 */ -(ConversationResultCode) send_audio_data:(const unsigned char *)data Len:(int)length;
send_ref_data:推送参考音频数据,在音频数据送给播放器时推送。
/** * @return:参见错误码 */ -(ConversationResultCode) send_ref_data:(const unsigned char *)data Len:(int)length;
send_response_data:Listening或Idle状态下,通知服务端与用户主动交互,可以直接把上传的文本转换为语音下发,也可以上传文本调用大模型,返回的结果再转换为语音下发。
/** * @param parameters:json string形式的初始化参数,参见下方说明或接口说明: * @return:参见错误码 */ -(ConversationResultCode) send_response_data:(const char *)parameters;
参数设置:
参数
类型
是否必选
说明
type
String
是
服务应该采取的交互类型,取值如下:
transcript:表示直接把文本转语音。
prompt:表示把文本送大模型回答。
text
String
是
要处理的文本。
update_message:发送如RTC相关的参数,JSON格式。
/** * @return:参见错误码 */ -(ConversationResultCode) update_message:(const char *)parameters;
RTC相关命令
RTC INIT:
{"type":"rtc","action":"INIT"}
RTC设置:
{"type":"rtc",from_state":2,"seq_id":1,"to_state":0}
p2t模型相关命令
p2t按下按钮时更新agent_chat,可填写zh、en、ja、ko。
{"type":"update_nls_parameters","agent_chat":{"language_type":"zh","answer_language_type":"en"}} # 或 {"type":"update_nls_parameters","SendHumanSpeech_agent_chat":{"language_type":"zh","answer_language_type":"en"}} # SendHumanSpeech_agent_chat 优先级高于 agent_chat
更新其它参数命令。
{"type":"update_nls_parameters",avatar":{}} {"type":"update_nls_parameters",client_info":{}} {"type":"update_nls_parameters",agent_chat":{}}
set_action:需要有一个音频(播放)开始/结束事件告知到SDK。
};/** * @return:参见错误码 */ -(int) set_action:(ConvAppAction)action; enum ConvAppAction { MIC_STARTED = 0, MIC_STOPPED, PLAYER_STARTED, PLAYER_STOPPED, ENABLE_VOICE_INTERRUPT, DISABLE_VOICE_INTERRUPT, VOICE_MUTE, VOICE_UNMUTE, START_HUMAN_SPEECH, STOP_HUMAN_SPEECH, CANCEL_HUMAN_SPEECH, PULL_OUT_HEADPHONES };
ConvAppAction
名称
说明
MIC_STARTED
MIC开始工作。
MIC_STOPPED
MIC停止录音。
PLAYER_STARTED
开始播放。
PLAYER_STOPPED
播放完毕。
ENABLE_VOICE_INTERRUPT
开启语音打断功能。
DISABLE_VOICE_INTERRUPT
关闭语音打断功能。
START_HUMAN_SPEECH
仅在push2talk模式有效, 表示用户开始说话。
STOP_HUMAN_SPEECH
仅在push2talk模式有效,表示用户说话完毕。
CANCEL_HUMAN_SPEECH
仅在push2talk模式有效,表示用户说话取消。
PULL_OUT_HEADPHONES
拔耳机时调用,用于优化耳机切换的回声消除效果。
p2t模式按下按键代码示例。
// 设置语种 NSMutableDictionary *root = [NSMutableDictionary dictionary]; NSMutableDictionary *agent_chat = [NSMutableDictionary dictionary]; [agent_chat setObject:@"zh" forKey:@"language_type"]; [agent_chat setObject:@"en" forKey:@"answer_language_type"]; [root setObject:agent_chat forKey:@"agent_chat"]; [root setObject:@"update_nls_parameters" forKey:@"type"]; NSData *data = [NSJSONSerialization dataWithJSONObject:root options:NSJSONWritingPrettyPrinted error:nil]; NSString * jsonStr = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding]; [_conversation update_message:[jsonStr UTF8String]]; [_conversation set_action:START_HUMAN_SPEECH];
p2t模式松开按键代码示例。
[_conversation set_action:STOP_HUMAN_SPEECH];
p2t模式取消用户说话代码示例。
conv_instance.setAction(ConvConstants.ConvAppAction.CANCEL_HUMAN_SPEECH);
get_state:获得当前各种状态。
/** * @param param: * @return:根据ConvStateType,返回对应事件的枚举值的int值,需要转换对应枚举 */ -(int) get_state:(ConvStateType)type; enum ConvStateType { DIALOG_STATE = 0, MIC_STATE, PLAYER_STATE, }; /** * 返回对应枚举 */ enum ConvDialogState { DIALOG_IDLE = 0, DIALOG_LISTENING, DIALOG_RESPONDING, DIALOG_THINKING, }; enum ConvAppAction { MIC_STARTED = 0, MIC_STOPPED, PLAYER_STARTED, PLAYER_STOPPED, };
ConvStateType
名称
说明
DIALOG_STATE
对话(AI)当前状态,枚举值为ConvConstants.DialogState。
MIC_STATE
MIC当前状态,枚举值为ConvConstants.ConvAppAction。
PLAYER_STATE
PLAYER当前状态,枚举值为ConvConstants.ConvAppAction。
返回对应的事件枚举ConvDialogState
名称
说明
DIALOG_IDLE
当前处于空闲未工作状态。
DIALOG_LISTENING
AI(服务端)处于听状态,接收用户输入数据(如MIC音频数据)。
DIALOG_RESPONDING
AI(服务端)处于反馈状态,发送AI的数据(如TTS音频数据)。
DIALOG_THINKING
AI(服务端)处于思考阶段。
ConvAppAction
名称
说明
MIC_STARTED
MIC开始工作。
MIC_STOPPED
MIC停止录音。
PLAYER_STARTED
开始播放。
PLAYER_STOPPED
播放完毕。
NativeConversation中回调
onConvEventCallback:SDK事件回调。
/** * SDK主要事件回调 * @param event_type:见下方ConvEventType * @param status_code:状态码/错误码 * @param error_message:错误信息 * @param response:服务端返回的完整信息 * @param task_id:当轮对话id,用于调试和定位问题 * @param session_id:会话的id,又为dialog_id * @param terminate:是否中断,true的话表示当前会话中断,再次使用需要调用connect() */ -(void) onConvEventCallback:(ConvEventType)event_type statusCode:(int)status_code errMsg:(const char*)error_message result:(const char*)response taskId:(const char*)task_id sessionId:(const char*)session_id terminate:(BOOL)terminate;
onConvStateChangedCallback:SDK状态回调。
/** * SDK状态回调 * @param state:回调事件,可通过调用其中具体方法获得事件及相关信息。具体方法见下方ConvDialogState */ -(void) onConvStateChangedCallback:(int)state; enum ConvDialogState { DIALOG_IDLE = 0, DIALOG_LISTENING, DIALOG_RESPONDING, DIALOG_THINKING, };
ConvDialogState:AI(服务端)状态。
名称
说明
DIALOG_IDLE
当前处于空闲未工作状态。
DIALOG_LISTENING
AI(服务端)处于听状态,接收用户输入数据(如MIC音频数据)。
DIALOG_RESPONDING
AI(服务端)处于反馈状态,发送AI的数据(如TTS音频数据)。
DIALOG_THINKING
AI(服务端)处于思考阶段。
onConvDataReceivedCallback:收到返回的结果数据。
/** * 获得返回数据(如音频)回调 * @param data:返回数据的buffer指针 * @param len:返回数据字节数 */ -(int) onConvDataReceivedCallback:(unsigned char *)data length:(int)len;
onConvSoundLevelCallback:获得的输入音频的音量级别。
/** * 计算输入音频的音量级别,从低到高0-100,以及对应的db值 * @param level:音频的音量级别,从低到高0-100 * @param db:音频db值,-160 - 0 */ -(void) onConvSoundLevelCallback:(int)level db:(float)db;
onConvEventTrackCallback:获得关键埋点信息日志。
/** * 日志埋点输出函数 * @param level:输出日志的级别 * @param log:关键埋点信息日志 */ -(void) onConvEventTrackCallback:(int)level log:(const char*)log;
ConvEventType:
SDK事件名称
事件说明
EVENT_CONVERSATION_START
会话任务成功启动,建连成功。
EVENT_CONVERSATION_FAILED
会话任务发生错误,需要查看错误码及错误信息。收到此事件后需要根据错误信息判断如何处理,也可以使用此dialog_id重新连接,继续会话。
EVENT_COVERSATION_COMPLETED
任务成功完成,执行断连操作。
EVENT_DATA_OUTPUT_STARTED
开始播放服务端TTS数据。
EVENT_DATA_OUTPUT_COMPLETED
服务端TTS数据合成完成。
EVENT_SENTENCE_BEGIN
HUMAN开始说话。PushToTalk模式按键则触发此事件,TapToTalk和Duplex模式是用户开始说话触发此事件。
EVENT_SENTENCE_FINAL
HUMAN说话结束。PushToTalk模式按键松开则触发此事件,TapToTalk和Duplex模式是用户说话结束触发此事件。
EVENT_INTERRUPT_ACCEPTED
AI(服务端)接收按键请求(如打断)。
EVENT_VOICE_INTERRUPT_ACCEPTED
AI(服务端)接收语音请求(如打断)。
EVENT_HUMAN_SPEAKING_DETAIL
ASR识别结果。
EVENT_RESPONDING_DETAIL
大模型返回的结果。
SDK错误码
状态码 | 状态消息 | 说明 |
MEM_ALLOC_ERROR | 内存分配失败。 | |
50 | INIT_FAILED | 初始化为不支持的模式。 |
51 | NOT_CONNECTED | 链接失败,如联网超时等。 |
52 | ENGINE_NULL | 交互引擎未创建,不可使用。 |
53 | ILLEGAL_PARAM | 设置参数非法。 |
54 | ILLEGAL_INIT_PARAM | 初始化参数非法。 |
55 | INVALID_STATE | 当前交互状态无法调用此接口。 |
56 | HAS_INVOKED | 已经调用了此接口。 |
57 | NOT_CREATE_CONVERSATION | 还未创建会话即未调用createConversation就开始操作。 |
58 | SKIP_SEND_DATA | 当前交互状态忽略此次音频。 |
59 | SEND_DATA_FAILED | 发送音频失败。 |
60 | INVALID_AUDIO_DATA | 无效音频。 |
61 | STOP_FAILED | stop()失败,如超时。 |
62 | CANCEL_FAILED | cancel()失败,如超时。 |
63 | INVOKE_TIMEOUT | 接口调用超时。 |
64 | REQUEST_DENIED | 打断请求拒绝。 |
65 | REQUEST_ACCEPTED | 允许打断请求。 |
100 | INTERNAL_ENGINE_INIT_FAILED | 内部引擎初始化失败,常发生于connect()时。 |
101 | INTERNAL_ENGINE_SET_PARAM_FAILED | 内部引擎配置参数失败。 |
111 | INTERNAL_ENGINE_RESOURCE_NOT_FOUND | 内部引擎因为找不到资源文件而初始化失败,请检查资源文件是否完备,且是最新版本 |
112 | INTERNAL_ENGINE_VAD_INVALID_PARAM | 内部vad引擎的初始化参数非法。 |
113 | INTERNAL_ENGINE_VAD_INVALID_STATE | 内部vad引擎运行处于异常状态,比如vad已经释放。 |
114 | INTERNAL_ENGINE_VAD_PROCESS_FAILED | 内部VAD引擎在异常状态送入数据。 |
115 | INTERNAL_ENGINE_VAD_CREATE_FAILED | 内部vad引擎初始化失败,一般是由于资源文件缺失或者不兼容的旧版本。 |
200 | EMPTY_CONV_EVENT | 非法ConvEvent。 |
201 | INVALID_CONV_EVENT_MSG_TYPE | 非法的ConvEvent事件类型。 |
301 | SERVER_NOT_ACCESS | 链接服务端失败,比如服务端不可链接,DNS不可解析等。 |
311 | JSON_FORMAT_ERROR | 接收到服务端返回的消息不符合JSON格式。 |
312 | SSL_ERROR | SSL失败,比如握手失败。 |
313 | SSL_CONNECT_FAILED | SSL链接失败。 |
351 | NLS_INVOKE_TIMEOUT | 向服务端发送请求操作超时。 |
352 | NLS_START_FAILED | 向服务端发送建立会话请求失败,常为网络问题。 |
353 | NLS_STOP_FAILED | 向服务端发送停止会话请求失败,常为网络问题。 |
354 | NLS_CANCEL_FAILED | 向服务端发送停止会话请求失败,常为网络问题。 |
355 | NLS_START_INBOUND_FAILED | 向服务端发送启动对话任务请求失败,常为网络问题。 |
358 | NLS_CANCEL_BOUND_FAILED | 向服务端发送停止对话任务请求失败,常为网络问题。 |
359 | NLS_SET_PARAMS_FAILED | 设置请求参数错误,比如设置token无效。 |
360 | NLS_SEND_AUDIO_FAILED | 向服务端发送音频数据失败,常为网络问题 |