系统要求
系统版本需要 iOS 11+。
SDK 接入方式
1. 下载并解压 iOS SDK 压缩包，其中 ivhsdk.framework 为数智人端渲染 framework 包，将其放到项目目录下。
2. 在项目的 'Frameworks, Libraries, and Embedded Content' 中添加 ivhsdk.framework。
3. 将需要加载的模型资产包放入 ivhsdk.framework/Data/Raw 目录。
初始化伪代码示例：
- (void)initSDK{SDKOptions* options = [[SDKOptions alloc] init];// options.xxx = xxxUnityFramework* ufw = [IvhLibAPI Init:options];// unity is not initializedif (![self.ufw appController]){// You must call this before running Unity in order for CrashReporter to work properly.[self.ufw setExecuteHeader: &_mh_execute_header];}// 注册实现 UnityFrameworkListener protocol 的对象[ufw registerFrameworkListener: frameworkListener];// 注册实现 IvhCallbacksProtocol protocol 的对象[IvhLibAPI RegisterAPIforIvhCallbacks: ivhCallbacks];// 启动，传入相关应用启动参数[ufw runEmbeddedWithArgc: gArgc argv: gArgv appLaunchOpts: appLaunchOpts];// set quit handler to change default behavior of exit app[ufw appController].quitHandler = ^(){ NSLog(@"AppController.quitHandler called"); };}
初始化接口
初始化接口中可以定义模型资源加载方式、动画控制器属性、apaas对话服务配置。
其中部分配置可以打包到模型资产包中，初始化时无需传入，若传入，则会覆盖模型资产包中的配置。
可以通过 IvhLibAPI 的类方法 Init 来初始化 SDK。
+(UnityFramework*) Init:(SDKOptions*) options;
自定义模型初始化时，首先需要从平台下载模型资源包，放到 ivhsdk.framework/Data/Raw 目录下。一般情况下，模型资产包中会附带部分默认的初始化参数，传入未定义的参数即可。一次典型的平台下载模型资源包初始化代码逻辑：
SDKOptions* options = [[SDKOptions alloc] init];options.ApaasOptions.AppKey = @"your appkey";options.ApaasOptions.AccessToken = @"your accesstoken";options.LoadModelOptions.LoadFromRemote = false;options.LoadModelOptions.ModelURI = @"ailing.assetsbundle";options.LoadModelOptions.ModelObjName = @"ailing";options.LoadModelOptions.GameObjectName = @"ailing";UnityFramework* ufw = [IvhLibAPI Init:options];
参数
参数名称 | 类型 | 描述 |
options | SDKOptions | SDK 初始化参数 |
SDKOptions 描述
参数名称 | 类型 | 描述 |
LoadModelOptions | LoadModelOptions | 模型加载参数 |
AnimationOptions | AnimationOptions | 动画控制参数 |
ApaasOptions | ApaasOptions | 对话接口参数 |
LoadModelOptions 描述
参数名称 | 类型 | 描述 |
CustomModel | BOOL | 是否自定义模型，规范详见第三小节 |
LoadFromRemote | BOOL | 是否从远程加载模型资源 |
ModelURI | NSString | 模型资源地址，可以是本地路径或者URL |
ModelObjName | NSString | 资源包中的模型名称 |
GameObjectName | NSString | 模型加载到场景中后的命名，默认为模型名称 |
HeadObjName | NSString | 模型中带BS参数的头部节点路径。若不传递，则使用资源包中配置好的路径。 如："mod/mod_head" |
AnimationOptions 描述
参数名称 | 类型 | 描述 |
IdelActions | NSArray | 等待动作名称列表，设置后，当无其它动作指令时，模型将随机播放列表中的动作 |
BlendshapeAttributes | NSArray | 口型参数的BS属性列表。需要按照对话服务返回的口型参数的属性进行对应，并保证顺序（注1）。 |
注1：BS属性参考苹果arkit52维标准绑定，并返回了其中36个属性的值，参考地址：https://developer.apple.com/documentation/arkit/arfaceanchor/blendshapelocation
["mouthLowerDownRight","mouthRollLower","cheekSquintRight","mouthStretchRight","mouthSmileLeft","mouthDimpleRight","noseSneerRight","jawOpen","mouthPucker","mouthFunnel","mouthStretchLeft","cheekSquintLeft","mouthPressRight","mouthDimpleLeft","cheekPuff","mouthClose","mouthPressLeft","jawRight","mouthUpperUpLeft","mouthLowerDownLeft","mouthLeft","mouthShrugUpper","mouthFrownLeft","mouthFrownRight","mouthRight","noseSneerLeft","mouthShrugLower","mouthUpperUpRight","mouthRollUpper","jawForward","jawLeft","mouthSmileRight"]
如果模型资产的BS参数名和此处一致，则直接传入此数组即可，否则需要将对应位置的属性名替换为模型的BS属性名。
例如模型的 mouthRollLower 属性名实际实现的是 mouthRollLower1，则需要将上面数组中的 mouthRollLower 替换为 mouthRollLower1，然后传入参数。
ApaasOptions描述
参数名称 | 类型 | 描述 |
Url | NSString | apaas平台的url |
Path | NSString | apaas接口的path |
AppKey | NSString | 数智人接入的appKey，从平台获取 |
AccessToken | NSString | 数智人接入的accessToken，从平台获取 |
VirtualmanKey | NSString | 数智人的virtualmanKey，从平台获取 |
描述
该接口执行 SDK 的初始化工作，包括模型资源的读取、动画管理器的配置、对话服务客户端的配置等。
初始化回调
初始化工作完成后，才可以调用 动画播放、播报/对话、语音识别等接口，初始化完成之前，调用其它接口将无效。
如果要在初始化完毕后立即执行播报/对话，可以通过监听SDK的完成事件来等待初始化完成，或者协程等待初始化完成。
通过监听回调等待初始化完成：
@interface IvhCallbacks : NSObject<IvhCallbacksProtocol>@end@implementation IvhCallbacks// other callbacks ···- (void)onSDKReady{NSLog(@"=== onSDKReady ===");}- (void)onSDKInitFail:(NSString *)message{NSLog(@"%@", [@" === onSDKInitFail ===: " stringByAppendingString: message]);}// other callbacks ···@endIvhCallbacks* callbacks = [[IvhCallbacks alloc] init];[IvhLibAPI RegisterAPIforIvhCallbacks:callbacks];
动画播放接口
播放动画
可以通过 IvhLibAPI 的类方法 PlayAnimation 来播放动画。
+(void) PlayAnimation:(NSString*)name;
参数
参数名称 | 类型 | 描述 |
name | NSString | 需要播放的动画名称 |
描述
传入的动画名称必须是数智人支持的动作名，详见3.2-模型资产打包规范。
停止播放动画
可以通过 IvhLibAPI 的类方法 StopAnimation 来播放动画。
+(void) StopAnimation;
描述
停止播放当前的动画，并清空所有已添加的动画序列。
动画事件回调
可以通过 IvhSDKCallback 绑定动画播放相关回调事件。
@interface IvhCallbacks : NSObject<IvhCallbacksProtocol>@end@implementation IvhCallbacks// other callbacks ···- (void)onPlayAnimation:(NSString *)name{NSLog(@"%@", [@" === onPlayAnimation ===: " stringByAppendingString: name]);}- (void)onEndAnimation:(NSString *)name{NSLog(@"%@", [@" === onEndAnimation ===: " stringByAppendingString: name]);}// other callbacks ···@endIvhCallbacks* callbacks = [[IvhCallbacks alloc] init];[IvhLibAPI RegisterAPIforIvhCallbacks:callbacks];
对话交互接口
对话/播报接口
可以通过 IvhLibAPI 的类方法 Play 来发起对话 / 播报。
+(void) Play: (NSString*) text PlayOptions: (PlayOptions*) options;
参数
参数名称 | 类型 | 描述 |
text | NSString | 对话输入/语音播报的文本内容 |
options | PlayOptions | 对话/播报选项 |
PlayOptions 描述
参数名称 | 类型 | 描述 |
IsDialog | BOOL | 是否对话，为 true 时 text 作为对话输入，false 时 text 作为语音播报的文本输入 |
ChatRoundId | NSString | 对话轮次id，长度大于等于10的随机字符串即可，标识多次Dialog请求为同一次会话。 当希望开启新一轮对话时，传入新的 chatRoundId 即可。 |
描述
当 IsDialog 为 true 时，数字人将播报text中对应文本的应答内容。当 IsDialog 为 false 时，数智人将语音播报 text 中的文本，并播放语音对应的口型动画。含交互数智人平台上配置的停顿、动作、多音字等播报表现。
打断播报接口
可以通过 IvhLibAPI 的类方法 Stop 来发起对话 / 播报。
+(void) Stop;
描述
调用此接口后，将停止播报音频，并清空口型动画，同时停止人物动作的播放。
播报事件回调
获取对话结果
@interface IvhCallbacks : NSObject<IvhCallbacksProtocol>@end@implementation IvhCallbacks// other callbacks ···- (void)onChatResponse:(ChatRsp *)chatRsp{NSLog(@"%@", [@" === onChatResponse ===: " stringByAppendingString: [chatRsp toJSONString]]);}- (void)onChatError:(NSString *)message{NSLog(@"%@", [@" === onChatError ===: " stringByAppendingString: message]);}// other callbacks ···@endIvhCallbacks* callbacks = [[IvhCallbacks alloc] init];[IvhLibAPI RegisterAPIforIvhCallbacks:callbacks];
ChatRsp 描述
参数名称 | 类型 | 描述 |
ChatRoundId | NSString | 对话轮次 id |
ReplyDisplay | NSString | 用于展示在端上的内容，含富文本标签 |
InteractionType | NSString | 特殊消息类型（见注①说明 ） |
InteractionContent | NSString | 特殊消息内容，用于下发弹窗、图片等非文本类的特殊消息。 |
Uninterrupt | BOOL | 当前播报句是否可打断 |
Muted | BOOL | 播报当前句时是否关闭收音 |
播报进度
@interface IvhCallbacks : NSObject<IvhCallbacksProtocol>@end@implementation IvhCallbacks// other callbacks ···- (void)onStartPlay{NSLog(@"=== onStartPlay ===");}- (void)onEndPlay{NSLog(@"=== onEndPlay ===");}// other callbacks ···@endIvhCallbacks* callbacks = [[IvhCallbacks alloc] init];[IvhLibAPI RegisterAPIforIvhCallbacks:callbacks];
语音识别接口说明
设置语音识别鉴权信息
+(void) InitAsr:(AsrCredential*) options;
参数
参数名称 | 类型 | 描述 |
options | AsrCredential | 最大录音长度，单位为秒。 |
AsrCredential描述
参数名称 | 类型 | 描述 |
AppId | NSString | 腾讯云语音识别的 AppId。 |
SecretId | NSString | 腾讯云语音识别的 SecretId，或者临时鉴权的 TmpSecretId。 |
SecretKey | NSString | 腾讯云语音识别的 SecretKey，或者临时鉴权的 TmpSecretKey。 |
Token | NSString | 腾讯云语音识别临时鉴权的 Token。 |
描述
注意，需要在 SDKReadyCallback 回调函数触发后再调用此方法，在 SDKReadyCallback 之前调用将无法设置鉴权信息。
调用此方法后，才可以开始语音识别，否则会因为无语音识别鉴权信息而无法开启识别。如果设置的是临时鉴权信息，需要传入对应的 token。临时鉴权信息过期时间为30分钟，注意在30分钟内更新临时鉴权信息，否则语音识别接口将无法使用。
开始语音识别
+(void) StartRecord:(int)limitSec;
参数
参数名称 | 类型 | 描述 |
limitSec | int | 最大录音长度，单位为秒。 |
描述
调用此方法后，sdk将异步启动语音识别，不能在调用后立即将交互设置为录音中，需要等待录音开始的回调。
结束语音识别
+(void) StopRecord;
描述
调用此方法后，将停止语音识别，并触发结束录音事件，带回识别结果。
语音识别回调
可以通过 IvhSDKCallback 绑定语音识别相关回调事件。
注意：语音识别回调会在其它线程中被调用，若要执行 UI 线程中的操作，请在回调中使用 handler 处理。
@interface IvhCallbacks : NSObject<IvhCallbacksProtocol>@end@implementation IvhCallbacks// other callbacks ···- (void)onAsrStart:(NSString *)sessionId{NSLog(@"%@", [@" === onAsrStart ===: " stringByAppendingString: sessionId]);}- (void)onAsrEnd:(NSString *)sessionId Result:(NSString *)result{NSLog(@"%@", [@" === onAsrEnd ===: " stringByAppendingString: result]);}- (void)onAsrError:(NSString *)sessionId Message:(NSString *)message{NSLog(@"%@", [@" === onAsrEnd ===: " stringByAppendingString: message]);}// other callbacks ···@endIvhCallbacks* callbacks = [[IvhCallbacks alloc] init];[IvhLibAPI RegisterAPIforIvhCallbacks:callbacks];
抗锯齿设置接口
+(void) SetMSAA:(int)antiAliasing;
参数
参数名称 | 类型 | 描述 |
antiAliasing | int | 抗锯齿级别，从低到高可设置为 2 / 4 / 8 |
描述
在低 DPI 的设备上使用时，数智人渲染可能出现比较明显的锯齿，可以尝试设置抗锯齿参数来优化。启用抗锯齿后，根据抗锯齿级别的不同会带来一定的性能损耗。
注意：需要在 SDK的初始化回调（ SDKReadyCallback）触发后，才可以调用此函数，否则会因 SDK 未初始化完成而调用无效。
