3D数字人交互SDK-H5版
更新时间：2024-12-27
1. 使用流程
1、形象包制作：分为“定制形象”和“公共库形象”两种。
- 定制形象
用户提供设计原画，百度侧根据需求制作3D人物模型，为保证人物模型可以被端渲染SDK驱动使用，3D端渲染人像需要进行适配。预计需要3-4周时间。人像制作过程中允许用户调整和修改，确保人像符合用户需求。
- 公共形象库
人像上新中，敬请期待
形象定制及适配费用相关问题，可咨询：https://cloud.baidu.com/survey/assembly.html
2、SDK调用：
客户端或页面集成SDK加载形象包，本地驱动渲染数字人。
支持音频和文本驱动:
音频可以使用真人音频或自行接入的第三方的TTS音频。
文本驱动SDK内部会调用数字人开放平台TTS服务驱动数字人，
文本驱动可以开启智能动作开关，实现数字人根据播报语义智能触发动作。
3D数字人形象包可切换机位，动作驱动，切换配饰服装（如有多套配置服装）
购买入口：组件商店 （依次购买： 1. 定制服务-语音合成 2. 交互组件-端渲染交互组件-3D数字人）
2. 接入方法
iframe支持在网页内引入其他网页，使用iframe引入WebSdk方式如下：
FAQ: 为什么使用iframe
使用iframe的方式天然的和集成方代码形成隔离，形成单独的进程进行数字人的渲染工作，防范因js单线程设计可能造成的渲染卡顿问题。
<iframe
id="myIframe"
src="https://open.xiling.baidu.com/cloud/client/ar?platform=paas"
allow="autoplay;"
style="height: 400px;width: 400px;"
/>3. demo 使用
3.1 demo说明
此demo分别使用react，vue两种框架。
针对如何初始化数字人，发送消息驱动数字人, 发送流式音频驱动数字人，以及数字人播报的打断，数字人的销毁，动作驱动，机位切换等功能给予了相应的实现。
3.2 demo下载
React版本，下载地址https://sdk-demo.bj.bcebos.com/client-human-react-demo.zip
Vue版本，下载地址https://sdk-demo.bj.bcebos.com/client-human-vue-demo.zip
3.3 demo运行
- 判断环境是否有 node(22 版本以上)和 yarn，如没有则进行 node, yarn 的安装： brew install node; npm install --global yarn (其他安装方式请自行搜索)
- 解压后，进入目录：
- React版本目录名称：client-human-react-demo
- Vue 版本目录名称：client-human-vue-demo
- 命令行执行yarn，安装所需依赖包（根据提示使用对应的 node 版本）
- 搜索“自行填写”关键字，将demo中一些需要自己填写的，如形象包地址、token等变量进行填写
- 文本和音频驱动的token需要自行生成， 注：从应用管理中获取appKey/appId后, 参见token生成文档，生成token。
- 命令行执行npm run dev，启动项目
- 将控制台输出的ip地址，复制到浏览器地址栏进行项目预览
3.4 SDK兼容性
支持机型信息：
- 安卓：支持CPU骁龙730G/骁龙855/联发科天玑900/天玑820 同等性能及以上芯片
- iOS : 支持iPhone8 系统版本13.3以及以上。
支持浏览器类型：
| 机型 | 系统浏览器 | qq浏览器 | 百度浏览器 | 微信内置浏览器 | UC浏览器 |
|---|---|---|---|---|---|
| 华为mate 50 （鸿蒙系统） |
测试版本：15.0.8.301 | 测试版本：15.7.0.0081 64bit | 测测试版本：13.74.0.10 | 测试版本：8.0.53 | 测试版本：V17.2.0.1351 |
| 小米 11pro | 测试版本：18.6.71011 | 测试版本：15.7.2.2041 | 测试版本：13.74.0.10 | 测试版本：8.0.53 | 测试版本：17.1.9.1350 |
| oppo reno6 pro | 测试版本：40.8.29_db2babb | 测试版本：14.9.1.1.1033 64bit | 测试版本：13.53.0.10 | 测试版本：8.0.49 | 测试版本：V16.3.9.1290 |
| iPhone15promax | 测试版本：ios17.5.1 | — | 测试版本：13.73.1.10 | 测试版本：8.0.53 | 测试版本：17.2.0.2476 |
| iPhone12 | 测试版本：ios17.6.1 | — | 测试版本：13.53.5.10 | 测试版本：8.0.48 | 测试版本：17.2.0.2476 |
| iphone xs | 测试版本：ios15.3 | — | 测试版本：13.74.1.10 | 测试版本：8.0.53 | 测试版本：17.1.9.2473 |
| iphone 14pro | 试版本：ios16.3.1 | — | 测试版本：13.74.1.10 | 测试版本：8.0.54 | 测试版本：17.1.9.2476 |
（其余浏览器及上述浏览器低版本可能存在不兼容情况）
4. SDK 的使用
4.1 SDK 驱动原理及工具包的使用
4.1.1 SDK 驱动原理
SDK 的驱动原理是通过业务页面与数字人iframe之间的消息发送和状态监听来实现数字人的初始化，以及数字人状态的监听；
这里我们封装了一个 npm 包来便捷客户进行上述消息的发生和监听，用户只需调用 npm 包提供的方法即可完成数字人的初始化和消息的发送以及回调的监听。
4.1.2 工具包的安装
// npm 方式：
npm i @bddh/starling-dhiframe
// yarn 方式
yarn add @bddh/starling-dhiframe4.1.3 工具包的使用
import {DHIframeV2} from '@bddh/starling-dhiframe';
const dhIframe = new DHIframeV2('iframeId'); // 这里修改成 iframe 的 id属性值
// 模型的初始化
dhIframe.load(...)
// 文本驱动和回调
dhIframe.textRender(...)4.2 SDK初始化以及状态监听
4.2.1 监听 iframe引擎加载完成
dhIframe.registerMessageReceived((data: any) => {
if (data.type === 'state') {
if (data.content.status === 'INIT') {
console.log('引擎初始化完成')
dhIframe.load({
backgroundImageUrl: 'https://digital-human-js-cdn.cdn.bcebos.com/meta_human_editor/20240903202457/digital-human-open-console-web/img/bg1.png',
modelUrl: '定制人像包的zip的cdn地址'
});
}
if (data.content.status === 'AVATAR_LOAD') {
console.log('模型数字人加载完成')
}
if (data.content.status === 'CLOSE') {
console.log('模型数字人销毁完成')
}
}
});4.2.2 status 状态列表
| data.content.status | 含义 | 备注 |
|---|---|---|
| INIT | 引擎初始化完成 | 引擎初始化完成之后，才可以使用dhIframe.load方法加载人像包 |
| ERROR | 启动发生错误 | INIT之前发生ERROR是引擎发生错误INIT之后传入人像包发生错误是人像包加载失败 |
| AVATAR_LOAD | 模型包数字人加载完成 | dhIframe.load完成的状态提示 |
| USER_ACTIVE | 数字人加载时无用户点击交互 | 场景：使用开场白驱动数字人时，通过监听该消息，进行用户交互提醒 |
| CLOSE | 模型包数字人销毁完成 | dhIframe.destroy完成后的状态提示 |
| AUTHENTICATION | 鉴权回调信息 | { code: '错误码' message: '错误信息'} |
鉴权失败code码
| 错误码 | 错误信息 |
|---|---|
| 1001 | 服务器内部错误 |
| 1002 | APP已失效 |
| 1003 | APP token已过期 |
| 1004 | 目前线上用户较多，请您稍后再试或tts字符包配额不足 |
| 1005 | 授权信息不存在 |
| 1008 | App 签名非法 |
| 1009 | App key非法 |
| 1010 | App token非法 |
| 1012 | 参数不能为空 |
| 1202 | 正在连接或已连接 |
| 1204 | 解析请求失败 |
| 1206 | 读取json失败 |
4.2.3 加载人像包
dhIframe.load({
backgroundImageUrl: 'https://digital-human-js-cdn.cdn.bcebos.com/meta_human_editor/20240903202457/digital-human-open-console-web/img/bg1.png',
modelUrl: '定制人像包的zip的文件地址',
cameraId: 'face_cam'
});| 参数 | 必填 | 含义 |
|---|---|---|
| modelUrl | 是 | 模型包文件地址，不支持本地文件地址；开发者向运营人员获取所需人像zip包文件，存储到自有文件服务后填写文件下载 URL。建议使用 CDN 地址以提高加载速度。 |
| backgroundImageUrl | 否 | 人像背景，不填为透明背景，不支持本地文件地址，使用bos或cdn获取url |
| cameraId | 否 | 加载完成人像资源后，人像的初始相机位（全身，半身等），参见人像zip包中config.json文件 |
tip: load方法需要在监听到status为INIT后才可以进行调用
4.3 文本驱动
dhIframe.textRender({
// 购买"定制服务-语音合成 交互组件-端渲染交互组件-3D数字"两个组件组件，为应用绑定组件，获取appKey, appId
// 参见token生产文档（https://cloud.baidu.com/doc/AI_DH/s/Ulywupd35）生成token
token: '填写 appKey, appId 生成的鉴权 token',
text: '使用文本驱动数字人的播报文本',
tts: {
per: 5116,
spd: 5,
pit: 5
}
},
({status, data}) => {
Logger.log('textRender callback:', status, data);
});
);| 参数 | 必填 | 类型 | 含义 |
|---|---|---|---|
| text | 是 | string | 播报文本, 支持在线SSML（语音合成标记语言），不可包含& < >特殊字符 |
| token | 是 | string | 鉴权 token，生产方式参见： 鉴权参数生成指南 |
| tts | 是 | { per: number｜ string; spd: number; pit: number; } | 音色发音人ID，可用发音人列表参考：公共音色库 ，或使用[克隆音色](https://cloud.baidu.com/doc/AI_DH/s/qm1ftwtgispd) 语速 5是正常值，0-15的取值范围。越大语速越快，默认值5 （字面量需要是整数） pit 语调 5是正常值，0-15的取值范围，越大声音越尖，默认值5 （字面量需要是整数） |
| characterImage | 否 | string | 人像id，用于标识人像，从人像包 config.json 中获取。目前只用于开启智能动作功能，参考下面 autoAnimoji 字段说明。 |
| autoAnimoji | 否 | boolean | 是否为本次文本驱动智能匹配动作， 当填写有效 characterImage 且本参数设为 true 时开启。 |
| listener | 否 | {status, data} | staus为驱动回调的状态，staus枚举及含义如下 |
listener中staus枚举及说明
| status | 含义 | data |
|---|---|---|
| RENDER_START | 文本驱动开始的状态回调 | - |
| RENDER_COMPLETED | 文本驱动完成的状态回调 | - |
| RENDER_FINISH | 驱动完成或被打断状态的回调如被打断，则状态从RENDER_START直接变为RENDER_FINISH不存在RENDER_COMPLETED | - |
| RENDER_WARNING | 缺少用户点击交互行为，无法有声播放 | {code: 4000} |
| SUBTITLE | 播报内容 | {content: '当前播报的文本'} |
| RENDER_ERROR | 文本驱动错误 | {code: number}错误码描述如下表 |
RENDER_ERROR中错误码映射表如下：
| code错误码 | 错误信息 | 说明 |
|---|---|---|
| 1604 | characterImage非法 | characterImage填写错误 |
| 1203 | 渲染文本失败 | body参数非法，不支持 body 传& < >等特殊字符 |
| 1208 | 富文本格式非法 | SSML格式错误 |
| 1201 | 操作尚未支持 | -- |
| 23002 | ttsPer非法 | tts ttsPer参数填写非法 |
| 4001 | 文本不能为空 | -- |
token鉴权失败消息回调4.2.2 status中AUTHENTICATION描述
4.4 音频驱动
// 购买"定制服务-语音合成 交互组件-端渲染交互组件-3D数字"两个组件组件，为应用绑定组件，获取appKey, appId
// 参见token生产文档（https://cloud.baidu.com/doc/AI_DH/s/Ulywupd35）生成token
dhIframe.startAudioRender('填写appKey,appId生成的token', ({status, data}) => console.log('驱动回调消息：', status, data));
dhIframe.audioRender(data); //ArrayBuffer音频数据(PCM 编码，16k, 单通道，16bit)
dhIframe.stopAudioRender(); //结束音频渲染| 驱动方法 | 传参 | 备注 |
|---|---|---|
| startAudioRender | (token: string,listener?: (msg) => void) | 开启语音驱动并设置状态回调函数msg枚举详见下表 |
| audioRender | (data: ArrayBuffer) | 传输音频数据(PCM 编码，16k, 单通道，16bit) |
| stopAudioRender | - | 结束语音驱动 |
listener中msg枚举及说明
| status | 含义 | data |
|---|---|---|
| AUDIO_INIT | 音频驱动初始化完成，准备接收数据的状态回调 | - |
| RENDER_COMPLETED | 音频驱动完成的状态回调 | - |
| RENDER_FINISH | 驱动完成，如被打断，则状态从RENDER_START直接变为RENDER_FINISH不存在RENDER_COMPLETED | - |
| RENDER_WARNING | 缺少用户点击交互行为，无法有声播放 | code码为4000 |
| RENDER_ERROR | 音频驱动错误 | errMsg信息 |
4.5 其他驱动指令
// 销毁数字人
dhIframe.destroy();
// 打断数字人播报
dhIframe.interrupt();| 驱动指令 | 传参 | 备注 |
|---|---|---|
| interrupt | - | 打断当前播报内容 |
| destroy | - | 销毁数字人 |
| changeCamera | (cameraId: string;) | 切换机位，参见zip包中config.json文件 |
| animojiRender | (animojiId: string, listener?: (msg) => void) | 切换动作，参见zip包中config.json文件 |
| changeParts | (parts: Array({ id: string; // 资产id type?: string; //资产类型})) | 切换数字人相关配饰，参见zip包中config.json文件例：dhIframe.changeParts([ { type: "hair", id: "coco_02_hair_out" }, { type: "badge", id: "coco_02_badge_out" }]); |
5.常见问题
5.1 本地调试过程中数字人发生形变
数字人销毁，需要通过指令进行，本地热更新时可能触发数字人模型非正常销毁的情况
解决方法：1. 刷新浏览器；2. 正确调用dhIframe.destroy进行销毁数字人