iOS SDK

前提条件

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

• 准备好项目Appkey，详情请参见创建项目。

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

下载安装

1. 下载SDK和示例代码。

   重要

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

2. 解压ZIP包，将zip包中的nuisdk.framework添加到您的工程中，并在工程Build Phases的Link Binary With Libraries中添加nuisdk.framework。请确保在编译配置的General > Frameworks, Libraries, and Embedded Content中配置nuisdk.framework为Embed & Sign。

3. 使用Xcode打开此工程，工程中提供了参考代码以及一些直接可使用的工具类，例如音频播放录制和文件操作，您可以直接复制源码到您的实际工程进行使用。其中录音文件识别极速版示例代码在FileTranscriberViewController类中。

SDK关键接口

• nui_initialize：初始化SDK。

    /**
     * 初始化SDK，SDK为单例，请先释放后再次进行初始化。请勿在UI线程调用，可能引起阻塞。
     * @param parameters: 初始化参数，参见接口说明文档
     * @param level: log打印级别，值越小打印越多
     * @param save_log: 是否保存log为文件，存储目录为parameter中的debug_path字段值
     * @return 参见错误码
     */
  -(NuiResultCode) nui_initialize:(const char *)parameters
                         logLevel:(NuiSdkLogLevel)level
                          saveLog:(BOOL)save_log;

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

  /**
   * 以JSON格式设置参数
   * @param params: 参数信息请参见接口说明文档
   * @return 参见错误码
   */
  -(NuiResultCode) nui_set_params:(const char *)params;

• nui_file_trans_start：发起文件识别请求。

  /**
   * 开始识别
   * @param params：设置识别参数，参考接口说明。
   * @param task_id：开始转写的任务ID，SDK生成随机字符串。
   * @return：参见错误码。
   */
  NuiResultCode nui_file_trans_start(const char *params, char *task_id);

• nui_file_trans_cancel：取消正在工作的识别任务。

  /**
   * 结束识别
   * @param task_id：需要结束的转写任务ID。
   * @return：参见错误码
   */                    
  NuiResultCode nui_file_trans_cancel(const char *task_id);

• nui_release：释放SDK。

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

• NeoNuiSdkDelegate事件代理

  onFileTransEventCallback：SDK转写事件回调。

  /**
   * SDK主要事件回调
   * @param nuiEvent: 回调事件，参见如下事件列表
   * @param asrResult: 语音识别结果
   * @param taskId: 一个任务对应的唯一id
   * @param ifFinish: 本轮识别是否结束标志
   * @param retCode: 参见错误码，在出现EVENT_ASR_ERROR事件时有效
   */
  -(void) onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                         asrResult:(const char *)asr_result
                            taskId:(const char *)task_id
                          ifFinish:(BOOL)finish
                           retCode:(int)code;

  NuiCallbackEvent事件列表：

  名称	说明
  EVENT_FILE_TRANS_CONNECTED	连接文件转写服务成功
  EVENT_FILE_TRANS_UPLOADED	上传文件成功
  EVENT_FILE_TRANS_RESULT	识别最终结果
  EVENT_ASR_ERROR	根据错误码信息判断出错原因

调用步骤

1. 初始化SDK。

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

3. 调用nui_file_trans_start开始识别。

4. 在EVENT_FILE_TRANS_RESULT事件中获取最终识别结果。

5. 结束调用，使用release接口释放SDK资源。

代码示例

NUI SDK初始化

//请注意此处的参数配置，其中账号相关需要按照genInitParams的说明填入后才可访问服务
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 *id_string = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
    NSString *debug_path = [_utils createDir];
    TLog(@"id: %s", [id_string UTF8String]);

    //获取token方式：
    NSMutableDictionary *dictM = [NSMutableDictionary dictionary];

    //账号和项目创建
    //  ak_id ak_secret app_key如何获得,请查看https://help.aliyun.com/document_detail/72138.html
    [dictM setObject:@"<您申请创建的app_key>" forKey:@"app_key"]; // 必填

    //方法1：
    //  首先ak_id ak_secret app_key如何获得,请查看https://help.aliyun.com/document_detail/72138.html
    //  然后请看 https://help.aliyun.com/document_detail/466615.html 使用其中方案一获取临时凭证
    //  此方案简介: 远端服务器使用以下方法获得有效时限的临时凭证, 下发给移动端进行使用, 保证账号信息ak_id和ak_secret不被泄露
    //  获得Token方法(运行在APP服务端): https://help.aliyun.com/document_detail/450255.html?spm=a2c4g.72153.0.0.79176297EyBj4k
    [dictM setObject:@"<服务器生成的具有时效性的临时凭证>" forKey:@"token"]; // 必填

    //方法2：
    //  STS获取临时凭证方法暂不支持

    //方法3：（强烈不推荐，存在阿里云账号泄露风险）
    //  参考NuiSdkUtils类的实现在端上访问阿里云Token服务获取SDK进行获取。请勿将ak/sk存在本地或端侧环境。
    //  此方法优点: 端侧获得Token, 无需搭建APP服务器。
    //  此方法缺点: 端侧获得ak/sk账号信息, 极易泄露。
    //    [_utils getTicket:dictM];

    //工作目录路径，SDK从该路径读取配置文件
    [dictM setObject:bundlePath forKey:@"workspace"]; // 必填
    //debug目录。当初始化SDK时的save_log参数取值为true时，该目录用于保存中间音频文件
    [dictM setObject:debug_path forKey:@"debug_path"];
    [dictM setObject:id_string forKey:@"device_id"]; // 必填, 推荐填入具有唯一性的id, 方便定位问题
    [dictM setObject:@"https://nls-gateway.cn-shanghai.aliyuncs.com/stream/v1/FlashRecognizer" forKey:@"url"]; // 必填

    //FullMix = 0   // 选用此模式开启本地功能并需要进行鉴权注册
    //FullCloud = 1 // 在线实时语音识别可以选这个
    //FullLocal = 2 // 选用此模式开启本地功能并需要进行鉴权注册
    //AsrMix = 3    // 选用此模式开启本地功能并需要进行鉴权注册
    //AsrCloud = 4  // 在线一句话识别可以选这个
    //AsrLocal = 5  // 选用此模式开启本地功能并需要进行鉴权注册
    [dictM setObject:@"1" forKey:@"service_mode"]; // 必填

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

开始识别

调用nui_file_trans_start接口开启识别。

char task_id[33] = {0};
[_nui nui_file_trans_start:param:[param_string UTF8String] taskId:task_id];

回调处理

onFileTransEventCallback：文件识别事件回调，请勿在事件回调中调用SDK的接口，可能引起死锁。

-(void)onFileTransEventCallback:(NuiCallbackEvent)nuiEvent
                      asrResult:(const char *)asr_result
                         taskId:(const char *)task_id
                       ifFinish:(bool)finish
                        retCode:(int)code {
    TLog(@"onNuiEventCallback event %d finish %d", nuiEvent, finish);
    if (nuiEvent == EVENT_FILE_TRANS_CONNECTED) {
        [myself showAsrResult:@"连接成功，正在上传..."];
    } else if (nuiEvent == EVENT_FILE_TRANS_UPLOADED) {
        [myself showAsrResult:@"完成上传，正在转写..."];
    } else if (nuiEvent == EVENT_FILE_TRANS_RESULT) {
        NSString *result = [NSString stringWithUTF8String:asr_result];
        [myself showAsrResult:result];
    } else if (nuiEvent == EVENT_ASR_ERROR) {
        TLog(@"EVENT_ASR_ERROR error[%d]", code);
        NSString *result = [NSString stringWithUTF8String:asr_result];
        [myself showAsrResult:result];
    }

    if (finish) {
        // 任务完成
        [myself showStart];
    }
    return;
}      

取消识别

[_nui nui_file_trans_cancel:[task_id UTF8String]];

常见问题