3D数字人交互SDK-iOS版
更新时间：2024-12-12
简介
本文说明SDK的集成使用以及接口调用方式
整体架构&功能简介
- 客户端或页面集成SDK加载形象包，本地驱动渲染数字人。
- 支持音频和文本驱动:
- 音频可以使用真人音频或自行接入的第三方的TTS音频。
- 文本驱动SDK内部会调用数字人开放平台TTS服务驱动数字人，
- 文本驱动可以开启智能动作开关，实现数字人根据播报语义智能触发动作。
- 3D数字人形象包可切换机位，动作驱动，切换配饰服装（如有多套配置服装）
一、SDK接入和集成
1.1、将下载得到的framework文件和a文件在framework，librarties，and embedded content中进行导入
1.2、添加以下系统库
| Framework | 描述 |
|---|---|
| libc++.tbd | 提供对C/C++特性支持 |
| GLKit.framework | GL支持 |
| OpenGLES.framework | OpenGL 支持 |
| libicucore.tbd | |
| libz.tbd | 提供gzip支持 |
| libnetwork.tbd | 提供网络支持 |
1.3、在工程中配置如下参数
1.3.1、将 API Validation 取消选中
1.3.2、将other Linker Flages 设置为-ObjC
1.3.3、库引用地址
1.4、资源文件导入
1.4.1、license 文件资源导入（必须作为资源导入， 否则授权则不成功， 如果有新的授权文件则更新到license 文件夹下）
license需要额外申请， 提供Bundle Identifier 给到百度方，用于生成license文件
1.4.2、人像资源导入 (可自定义地址， 初始化时传入自定义地址即可， 地址获取至case目录)
二、SDK 调用以及API 说明
2.1、初始化
- (instancetype)initWithFrame:(CGRect)frame andARVSSettings:(DigitalHumanARVSSettings *)settings| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| frame | 数字人view显示坐标 | 是 | |
| settings | 加载ar数字人、babel、render 的配置信息 | 是 | 参数参考DigitalHumanARVSSettings 模块 |
DigitalHumanARVSSettings 参数
| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| appId | 应用的appID | 是 | 咨询百度支持人员 |
| appKey | 应用的appKey | 是 | |
| arParams | ar数字人配置参数 | 是 | 参考arParams 参数 |
| renderEngine | render播报配置参数 | 是 | 参考renderEngine 参数 |
arParams 参数
| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| modelPath | 模型地址 | 是 | |
| figure | 人像名称 | 是 | |
| camera | 机位 | 是 | |
| deviceType | 渲染等级 | 是 | 低端机：iPhone_Low 中端机：iPhone_Middle 高端机：iPhone_Heavy |
| licenseName | 授权文件名称 | 是 | 咨询百度支持人员 |
| licenseKey | 授权key | 是 |
renderEngine参数
| 参数 | 含义 | 备注 |
|---|---|---|
| renderToken | token | |
| characterlmage | 人像id | 用于标识人像，目前只用于开启智能动作功能 |
| autoAnimoji | 是否开启智能动作匹配 | YES: 开启 NO: 不开启 开启条件： autoAnimoji = YES 且characterlmage 为有效值则打开， 否则无法生效 |
| renderUrl | 合成url | 默认： wss://persona.baidu.com:8850/v1/arkit/render |
| ttsParams | tts参数 | 示例：{@"person":@5116,@"pitch":@5,@"speed":@5} |
调用示例
_cloudView = [[DigitalHumanARVSView alloc] initWithFrame:self.view.frame andARVSSettings:_dhSettings];
_cloudView.delegate = self;
_cloudView.backgroundColor = [UIColor clearColor]; // 初始化时设置背景为透明
[self.view addSubview:_cloudView];2.2、获取版本信息
+ (NSString *)version调用示例
[DigitalHumanARVSView version]2.3、数字人暂停
- (void)pause调用示例
[_cloudView pause];2.4、数字人继续
- (void)resume调用示例
[_cloudView resume];2.5、render播放相关接口
2.5.1、文本播报
- (void)sendTextRender:(NSString *)message| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| message | 播报文本 | 是 |
调用示例
[_cloudView sendTextRender:text];2.5.2、音频文件播报
- (void)sendAudioStream:(NSString *)input| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| input | 音频文件路径 | 是 |
调用示例
NSString *micPath = [[NSBundle mainBundle] pathForResource:@"asr_0501-iPhone13Promax-lijiaqi_kongtiao_mic_01" ofType:@"pcm" inDirectory:@"dhResources"];
[_cloudView sendAudioStream:micPath];2.6、打断
- (void)interrupt调用示例
[_cloudView interrupt];2.7、播放动作
- (void) playAnim:(NSString *) animName| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| animName | 播报动作ID | 是 |
调用示例
[_cloudView playAnim:_animationList[_animationIndex]];2.8、设置idle
- (void) setArIdle调用示例
[_cloudView setArIdle];2.9、更新render参数
-(void) updateRenderParams:(RenderEngine *) renderEngine;| 参数 | 含义 | 是否必填 | 备注 |
|---|---|---|---|
| renderEngine | 合成相关参数 | 是 |
renderEngine
| 参数 | 含义 | 备注 |
|---|---|---|
| renderToken | token | 不更新token 项无需调用 |
| ttsParams | tts参数 | 不更新tts 项无需调用，调用示例：{@"person":@5116,@"pitch":@5,@"speed":@5} |
调用示例
RenderEngine * renderEngine = self.dhSettings.renderEngine;
// 更新token
renderEngine.renderToken = [DHLanAES generateAuthorizationTokenWithAppId:self.dhSettings.appId appKey:self.dhSettings.appKey expirationTime:1];
// 更新tts参数
NSDictionary *tts = @{
@"person":@5116,
@"pitch":@5,
@"speed":@5,
};
renderEngine.ttsParams = tts;
[_cloudView updateRenderParams:renderEngine];2.10、切换机位
- (void)changeCamera:(NSString*) camParam| 参数 | 是否必填 | 含义 |
|---|---|---|
| camParam | 是 | 机位ID |
调用示例
[_cloudView changeCamera:_cameraData[0]];2.11、销毁
- (void)destroy调用示例
[_cloudView destroy];2.12、DigitalHumanARVSDelegate
/**
数字人sdk状态变化回调
@param event 状态名称
@param data 根据状态的不同，绑定的其他数据
*/
@required
- (void)onDigitalHumanARVSEventUpdate:(DigitalHumanARVSEvent)event obj:(id __nullable)data;| 参数 | 含义 | 备注 |
|---|---|---|
| onDigitalHumanARVSEventUpdate | sdk状态变化回调 | 参数参考DigitalHumanARVSEvent 模块 |
DigitalHumanARVSEvent 参数
| 参数 | 含义 | 备注 |
|---|---|---|
| DH_ARVS_LIB_OPEN | 初始化完成 | |
| DH_ARVS_LIB_ERROR | 数字人执行错误 | |
| DH_ARVS_LIB_LICENSE | 授权状态 | 数字人授权状态 |
| DH_ARVS_LIB_AR_RENDERING | 获取数字人 | 后台返回数字人页面触发 |
| DH_ARVS_LIB_AR_PAUSE | 暂停数字人 | 退出至后台触发 |
| DH_ARVS_LIB_CLOSED | 关闭销毁数字人 | |
| DH_ARVS_LIB_AVATAR_ANIMATION | 获取可执行动作列表 |
2.13、DigitalHumanARVSRenderDelegate
/**
播报状态变化回调
@param event 状态名称
@param data 根据状态的不同，绑定的其他数据
*/
@protocol DigitalHumanARVSRenderDelegate <NSObject>
-(void)onDigitalHumanRenderEventUpdate:(QueryEventStatus) event obj:(id __nullable)data;QueryEventStatus 参数
| 参数 | 含义 | 备注 |
|---|---|---|
| RENDER_START | 开始播放 | |
| RENDER_INTERRUPT | 播放打断 | |
| RENDER_FINISH | 播放结束 | |
| RENDER_ERROR | 播放错误 | |
| SUBTITLE | 播报内容 | 音频驱动无播报内容， 忽略此字段 |