iOS SDK
本文介绍了如何使用阿里云离线语音合成服务提供的iOS NUI SDK,包括下载安装SDK和语音包、SDK关键接口及代码示例。
前提条件
下载安装
- 说明
下载后在样例初始化代码中替换您的阿里云账号信息、Appkey才可运行。为方便集成,2.5.14版本后iOS接口使用纯Object-C接口,不再使用C++混合接口。
类别
兼容范围
系统
最低支持iOS9
架构
arm64,x86_64
此SDK还包含如下功能,若未支持您想要的功能,请前往对应文档获取SDK。
功能
是否支持
一句话识别
是
实时语音识别
是
语音合成
是
实时长文本语音合成
是
流式文本语音合成
是
离线语音合成
是
录音文件识别极速版
是
唤醒及命令词
否
听悟实时推流
是
下载语音包,详情请参见接口说明中的语音包列表。
重要SDK和语音包是完全独立的,下载SDK后并不能直接使用,需要下载语音包,并设置语音包存放路径。
解压ZIP包。
将ZIP包中的nuisdk.framework添加到您的工程中,并在工程Build Phases的Link Binary With Libraries中添加nuisdk.framework。
使用Xcode打开此工程。
工程中提供了参考代码以及一些直接可使用的工具类,例如音频播放录制和文件操作,您可以直接复制源码到您的实际工程进行使用。其中语音合成示例代码在LocalTTSViewController类中。替换appkey和token后可直接运行。
SDK关键接口
nui_tts_initialize:初始化SDK。
/** * 初始化SDK,离线合成暂不支持多实例,请先释放后再次进行初始化。请勿在UI线程调用,意外下可能引起阻塞。 * 初始化是耗时操作,不需要合成一个任务就进行该操作;在启动和退出时进行一次即可。 * @param parameters: 初始化参数,参考接口说明。 :https://help.aliyun.com/zh/isi/developer-reference/sdk-reference-11 * @param level: log打印级别,值越小打印越多 * @param save_log: 是否保存log为文件,存储目录为parameter中的debug_path字段值。注意,log文件无上限,请注意持续存储导致磁盘存满。 * @return 参考错误码:https://help.aliyun.com/document_detail/459864.html */ -(int) nui_tts_initialize:(const char *)parameters logLevel:(NuiSdkLogLevel)level saveLog:(BOOL)save_log;
nui_tts_play:开始播放。
/** * 开始播放,该接口异步执行 * @param priority: 任务优先级,请使用"1"。 * @param taskid: 任务ID,可传入32个字节的uuid或者传入空内容由SDK自动生成。 * @param text: 要播放的文本内容。 * @return 参考错误码。 */ -(int) nui_tts_play:(const char *)priority taskId:(const char *)taskid text:(const char *)text;
nui_tts_cancel:取消播放。
/** * 取消合成任务 * @param taskid: 传入想要停止的任务ID,如果为空则取消所有任务。 * @return 参考错误码。 */ -(int) nui_tts_cancel:(const char *)taskid;
nui_tts_pause:暂停播放。
/** * 暂停 * @return 参考错误码。 */ -(int) nui_tts_pause;
nui_tts_resume:恢复播放。
/** * 恢复暂停的任务 * @return 参考错误码。 */ -(int) nui_tts_resume;
nui_tts_set_param:设置语音合成参数。
/** * 以键值对形式设置参数 * @param param: 参数名,参考接口说明:https://help.aliyun.com/zh/isi/developer-reference/sdk-reference-11 * @param value: 参数值,参考接口说明:https://help.aliyun.com/zh/isi/developer-reference/sdk-reference-11 * @return 参考错误码 */ -(int) nui_tts_set_param:(const char *)param value:(const char *)value;
nui_tts_get_param:获取参数。
/** * 获取参数值 * @param param: 参数名,参考接口说明:https://help.aliyun.com/zh/isi/developer-reference/sdk-reference-11 * @return 参数值 */ -(const char *) nui_tts_get_param:(const char *)param;
nui_tts_release:释放SDK资源。
/** * 释放SDK * @return 参考错误码。 */ -(int) nui_tts_release;
NeoNuiTtsDelegate事件代理
onNuiTtsUserdataCallback:在回调中提供音频数据。
/** * 当开始识别时,此回调被连续调用,App需要在回调中进行语音数据填充。 * @param info: 在使用时间戳功能时返回时间戳结果,JSON格式。 * @param info_len: info字段的数据长度。 * @param buffer: 合成的语音数据。 * @param len: 合成的语音长度。 * @param taskid: 本次合成的任务ID。 */ - (void)onNuiTtsUserdataCallback:(char*)info infoLen:(int)info_len buffer:(char*)buffer len:(int)len taskId:(char*)task_id;
onNuiTtsEventCallback: 事件回调。
/** * SDK主要事件回调 * @param event: 回调事件,参考接口说明:https://help.aliyun.com/zh/isi/developer-reference/sdk-reference-11 * @param taskid: 本次合成的任务id * @param code: 参考错误码,TTS_EVENT_ERROR时有效 */ - (void)onNuiTtsEventCallback:(NuiSdkTtsEvent)event taskId:(char*)taskid code:(int)code;
NuiSdkTtsEvent事件列表:
名称
说明
TTS_EVENT_START
语音合成开始,准备播放。
TTS_EVENT_END
语音合成结束,合成数据已全部抛出,但并不表示播放结束。
TTS_EVENT_CANCEL
取消语音合成。
TTS_EVENT_PAUSE
语音合成暂停。
TTS_EVENT_RESUME
语音合成恢复。
TTS_EVENT_ERROR
语音合成发生错误。
调用步骤
初始化SDK和播放组件。
根据业务需要设置参数。
调用nui_tts_play进行播放。
在合成数据回调中,将数据写入播放器进行播放,建议使用流式播放。
收到语音合成结束的回调。
代码示例
语音合成初始化。
// 一次初始化成功,可以反复调用合成和参数设置接口,不需要频繁初始化和释放,减少耗时 NSString * initParam = [self genInitParams]; [_nui nui_tts_initialize:[initParam UTF8String] logLevel:LOG_LEVEL_VERBOSE saveLog:true]; if (retcode != 0) { // 初始化失败,通过"error_msg"查看详细的错误信息,离线语音合成FAQ文档中已列出常见错误。 const char *errmsg = [_nui nui_tts_get_param: "error_msg"]; TLog(@"init failed. retcode:%d. errmsg:%s", retcode, errmsg); // 初始化失败不需要再调用参数设置和合成接口 return; }
其中,genInitParams生成为String JSON字符串,包含资源目录和用户信息。其中用户信息包含如下字段。
-(NSString *)genInitParams { NSString *strResourcesBundle = [[NSBundle mainBundle] pathForResource:@"Resources" ofType:@"bundle"]; NSString *bundlePath = [[NSBundle bundleWithPath:strResourcesBundle] resourcePath]; NSString *debug_path = [_utils createDir]; NSMutableDictionary *dictM = [NSMutableDictionary dictionary]; //郑重提示: // 语音交互服务需要先准备好账号,并开通相关服务。具体步骤请查看: // https://help.aliyun.com/zh/isi/getting-started/start-here // //原始账号: // 账号(子账号)信息主要包括AccessKey ID(后续简称为ak_id)和AccessKey Secret(后续简称为ak_secret)。 // 此账号信息一定不可存储在app代码中或移动端侧,以防账号信息泄露造成资费损失。 // //STS临时凭证: // 由于账号信息下发给客户端存在泄露的可能,阿里云提供的一种临时访问权限管理服务STS(Security Token Service)。 // STS是由账号信息ak_id和ak_secret,通过请求生成临时的sts_ak_id/sts_ak_secret/sts_token // (为了区别原始账号信息和STS临时凭证, 命名前缀sts_表示STS生成的临时凭证信息) //什么是STS:https://help.aliyun.com/zh/ram/product-overview/what-is-sts //STS SDK概览:https://help.aliyun.com/zh/ram/developer-reference/sts-sdk-overview //STS Python SDK调用示例:https://help.aliyun.com/zh/ram/developer-reference/use-the-sts-openapi-example // //账号需求说明: // 若使用离线功能(离线语音合成、唤醒), 则必须app_key、ak_id和ak_secret,或app_key、sts_ak_id、sts_ak_secret和sts_token // 若使用在线功能(语音合成、实时转写、一句话识别、录音文件转写等), 则只需app_key和token //获取账号访问凭证: [_utils getTicket:dictM Type:get_sts_access_from_server_for_offline_features]; //请参照阿里云官网获取鉴权信息获取配额 // https://help.aliyun.com/document_detail/251488.html?spm=a2c4g.11186623.6.638.1f0d530eut95Jn // 如果配额已耗尽,请联系客户扩大配额 // 如果合成失败,通常是由于鉴权失败,可以参照阿里云官网Q&A部分 // https://help.aliyun.com/document_detail/204191.html?spm=a2c4g.11186623.6.657.3cde7340qMll1h ,根据错误日志判别导致鉴权失败的原因 //工作目录路径,SDK从该路径读取配置文件 [dictM setObject:bundlePath forKey:@"workspace"]; // 如果需要保存调试日志到文件,初始化的时候加入该字段;不要保存日志,该字段删除 // 日志文件是追加的方式存储的,下次初始化时并不会将老日志冲掉重写 // 另外,在开启保存日志文件时,可以动态的通过接口nui_tts_set_param将日志等级设置成最高值,保证日志不写入文件,等需要写入时再动态设置成较低的等级 [dictM setObject:debug_path forKey:@"debug_path"]; TLog(@"debug_path:%@", debug_path); TLog(@"workspace:%@", bundlePath); [dictM setObject:@"wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1" forKey:@"url"]; // 设置成本地语音合成模式, 这个设置很重要, 遗漏会导致无法运行 [dictM setObject:@"0" forKey:@"mode_type"]; // 必填 // 特别说明: 鉴权所用的id是由以下device_id,与手机内部的一些唯一码进行组合加密生成的。 // 更换手机或者更换device_id都会导致重新鉴权计费。 // 此外, 以下device_id请设置有意义且具有唯一性的id, 比如用户账号(手机号、IMEI等), // 传入相同或随机变换的device_id会导致鉴权失败或重复收费。 // NSString *id_string = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString]; 并不能保证生成不变的device_id,请不要使用 [dictM setObject:@"empty_device_id" forKey:@"device_id"]; // 必填 NSData *data = [NSJSONSerialization dataWithJSONObject:dictM options:NSJSONWritingPrettyPrinted error:nil]; NSString * jsonStr = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding]; return jsonStr; }
根据需求设置参数。
//加载语音包:已购买的语音包,可以放在任意位置,以aijia为例,该语音包位于Documents/voices/下,设置命令为“Documents/voices/aijia” NSString *cmd = [NSString stringWithFormat:@"%@/aijia", myvoicedir]; [self.nui nui_tts_set_param:"extend_font_name" value:[cmd UTF8String]];
启动语音合成。
//建议同一时间单示例启动一个task进行语音合成,单实例多task易出异常。 [self.nui nui_tts_play:"1" taskId:"" text:[content UTF8String]];
取消语音合成
//如果上个任务没有合成完毕,手动取消,开始合成新的任务。 //建议同一时间单示例启动一个task进行语音合成,单实例多task易在cancel时出异常。 [self.nui nui_tts_cancel:NULL];
回调处理。
onNuiTtsEventCallback:语音合成事件回调,根据语音合成状态控制播放器。
- (void)onNuiTtsEventCallback:(NuiSdkTtsEvent)event taskId:(char*)taskid code:(int)code { TLog(@"onNuiTtsEventCallback event[%d]", event); if (event == TTS_EVENT_START) { TLog(@"onNuiTtsEventCallback TTS_EVENT_START"); loop_in = TTS_EVENT_START; // 旧版本示例工程提供的播放器,仅做参考,可根据自身业务重写播放器。 // [self->_voicePlayer play]; // 新版本示例工程提供了新的播放器,仅做参考,可根据自身业务重写播放器。 [_audioController startPlayer]; } else if (event == TTS_EVENT_END || event == TTS_EVENT_CANCEL || event == TTS_EVENT_ERROR) { loop_in = event; if (event == TTS_EVENT_END) { TLog(@"onNuiTtsEventCallback TTS_EVENT_END"); // 旧版本示例工程提供的播放器,仅做参考,可根据自身业务重写播放器。 // 注意这里的event事件是指语音合成完成,而非播放完成,播放完成需要由voicePlayer对象来进行通知 // [self->_voicePlayer drain]; // 新版本示例工程提供了新的播放器,仅做参考,可根据自身业务重写播放器。 // 注意这里的event事件是指语音合成完成,而非播放完成,播放完成需要由audioController对象来进行通知 [_audioController drain]; } else { // 旧版本示例工程提供的播放器,仅做参考,可根据自身业务重写播放器。 // 取消播报、或者发生异常时终止播放 // [self->_voicePlayer stop]; // 新版本示例工程提供了新的播放器,仅做参考,可根据自身业务重写播放器。 // 取消播报、或者发生异常时终止播放 [_audioController stopPlayer]; } if (event == TTS_EVENT_ERROR) { const char *errmsg = [_nui nui_tts_get_param: "error_msg"]; TLog(@"tts get errmsg:%s", errmsg); } } }
onNuiTtsUserdataCallback:语音合成数据回调,将回调中的合成数据写入播放器进行播放。
- (void)onNuiTtsUserdataCallback:(char*)info infoLen:(int)info_len buffer:(char*)buffer len:(int)len taskId:(char*)task_id { TLog(@"onNuiTtsUserdataCallback info ..."); if (info_len > 0) { TLog(@"onNuiTtsUserdataCallback info text %s. index %d.", info, info_len); } if (len > 0) { // 旧版本示例工程提供的播放器,仅做参考,可根据自身业务重写播放器。 // [_voicePlayer write:(char*)buffer Length:(unsigned int)len]; // 新版本示例工程提供了新的播放器,仅做参考,可根据自身业务重写播放器。 [_audioController write:(char*)buffer Length:(unsigned int)len]; } }