iOS SDK

前提条件

• 使用SDK前，请先阅读接口说明，详情请参见接口说明。

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

• 已获取Access Token，详情请参见获取Token概述。

下载安装

1. 下载SDK和示例代码。

   重要

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

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

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

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

2. 解压ZIP包。

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

3. 使用Xcode打开此工程，工程中提供了参考代码以及一些直接可使用的工具类，例如音频播放录制和文件操作，您可以直接复制源码到您的实际工程进行使用。其中实时转写示例代码为SpeechTranscriberViewController。替换Appkey和Token后可直接运行。

SDK关键接口

• nui_initialize：初始化SDK。

  /**
   * 初始化SDK，SDK为单例，请先释放后再次进行初始化。请勿在UI线程调用，可能引起阻塞。
   * @param parameters: 初始化参数，参见接口说明文档：https://help.aliyun.com/zh/isi/developer-reference/overview-4
   * @param level: log打印级别，值越小打印越多
   * @param save_log: 是否保存log为文件，存储目录为parameter中的debug_path字段值。注意，log文件无上限，请注意持续存储导致磁盘存满。
   * @return 参见错误码
   */
  -(NuiResultCode) nui_initialize:(const char *)parameters
                         logLevel:(NuiSdkLogLevel)level
                          saveLog:(BOOL)save_log;

• nui_set_params：以JSON格式设置SDK参数。

  /**
   * 以JSON格式设置参数
   * @param params: 参数信息请参见接口说明文档：https://help.aliyun.com/zh/isi/developer-reference/overview-4
   * @return 参见错误码
   */
  -(NuiResultCode) nui_set_params:(const char *)params;

• nui_dialog_start：开始识别。

  /**
   * 开始识别
   * @param vad_mode: 多种模式，对于识别场景，请使用P2T
   * @param dialog_params: 设置识别参数，可不设置，可参考接口文档：https://help.aliyun.com/zh/isi/developer-reference/overview-4
   * @return 参见错误码
   */
  -(NuiResultCode) nui_dialog_start:(NuiVadMode)vad_mode
                        dialogParam:(const char *)dialog_params;

• nui_dialog_cancel：结束识别。

  /**
   * 结束识别，调用该接口后，服务端将返回最终识别结果并结束任务
   * @param force: 是否强制结束而忽略最终结果，false表示停止但是等待完整结果返回
   * @return 参见错误码
   */
  -(NuiResultCode) nui_dialog_cancel:(BOOL)force;

• nui_release：释放SDK。

  /**
   * 释放SDK资源
   * @return 参见错误码
   */
  -(NuiResultCode) nui_release;

• nui_get_version：获得当前SDK版本信息。

  /**
   * 获得当前SDK版本信息
   * @return 字符串形式的SDK版本信息
   */
  -(const char*) nui_get_version;

• nui_get_all_response：获得当前事件回调的完整信息。

  /**
   * 获得当前事件回调的完整信息
   * @return json字符串形式的完整事件信息
   */
  -(const char*) nui_get_all_response;

• NeoNuiSdkDelegate

  onNuiEventCallback：SDK事件回调。

  /**
   * SDK主要事件回调
   * @param event: 回调事件，参见如下事件列表
   * @param dialog: 会话编号，暂不使用
   * @param wuw: 语音唤醒功能使用（暂不支持）
   * @param asr_result: 语音识别结果
   * @param finish: 本轮识别是否结束标志
   * @param resultCode: 参见错误码，在出现EVENT_ASR_ERROR事件时有效
   */
  -(void) onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                      dialog:(long)dialog
                   kwsResult:(const char *)wuw
                   asrResult:(const char *)asr_result
                    ifFinish:(BOOL)finish
                     retCode:(int)code;

  NuiCallbackEvent事件列表：

  名称	说明
  EVENT_VAD_START	检测到人声起点.
  EVENT_VAD_END	检测到人声尾点。
  EVENT_ASR_PARTIAL_RESULT	语音识别中间结果。
  EVENT_ASR_RESULT	语音识别最终结果。
  EVENT_ASR_ERROR	根据错误码信息判断出错原因。
  EVENT_MIC_EEROR	录音错误，表示SDK连续2秒未收到任何音频，可检查录音系统是否正常。
  EVENT_SENTENCE_START	实时语音识别事件，检测到一句话开始。
  EVENT_SENTENCE_END	实时语音识别事件，检测一句话结束，返回一句的完整结果。
  EVENT_SENTENCE_SEMANTICS	暂不使用。
  EVENT_TRANSCRIBER_COMPLETE	停止语音识别后上报。

  onNuiNeedAudioData：获取音频。

  /**
   * 开始识别时，此回调被连续调用，App需要在回调中进行语音数据填充
   * @param audioData:  填充语音的存储区
   * @param len: 需要填充语音的字节数
   * @return 实际填充的字节数
   */
  -(int) onNuiNeedAudioData:(char *)audioData length:(int)len;

  onNuiAudioStateChanged：根据音频状态进行录音功能的开关。

  /**
   * 当start/stop/cancel等接口调用时，SDK通过此回调通知App进行录音的开关操作
   * @param state：录音需要的状态（打开/关闭）
   */
  -(void) onNuiAudioStateChanged:(NuiAudioState)state;

  onNuiRmsChanged：音频能量事件。

  /**
   * SDK主要事件回调
   * @param rms: 语音能量值，范围为-160至0
   */
  -(void) onNuiRmsChanged:(float) rms;

调用步骤

1. 初始化SDK、录音实例。

2. 根据业务需求配置参数。

3. 调用nui_dialog_start开始识别。

4. 根据音频状态回调onNuiAudioStateChanged，打开录音机。

5. 在onNuiNeedAudioData回调中提供录音数据。

6. 在EVENT_ASR_PARTIAL_RESULT和EVENT_SENTENCE_END事件回调中获取识别结果。

7. 调用nui_dialog_cancel结束识别。

8. 结束调用，使用nui_release接口释放SDK资源。

代码示例

NUI SDK初始化

BOOL save_log = NO;
NSString * initParam = [self genInitParams];
[_nui nui_initialize:[initParam UTF8String] logLevel:LOG_LEVEL_VERBOSE saveLog:save_log];

其中，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 *ticketJsonDict = [NSMutableDictionary dictionary];

    //获取账号访问凭证：
    //  getTicket为示例工程中提供了多种可能的方式，请选择适合自身业务的安全方式
    //
    //注意:
    //  语音交互服务需要先准备好账号，并开通相关服务。具体步骤请查看：
    //    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:ticketJsonDict Type:get_token_from_server_for_online_features];
    if ([ticketJsonDict objectForKey:@"token"] != nil) {
        NSString *tokenValue = [ticketJsonDict objectForKey:@"token"];
        if ([tokenValue length] == 0) {
            TLog(@"The 'token' key exists but the value is empty.");
        }
    } else {
        TLog(@"The 'token' key does not exist.");
    }

    [ticketJsonDict setObject:@"wss://nls-gateway.cn-shanghai.aliyuncs.com:443/ws/v1" forKey:@"url"]; // 默认

    //工作目录路径，SDK从该路径读取配置文件
    [ticketJsonDict setObject:bundlePath forKey:@"workspace"]; // 必填
    //当初始化SDK时的save_log参数取值为true时，该参数生效。表示是否保存音频debug，该数据保存在debug目录中，需要确保debug_path有效可写
    [ticketJsonDict setObject:save_wav ? @"true" : @"false" forKey:@"save_wav"];
    //debug目录，当初始化SDK时的save_log参数取值为true时，该目录用于保存中间音频文件
    [ticketJsonDict setObject:debug_path forKey:@"debug_path"];

    //FullCloud = 1 // 在线实时语音识别可以选这个
    [ticketJsonDict setObject:@"1" forKey:@"service_mode"]; // 必填

    NSString *id_string = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
    TLog(@"id: %s", [id_string UTF8String]);
    [ticketJsonDict setObject:id_string forKey:@"device_id"]; // 必填, 推荐填入具有唯一性的id, 方便定位问题

    NSData *data = [NSJSONSerialization dataWithJSONObject:ticketJsonDict options:NSJSONWritingPrettyPrinted error:nil];
    NSString * jsonStr = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding];
    return jsonStr;
}

参数设置

以JSON字符串形式进行设置。

-(NSString*) genParams {
    NSMutableDictionary *nls_config = [NSMutableDictionary dictionary];
    [nls_config setValue:@YES forKey:@"enable_intermediate_result"]; // 必填
    //参数可根据实际业务进行配置
    //接口说明可见: https://help.aliyun.com/document_detail/173528.html
    //查看 2.开始识别

    //[nls_config setValue:@"<更新token>" forKey:@"token"];
    //[nls_config setValue:@YES forKey:@"enable_punctuation_prediction"];
    //[nls_config setValue:@YES forKey:@"enable_inverse_text_normalization"];
    //[nls_config setValue:@YES forKey:@"enable_voice_detection"];
    //[nls_config setValue:@10000 forKey:@"max_start_silence"];
    //[nls_config setValue:@800 forKey:@"max_end_silence"];
    //[nls_config setValue:@800 forKey:@"max_sentence_silence"];
    //[nls_config setValue:@NO forKey:@"enable_words"];
    //[nls_config setValue:@16000 forKey:@"sample_rate"];
    //[nls_config setValue:@"opus" forKey:@"sr_format"];

    NSMutableDictionary *dictM = [NSMutableDictionary dictionary];
    [dictM setObject:nls_config forKey:@"nls_config"];
    [dictM setValue:@(SERVICE_TYPE_SPEECH_TRANSCRIBER) forKey:@"service_type"]; // 必填

    //如果有HttpDns则可进行设置
    //[dictM setObject:[_utils getDirectIp] forKey:@"direct_ip"];
    
    /*若文档中不包含某些参数，但是此功能支持这个参数，可以用如下万能接口设置参数*/
    //NSMutableDictionary *extend_config = [NSMutableDictionary dictionary];
    //[extend_config setValue:@YES forKey:@"custom_test"];
    //[dictM setObject:extend_config forKey:@"extend_config"];
    
    NSData *data = [NSJSONSerialization dataWithJSONObject:dictM options:NSJSONWritingPrettyPrinted error:nil];
    NSString * jsonStr = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding];
    return jsonStr;
}

NSString * parameters = [self genParams];
[_nui nui_set_params:[parameters UTF8String]];

开始识别

通过nui_dialog_start接口开启监听。

-(NSString*) genDialogParams {
    NSMutableDictionary *dialog_params = [NSMutableDictionary dictionary];
    // 运行过程中可以在nui_dialog_start时更新临时参数，尤其是更新过期token
    // 注意: 若下一轮对话不再设置参数，则继续使用初始化时传入的参数
    //[dialog_params setValue:@"" forKey:@"app_key"];
    //[dialog_params setValue:@"" forKey:@"token"];
    
    NSData *data = [NSJSONSerialization dataWithJSONObject:dialog_params options:NSJSONWritingPrettyPrinted error:nil];
    NSString * jsonStr = [[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding];
    return jsonStr;
}

//若需要修改token等参数, 可详见genDialogParams()
NSString * parameters = [self genDialogParams];
//若要使用VAD模式，则需要设置nls_config参数启动在线VAD模式(见genParams())
[_nui nui_dialog_start:MODE_P2T dialogParam:[parameters UTF8String]];

回调处理

• onNuiAudioStateChanged：录音状态回调，SDK内部维护录音状态，调用时根据该状态的回调进行录音机的开关操作。

  -(void)onNuiAudioStateChanged:(NuiAudioState)state{
      TLog(@"onNuiAudioStateChanged state=%u", state);
      if (state == STATE_CLOSE || state == STATE_PAUSE) {
          // 旧版本示例工程提供的录音模块，仅做参考，可根据自身业务重写录音模块。
          // [_voiceRecorder stop:YES];
  
          // 新版本示例工程提供了新的录音模块，仅做参考，可根据自身业务重写录音模块。
          [_audioController stopRecorder:NO];
      } else if (state == STATE_OPEN){
          self.recordedVoiceData = [NSMutableData data];
          // 旧版本示例工程提供的录音模块，仅做参考，可根据自身业务重写录音模块。
          // [_voiceRecorder start];
  
          // 新版本示例工程提供了新的录音模块，仅做参考，可根据自身业务重写录音模块。
          [_audioController startRecorder];
      }
  }

• onNuiNeedAudioData：录音数据回调，在该回调中填充录音数据。

  -(int)onNuiNeedAudioData:(char *)audioData length:(int)len {
      static int emptyCount = 0;
      @autoreleasepool {
          @synchronized(_recordedVoiceData){
              if (_recordedVoiceData.length > 0) {
                  int recorder_len = 0;
                  if (_recordedVoiceData.length > len)
                      recorder_len = len;
                  else
                      recorder_len = _recordedVoiceData.length;
                  NSData *tempData = [_recordedVoiceData subdataWithRange:NSMakeRange(0, recorder_len)];
                  [tempData getBytes:audioData length:recorder_len];
                  tempData = nil;
                  NSInteger remainLength = _recordedVoiceData.length - recorder_len;
                  NSRange range = NSMakeRange(recorder_len, remainLength);
                  [_recordedVoiceData setData:[_recordedVoiceData subdataWithRange:range]];
                  emptyCount = 0;
                  return recorder_len;
              } else {
                  if (emptyCount++ >= 50) {
                      TLog(@"_recordedVoiceData length = %lu! empty 50times.", (unsigned long)_recordedVoiceData.length);
                      emptyCount = 0;
                  }
                  return 0;
              }
  
          }
      }
      return 0;
  }

• onNuiEventCallback：NUI SDK事件回调，请勿在事件回调中调用SDK的接口，可能引起死锁。

  -(void)onNuiEventCallback:(NuiCallbackEvent)nuiEvent
                     dialog:(long)dialog
                  kwsResult:(const char *)wuw
                  asrResult:(const char *)asr_result
                   ifFinish:(bool)finish
                    retCode:(int)code {
      TLog(@"onNuiEventCallback event %d finish %d", nuiEvent, finish);
      if (nuiEvent == EVENT_ASR_PARTIAL_RESULT || nuiEvent == EVENT_SENTENCE_END) {
          // asr_result在此包含task_id，task_id有助于排查问题，请用户进行记录保存。
          TLog(@"ASR RESULT %s finish %d", asr_result, finish);
          NSString *result = [NSString stringWithUTF8String:asr_result];
      } else if (nuiEvent == EVENT_ASR_ERROR) {
          // asr_result在EVENT_ASR_ERROR中为错误信息，搭配错误码code和其中的task_id更易排查问题，请用户进行记录保存。
          TLog(@"EVENT_ASR_ERROR error[%d], error mesg[%s]", code, asr_result);
  
          // 可通过nui_get_all_response获得完整的信息
          const char *response = [_nui nui_get_all_response];
          if (response != NULL) {
              TLog(@"GET ALL RESPONSE: %s", response);
          }
      } else if (nuiEvent == EVENT_MIC_ERROR) {
          TLog(@"MIC ERROR");
          // 旧版本示例工程提供的录音模块，仅做参考，可根据自身业务重写录音模块。
          // [_voiceRecorder stop:YES];
          // [_voiceRecorder start];
  
          // 新版本示例工程提供了新的录音模块，仅做参考，可根据自身业务重写录音模块。
          [_audioController stopRecorder:NO];
          [_audioController startRecorder];
      }
  
      //finish 为真（可能是发生错误，也可能是完成识别）表示一次任务生命周期结束，可以开始新的识别
      if (finish) {
      }
      
      return;
  }

结束识别

[_nui nui_dialog_cancel:NO];