SparkOS iOS SDK接入文档

# SparkOS iOS SDK接入文档

## 1. 兼容性说明

|类别|兼容范围|
|---|---|
|系统|支持arm64架构，兼容iOS9.0及以上版本|
|开发环境|建议使用Xcode进行开发|
|开发语言|Object C|
## 2. 准备工作

### 2.1 平台配置

在集成开发SDK前，需要开发者在AIUI交互平台上创建应用及申请授权，设置好相关的配置，如个性化数据、技能、情景以及自然语言理解(即语义是使用交互大模型还是AIUI)等，并获取AIUI交互协议文档。

### 2.2 授权申请

接入SDK前，请先联系项目侧开通使用交互大模型需要用到的各种云端授权，防止出现运行时的授权报错。

除了云端功能需要授权外，如果需要使用到多模交互、音频编解码等功能，也需要额外再开通客户端侧的离线能力授权，具体可以联系SDK技术支持人工协助。

### 2.3 功能介绍

SDK内部包含多个独立子能力，通过编排协议按业务流程编排形成AIUI交互流程，预置子能力如下：

|子能力|说明|
|---|---|
|录音器、播放器|用于音频采集和播放|
|视频录像|用于采集视频/图片|
|VAD/IAT/NLP/TTS|在线AIUI能力，进行人声检测/语音识别/语义理解/合成|
|AudioCodec|音频编解码，用于将采集的音频编码、服务下发的音频解码(需要开通授权)|
|ImageConvert|图片编码，用于将采集的视频/图片编码(需要开通授权)|
## 3. SDK组成

SDK zip包解压后文件结构：

```Plain Text

iOS SDK集成文档.docx  // AIUI SDK能力集成指南
Demo                  // 使用Demo，集成前通过Demo了解调用原理
ReleaseNote.txt       // SDK版本日志
framework
├── XRTCSDK.framework          // 虚拟人视频拉流依赖组件
├── SocketRocket.framework     // 虚拟人视频拉流依赖组件
├── ecaf3bdb6_v1002_aee.framework  // 图片编码依赖组件
├── ec6e6c04b_v1006_aee.framework  // 音频编解码依赖组件
├── CocoaLumberjack.framework  // 虚拟人视频拉流依赖组件
└── AIKIT.framework            // 核心框架依赖
```

## 4. SDK工程配置

### 4.1 导入SDK库

AIUI iOS SDK核心代码库由AIUI.framework和其他若干依赖库组成。

在引入工程中时，在工程的General的frameworks,Libraries,and Embedded Content中使用**Embedded & sign**。

## 5. 接口调用流程

### 5.1 初始化

使用AIUI能力前，需获取授权应用信息(appId、apiKey、apiSecret)，联系项目经理获取；SDK仅需初始化一次。

#### 初始化示例代码

```Objective-C

static NSString* APPID = @"XXXXX";
static NSString* APIKEY = @"XXXXX";
static NSString* APISECRET = @"XXXXX";

AppHelper* _mHelper = [[AppHelper alloc] init:^(AiHelperMaker * _Nonnull maker) {
    maker.appId(APPID).apiKey(APIKEY).apiSecret(APISECRET);
}];
```

#### 初始化参数说明

|参数|类型|是否必填|说明|
|---|---|---|---|
|appID|NSString|是|AIUI交互平台创建应用后生成的应用ID|
|apiKey|NSString|是|AIUI交互平台创建应用后生成的唯一应用标识|
|apiSecret|NSString|是|AIUI交互平台创建应用后生成的唯一应用秘钥|
#### 初始化返回值

0：初始化成功；非0：初始化失败，参考错误码章节查询原因。

#### 代理协议（AppHelperDelegate）

```Objective-C

/// 能力回调代理
@protocol AppHelperDelegate<NSObject>

/// 能力结果回调
/// - Parameters:
///   - ability: 能力id
///   - handleId: 会话句柄
///   - data: 能力输出数据
///   - context: 用户自定义标识
- (void)onResult:(NSString *)ability
        handleId:(NSInteger)handleId
       outputData:(NSArray<AIKITDataModel *> *)data
           usrCtx:(AIKITCtxContent *)context;

/// 能力进度回调
/// - Parameters:
///   - ability: 能力id
///   - handleId: 会话句柄
///   - event: 进度事件 ( 0 : UnKnown, 1 : Start, 2 : End, 3 : Timeout, 4 : Progress)
///   - data: 进度数据
///   - context: 用户标识
- (void)onEvent:(NSString *)ability
        handleId:(NSInteger)handleId
           event:(NSInteger)event
       eventData:(NSArray<AIKITDataModel *> *)data
           usrCtx:(AIKITCtxContent *)context;

/// 能力错误回调
/// - Parameters:
///   - ability: 能力id
///   - handleId: 会话句柄
///   - error: 错误信息
///   - context: 用户表示
- (void)onError:(NSString*)ability
        handleId:(NSInteger)handleId
           error:(AIKITError*)error
           usrCtx:(AIKITCtxContent*)context;

@end
```

#### 回调接口说明

##### onResult

AIUI处理结果从onResult返回，通过key区分结果类型。

|变量名|类型|是否必填|说明|
|---|---|---|---|
|ability|NSString|是|能力标识ID|
|handleID|NSInteger|是|会话ID|
|context|id|否|用户自定义标识|
|data|NSArray|是|能力执行结果|
##### AIKITDataModel结构说明

|变量名|类型|是否必填|说明|
|---|---|---|---|
|key|NSString|是|输出数据名称|
|type|enum|是|输出数据类型，0=音频；1=文本；2=图片；3=视频；5=个性化数据|
|value|byte[]|否|字节数组类型输出数据|
|varType|enum|是|输出数据变量类型，0=字节数组；1=整型；2=实型；3=布尔型|
|len|NSInteger|是|输出数据长度|
##### 常见key取值

|key取值|含义|说明|
|---|---|---|
|iat|识别结果数据|唤醒后用户指令的语音识别结果|
|nlp|语义数据|AIUI根据识别结果返回的语义数据|
|tts|未解码的合成音频数据|云端合成的原始音频数据|
|audio|解码后的合成音频数据|解码完成的合成音频数据|
##### onEvent

会话事件信息回调，事件枚举：0=未知；1=开始；2=结束；3=超时；4=进度；15=连接建立；19=连接断开。

##### onError

会话错误信息回调，错误码分SDK错误码(18开头)和云端错误码。

### 5.2 请求调用

#### 5.2.1 场景切换

通过`AppHelper.start`启动会话，`AppHelper.stop`结束会话，支持4类场景：

- 语音输入，语音输出

- 语音输入，视频输出（虚拟人）

- 视频输入，语音输出（多模）

- 视频输入，视频输出（虚拟人+多模）

```Objective-C

typedef enum : NSUInteger {
    AUDIO_TO_AUDIO,
    AUDIO_TO_VIDEO,
    VIDEO_TO_AUDIO,
    VIDEO_TO_VIDEO
} AppMode;

@interface AppHelper
- (int)start:(AppMode)mode params:(AppParams*)params;
- (int)stop;
@end
```

#### 5.2.2 参数配置

会话参数通过`AppParams`构建，支持发音人、虚拟人形象、设备唯一码等配置。

```Objective-C

@interface AppParams : AIKITParameters
- (AppParams*)isDuplex:(bool)duplex;
- (AppParams*)vcn:(NSString*)value;
- (AppParams*)avatarId:(NSString*)value;
- (AppParams*)avatarSize:(NSInteger)width height:(NSInteger)height;
- (AppParams*)mode:(NSUInteger)value;
- (AppParams*)uid:(NSString*)value;
- (AppParams*)scene:(NSString*)value;
- (AppParams*)cameraView:(UIView *)cameraView;
- (AppParams*)imageSrcFormat:(NSString*)srcFormat;
- (AppParams*)imageDetectBlurry:(bool)detectBlurry;
- (AppParams*)imageSaveResult:(bool)saveResult;
- (AppParams*)imageSaveResultPath:(NSString*)savePath;
- (AIKITParameters*)build;
@end

- (AppParams*)buildParam {
    AppParams* param = [[AppParams alloc] init];
    param.header().addInt(@"demo_ver", 10241024);
    [param uid:UID];
    [param scene:@"SOSAPP"];
    [param vcn:self.vcn];
    // [param avatarId:@"avatar_wmy001"];
    // [param avatarSize:512 height:512];
    if (self.cameraSelected) {
        [param cameraView:self.fullScreenView];
    }
    return param;
}

int ret = [_mHelper start:gMode params:[self buildParam]];
```

#### 5.2.3 自定义IO

自行实现音频/视频输入输出接口，通过`AppHelper.registerIODevice`注册。

```Objective-C

@protocol IDeviceIO
- (instancetype)init;
- (void)release;
@end

@protocol IAudioWriter
- (void)write:(NSData*)data;
@end

@protocol IDeviceAudioInput <IDeviceIO>
- (void)on:(id<IAudioWriter>*)writer;
- (void)off;
@end

@protocol IDeviceAudioOutput <IDeviceIO>
- (void)on;
- (void)off;
- (void)pause;
- (void)resume;
- (void)data:(NSData*)data;
- (bool)isPlaying;
@end

typedef enum : NSUInteger {
    DEFAULT_CAMERA,
    FRONT_CAMERA,
    REAR_CAMERA
} VideoDataSource;

@protocol IImageWriter
- (void)write:(NSData*)data width:(int)width height:(int)height;
@end

@protocol IDeviceVideoInput <IDeviceIO>
- (void)on:(id<IAudioWriter>*)writer;
- (void)off;
- (void)switchTo:(VideoDataSource)source;
@end
```

#### 5.2.4 交互协议

请求协议由header、parameter、payload三部分构成，SDK自动封装请求，详细协议参考SparkOS API接入文档。

```JSON

{
    "header": {
        "uid": "39769795890",
        "scene": "mainCbm"
    },
    "parameter": {
        "iat": {
            "iat": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "json"
            }
        },
        "nlp": {
            "nlp": {
                "encoding": "utf8",
                "compress": "raw",
                "format": "json"
            }
        },
        "tts": {
            "tts": {
                "encoding": "speex-wb",
                "sample_rate": 16000,
                "channels": 1,
                "bit_depth": 16,
                "frame_size": 0
            }
        }
    },
    "payload": {
        "audio": {
            "encoding": "speex-wb",
            "sample_rate": 16000,
            "channels": 1,
            "bit_depth": 16,
            "status": 0,
            "seq": 0,
            "audio": "",
            "frame_size": 0
        },
        "text": {
            "encoding": "utf8",
            "compress": "raw",
            "format": "plain",
            "status": 2,
            "seq": 0,
            "text": ""
        }
    }
}
```

### 5.3 逆初始化

不再使用能力时，释放资源：

```Objective-C

[AppHelper unInit];
```

## 6. 高级功能

### 6.1 SDK初始化高级配置

|参数名|类型|说明|是否必填|
|---|---|---|---|
|workDir|NSString|SDK工作目录，需要读写权限；iOS平台一般用不上|否|
|authType|NSInteger|端能力授权方式，0=设备级授权，1=应用级授权|否|
|resDir|NSString|资源存放目录，需要读写权限；iOS平台一般用不上|否|
|licenseFile|NSString|授权文件目录；设备不支持联网时传入做离线授权，iOS一般用不上|否|
|cfgPath|NSString|配置文件路径；需配置文件时传入|否|
### 6.2 动态配置访问url

```Objective-C

static NSString * URL = @"{\"aiui_spark\":\"ws://sos-gray.cn-huabei-1.xf-yun.com/v3/sos\",\"aiui_image\":\"ws://sos-gray.cn-huabei-1.xf-yun.com/v3/sos-image\"}";
[AiHelper setConfig:@"HostUrl" value:URL];
```

### 6.3 下发服务侧sid结果

开启后结果携带header数据，包含sid：

```Objective-C

[AiHelper setConfig:@"ResultFormat" value:@"{\"aiui_spark\":1}"];
```

header数据格式：

```JSON

{
    "code": 0,
    "message": "success",
    "cid": "cidxxxxxxxxxxxxxxxxx",
    "sid": "xxx@xxxxxxxxxxxxxxxx"
}
```

### 6.4 获取会话结束标识

通过key+status判断会话状态：

|key|status含义|获取方式|
|---|---|---|
|iat|0=第一帧，1=中间，2=最后一帧|onResult中key=iat取status|
|nlp|0=第一帧，1=中间，2=最后一帧|onResult中key=nlp取status|
|tts|0=第一帧，1=中间，2=最后一帧|onResult中key=tts取status|
|header|0=第一帧，1=中间，2=最后一帧|解析header的status字段|
### 6.5 日志配置

```Objective-C

[AiHelper setLogInfo:AIKITLogOff mode:0 path:@"xxxxx"];
```

|参数|类型|说明|是否必填|
|---|---|---|---|
|level|LogLvl|日志等级：AIKITLogVerbose/AIKITLogDebug/AIKITLogWarn/AIKITLogInfo/AIKITLogError/AIKITLogFatal|否|
|mode|NSInteger|输出模式：0=stdout，1=logcat，2=file|否|
|path|NSString|文件输出时的路径（含文件名）|否|
## 7. 错误码

### 7.1 SDK错误码

参见AIKit错误码描述

### 7.2 云端错误码

参见云端错误码查询