iOS SDK

前提条件

• 阅读接口说明，详情请参见接口说明。

• 已获取项目Appkey，详情请参见创建项目。

• 已获取AccessKey ID和 AccessKey Secret，详情请参见开通服务。

下载安装

1. 下载SDK。

   重要

   下载后在样例初始化代码中替换您的阿里云账号信息、Appkey才可运行。为方便集成，2.5.14版本后iOS接口使用纯Object-C接口，不再使用C++混合接口。

   对象	说明
   SDK名称	智能语音交互移动端SDK
   开发者	阿里云计算有限公司
   SDK版本	2.6.3-028
   SDK更新时间	2024-12-23
   SDK整合包大小	40.5MB
   SDK整合包MD5值	d0a09153acb51f86334e1a8d43edffc5
   隐私政策	智能语音交互产品隐私政策
   SDK整合包下载	下载iOS SDK

   类别	兼容范围
   系统	最低支持iOS9
   架构	arm64，x86_64

   此SDK还包含如下功能，若未支持您想要的功能，请前往对应文档获取SDK。

   功能	是否支持
   一句话识别	是
   实时语音识别	是
   语音合成	是
   实时长文本语音合成	是
   流式文本语音合成	是
   离线语音合成	是
   录音文件识别极速版	是
   唤醒及命令词	否
   听悟实时推流	是

2. 下载语音包，详情请参见接口说明中的语音包列表。

   重要

   SDK和语音包是完全独立的，下载SDK后并不能直接使用，需要下载语音包，并设置语音包存放路径。

3. 解压ZIP包。

   将ZIP包中的nuisdk.framework添加到您的工程中，并在工程Build Phases的Link Binary With Libraries中添加nuisdk.framework。

4. 使用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	语音合成发生错误。

调用步骤

1. 初始化SDK和播放组件。

2. 根据业务需要设置参数。

3. 调用nui_tts_play进行播放。

4. 在合成数据回调中，将数据写入播放器进行播放，建议使用流式播放。

5. 收到语音合成结束的回调。

代码示例

1. 语音合成初始化。

   // 一次初始化成功，可以反复调用合成和参数设置接口，不需要频繁初始化和释放，减少耗时
   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;
   }

2. 根据需求设置参数。

   //加载语音包：已购买的语音包，可以放在任意位置，以aijia为例，该语音包位于Documents/voices/下，设置命令为“Documents/voices/aijia”
   NSString *cmd = [NSString stringWithFormat:@"%@/aijia", myvoicedir];
   [self.nui nui_tts_set_param:"extend_font_name" value:[cmd UTF8String]];

3. 启动语音合成。

   //建议同一时间单示例启动一个task进行语音合成，单实例多task易出异常。
   [self.nui nui_tts_play:"1" taskId:"" text:[content UTF8String]];

4. 取消语音合成

   //如果上个任务没有合成完毕，手动取消，开始合成新的任务。
   //建议同一时间单示例启动一个task进行语音合成，单实例多task易在cancel时出异常。
   [self.nui nui_tts_cancel:NULL];

5. 回调处理。

   • 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];
         }
     }

常见问题