小程序版

更新时间：2024-12-26

1. 接入方法

1.1 确保小程序已拥有 live-player(实时播放音视频流)组件权限

申请并开通流媒体播放权限（符合开通【 live-player｜live-pusher 】的资质文件）：

1.2 购买组件并申请数字人小程序插件权限

在平台购买云渲染组件商品并绑定到应用，操作说明参考：平台操作指引
申请数字人插件接入权限，插件申请地址：https://mp.weixin.qq.com/wxopen/pluginbasicprofile?action=intro&appid=wx702e7833d34cdcc5&token=&lang=zh_CN
联系对接人审批数字人插件权限申请

1.3 引入插件代码包

使用者要在 app.json 中声明需要使用的插件

{
    "plugins": {
        "digitalhumanlib": {
            "version": "2.0.1",
            "provider": "wx702e7833d34cdcc5"
        }
    }
}

1.4 使用插件

和使用普通自定义组件的方式相仿，在 json 文件定义需要引入的自定义组件时，使用 plugin:// 协议指明插件的引用名和自定义组件名

{
    "usingComponents": {
        "digitalhuman-view": "plugin://digitalhumanlib/digitalHumanView"
    }
}

1.5 业务中使用

在.wxml中引入自定义组件

<digitalhuman-view
    id="digitalhuman"
    class="digitalhuman-view-container"
    settings="{{digitalHumanSetting}}"
    bind:onMessage="onMessage"
    bind:onStateChange="onStateChange"
/>

2. demo的使用

下载小程序demo, 下载地址：**https://sdk-demo.bj.bcebos.com/demo_digitalHuman.zip
使用微信开发者工具导入该文件，进行真机预览**

3. settings数字人配置项

3.1 基础配置

参数名	类型	必填	默认值	备注
token	string	是	–	平台购买交互组件商品，参考：平台操作指南,生成鉴权凭证:生成方法查阅接口通用说明(token=Authorization)的鉴权参数生成部分
figureId	string	是	_	人像id，详细枚举参考：3D数字人列表、2D精品数字人、2D小样本数字人
mode	string	是	-	用于针对特定应用场景快速批量设置关联配置的默认值，设置后关联配置无需填写，枚举类型：noAudio：无拾音模式
resolutionWidth	number	否	720	数字人展示的宽度，必须是偶数，最小400，最大不超过 1080x1920、1920x1080，宽高比例需要和人像比例一致
resolutionHeight	number	否	1280	数字人展示的高度，必须是偶数，最小400，最大不超过 1080x1920、1920x1080，宽高比例需要和人像比例一致
backgroundImageUrl	string	否	-	设置数字人背景图片，推荐使用 BOS（百度对象存储服务）地址，其他地址可能会因为网络原因加载图片失败导致会话打开失败
x	number	否	0	水平位置，范围-0.5到0.5，取0居中，越大数字人越靠右
y	number	否	0	竖直位置，范围-1到1，取0为默认位置，越大数字人越靠上
z	number	否	1	缩放比例，范围0.5到1.5，取1原始比例，越小数字人越小。注意：y的取值是按数字人原始大小上下移动，当z取值大于1，既放大数字人时，y的值可以小于-1以实现更大范围下移。
cameraId	int	否	-	数字人预设机位 ID，控制数字人的位置和大小，建议使用和视频分辨率比例一致的机位：详细枚举参考：3D数字人列表、2D精品数字人、2D小样本数字人

3.2 高级配置项

参数名	类型	默认值	备注
ttsPer	string	-	音色发音人ID，可用发音人列表参考：公共音色库，或使用克隆音色
ttsPitch	number	5	音调，5是正常值，0-15的取值范围，越大声音越尖，默认值5 （字面量需要是整数）
ttsSpeed	number	5	语速，5是正常值，0-15的取值范围。越大语速越快，默认值5 （字面量需要是整数）
cp-autoAnimoji	Boolean	false	是否开启自动添加数字人动作，只支持高精3D/2D人像
cp-inactiveDisconnectSec	int	180	长时间无交互（交互指发送 text render 让数字人播报）的断连提醒，单位秒，0 表示不开启。达到阈值时，服务端会发送 TIMEOUT_EXIT 提醒消息，页面在收到该消息时需销毁组件，避免数字人渲染资源浪费，目前数字人后端服务不会主动断开。
cp-preAlertSec	int	10	在开启长时间无交互断连提醒，且即将到达断连阈值时，后端会先发送一条 DISCONNECT_ALERT 预提醒消息，页面收到消息可以弹窗提醒用户。该参数用于设置断连前多少秒发送该提醒，比如无交互超时参数 cp-inactiveDisconnectSec 设置为 180（3 分钟），提醒参数 cp-preAlertSec 设置为 10 （秒），则在用户最后一次交互后的 2 分 50 秒时会收到后端发送的 DISCONNECT_ALERT 提醒消息，在 3 分钟时收到 TIMEOUT_EXIT 断连消息。

4. 驱动与回调

4.1 文本驱动

代码样例详见handleSend

<digitalhuman-view
    id="digitalhuman"
    class="digitalhuman-view-container"
    settings="{{digitalHumanSetting}}"
    bind:onMessage="onMessage"
    bind:onStateChange="onStateChange"
/>

Page({
    data: {
        digitalHumanSetting: {...}
    },
    onLoad(options) {
        const digitalhuman = this.selectComponent('#digitalhuman');    }
    
    handleSend(){
       // 文本驱动数字人
       this.digitalhuman.textRender({body: '这里是驱动数字人的文本', requestId: this.digitalhuman.getUuid()})
    }
});

requestId说明：可自定义构造requestId进行驱动数字人，驱动的回调消息会沿用自定义构造的requestId。

body说明：

TEXT_RENDER时body的可选值	备注
你好，我是数字人	播报内容
	打断当前数字人播报
`<say-as type="telephone">110</say-as>`	指定读法的高级播报内容，支持在线SSML（语音合成标记语言）
开始说话停止5s后继续说话	支持播报中停顿
	音频播放
这段话不允许打断这段话不允许打断这段话不允许打断	播报不受打断的内容，后续textRender会在上句播报完成后开始播报，但仍可被interrupt标签打断

4.2 文本驱动回调

代码样例详见onMessage

<digitalhuman-view
    id="digitalhuman"
    class="digitalhuman-view-container"
    settings="{{digitalHumanSetting}}"
    bind:onMessage="onMessage"
    bind:onStateChange="onStateChange"
/>

Page({
    data: {
        digitalHumanSetting: {...}
    },
    onLoad(options) {
        const digitalhuman = this.selectComponent('#digitalhuman');
    }
   onMessage(message = {}) {
        const data = message.detail;
        const {action} = data;
        switch (action) {
          case 'RENDER_START':
            console.log('数字人驱动开始');
            break;
          case 'RENDER_COMPLETED':
            console.log('数字人驱动完成');
            break;
          default:
            break;
        }
    },
});

4.3 状态监听回调

代码样例详见onMessage

<digitalhuman-view
    id="digitalhuman"
    class="digitalhuman-view-container"
    settings="{{digitalHumanSetting}}"
    bind:onMessage="onMessage"
    bind:onStateChange="onStateChange"
/>

Page({
    data: {
        digitalHumanSetting: {...}
    },
    onLoad(options) {
        const digitalhuman = this.selectComponent('#digitalhuman');
    }
    onStateChange(e) {
        const {type, error = {}, loading} = e.detail;
        const {action, message, code} = error;
        if (type === 'INIT') {
            // 通过监听 INIT 消息，来实现数字人的开场白设置
            this.digitalhuman.textRender('数字人初始化完成，这是数字人的开场白播报，可以自行修改开场白内容');
        }
        if (type === 'ERROR'){
            console.log(type, error);
        }
    },
});

4.3.1 数字人初始化正常状态

type	说明
INIT	数字人第一次初始化完成
LOADING	数字人视频流是否加载中{type: 'LOADING', loading: true/false}

4.3.2 数字人初始化异常状态

type	code	错误信息	说明
ERROR	1001	服务器内部错误
ERROR	1002	APP已失效
ERROR	1003	APP token已过期
ERROR	1004	目前线上用户较多，请您稍后再试	app 会话路数已经达到上限
ERROR	1005	授权信息不存在	figureId未授权不可用
ERROR	1009	App token非法	token填写错误
ERROR	1010	App key非法
ERROR	1011	裁剪参数非法	仅2D数字人存在
ERROR	1012	参数不能为空
ERROR	1014	分辨率/编码参数不合法
ERROR	1015	无效的媒体信息	例如：传递的RTMP参数无效
ERROR	1202	正在连接或已连接
ERROR	1204	解析请求失败
ERROR	1206	读取json失败
ERROR	2001	Fail to establish	建立渲染任务失败
ERROR	3001	目前线上用户较多，请您稍后再试	系统渲染资源不足导致
ERROR	23002	ttsPer非法	ttsPer音色不在公共音色库中

4.3.3 数字人驱动异常状态

type	code	错误信息	说明
ERROR	-1	body 非法	不支持 body 传& < >等特殊字符
ERROR	1013	body 非法
ERROR	1208	body格式非法	body格式错误
ERROR	1201	操作尚未支持

5. 数字人状态和指令控制

方法	备注
VERSION	获取当前sdk版本号
destroy	销毁数字人组件
pause(boolean)	true: 暂停近端视频流false: 播放并同步远端视频流
mediaMute(boolean)	true: 静音数字人false: 取消静音数字人

6. 常见问题

6.1 视频播放组件无权限，报错 operateLivePlayer:fail no permission

原生插件集成依赖：能够申请并开通流媒体播放权限（符合开通【 live-player｜live-pusher 】的资质文件）：

需要在小程序开发管理上，申请并开启 live-player的权限

6.2 无法开通live-player权限如何在小程序中使用

可以使用web页面封装【云渲染组件】，再使用webview的方式进行嵌入小程序；

webview方式相较与原生小程序插件形式有如下特点

webview会自动铺满整个小程序页面。
个人类型的小程序暂不支持使用
webview所支持api相较小程序插件有所不同，需要用户按需进行技术选型，相关参考微信技术文档：https://developers.weixin.qq.com/miniprogram/dev/component/web-view.html
webview兼容性同【云渲染组件】兼容性，存在无交互不可有声播放等问题，参见【云渲染组件】常见问题解决方案

webview接入方式，添加校验文件具体步骤如下

登录微信公众平台，进入小程序管理页面。
在“开发设置”中找到“业务域名”部分，点击“修改”按钮。
在“合法域名”列表中，点击“添加”按钮，输入iframe域名：https://open.xiling.baidu.com和业务域名
选择文件验证或DNS验证，按照提示完成验证。

一旦验证成功，https://open.xiling.baidu.com 和业务域名就会出现在“合法域名”列表中，你的小程序就可以通过这个域名访问服务器了。
联系对接人员，将校验文件发给对接人员，待检验文件成功放到数字人服务的根目录上后，webview接入准备工作完成

H5版

端渲染交互

百度智能云

曦灵数字人开放平台