2D数字人交互SDK-Windows版

更新时间：2026-01-27

1、产品介绍

提供端渲染交互Windows-2D小样本数字人，可以通过文本,本地或在线音频数据(PCM,WAV)完成对虚拟人实时驱动。

1.1、适用场景特点

适合windows系统驱动的展示屏，可支持高性能需求场景，人像渲染及唇形推理本地化完成，无需依赖云端持续算力支持；可落地于金融 APP 客服、政务移动端咨询、教育类 APP 伴学等场景；

1.2、核心功能

公共形象租赁：提供半身、全身的2D小样本数字人形象，覆盖多种场景，支持客户快速集成使用；专属形象定制：支持定制专属的2D小样本数字人形象；实时播报渲染：支持数字人实时播报；性能指标：支持英伟达30、40系显卡使用。

1.3 整体架构

架构：

数据流图： 数据流图 1.png

Inference输入输出
输入
输入为16KHz 16位单声道 PCM音频流具体包格式：
|---------header--------|--------------------data--------------------| | flag (1) | index (4) |new_frame_flag(1)| ---------------data (1280) --------------|
输出
输出为16KHz 16位单声道 PCM音频流(与输入格式一致)➕ 指定分辨率和指定颜色空间的原始图像数据
|----audio header----|------audio data------|----new_frame_flag-----|----------------------video data--------------------|

架构分为三层：输入输出层(I/O)，SDK引擎层和资源层(Resource)

输入：SDK内置了一个WebEngine，基于WebKit的渲染引擎，用户使用HTML/Javascript/CSS构建前端展示和交互，启动时WebEngine注入了一个名为desktop2dJava的JavaScript对象作为与Java的通信的接口，通过此接口可以向SDK发送指令，参考使用说明的接口说明部分。

输出：SDK会创建一个面板，将用户配置的元素（视频/人像/图片）渲染到面板中，其中视频元素将循环播放，人像实时渲染到面板的DIGITAL_HUMAN层，同时播放音频。

SDK引擎

引擎主要负责两部分工作：1. 渲染引擎(JavaFX)，2. 驱动引擎（AudioDriver+Inference）。

渲染引擎：提供了基于WebKit的渲染引擎，接受用户传入的指令并转化为Java方法调用。

驱动引擎：将指令转换为驱动人像的音频数据，经过推理程序生成数字人说话的人像，经过播放器(Media-Player)将人像和音频输出到I/O层。

资源层

资源层包括：本地的数字人形象包，本地/在线音频文件，在线的文本转语音服务(TTS)。人像驱动引擎依赖本地的人像资源包，音频驱动依赖音频数据文件或在线TTS服务。

1.4、环境依赖

硬件依赖

型号	推荐版本
CPU	i5-12400F
内存	32G
显卡	nvidia 3060 8G

软件依赖

java 17

2、使用说明

2.1、SDK下载链接

SDK下载地址：https://digital-human-cloud.bj.bcebos.com/open/sdk/2d/baidu_digital_win_sdk_V1.0.0.zip

2.2、SDK的使用说明

下载SDK并解压
申请授权文件
模型初始化
运行样例APP，验证功能完整性
参考样例代码，调用SDK开发自己的数字人应用

2.2.1 下载SDK并解压

下载sdk到本地并解压，解压后由以下几个关键文件（夹）：

文件(夹)	说明
run.sh	启动脚本
setup.sh	预热脚本
app.jar	程序文件
lib/app-shade.jar	程序文件
conf/config.yaml	配置文件
html/index.html	demo样例，内置的展示界面
figures/	人像目录
inference/	程序目录
windows_license_tools/	授权工具
demo/	针对开发者，socket通信demo

2.2.2 申请授权文件

进入windows_license_tools目录，执行LicenseTools.exe 获取设备指纹

将硬件指纹交给数字人运营人员，获取授权文件

得到授权文件后，将授权文件放到inference目录中

2.2.3 模型预热

打开setup.sh或setup.bat，修改licenseKey对应的值为授权文件名称

执行setup.sh 或 setup.bat，启动后日志显示“License Auth Success !”说明授权成功，显示“License Auth ret Failed”则表示授权失败

首次运行需要模型预热，预计10~20分钟，根据硬件配置的高低会有上下波动。日志如下

日志.png

预热成功后，程序会自动退出，在inference目录下生成inference_$datetime.dmp文件说明预热成功。

2.2.4 运行样例APP，验证功能完整性

打开conf/config.yaml，参考文档进行修改，修改完后保存退出，执行run.sh或run.bat
样例.png

界面说明
第一行为控制按钮：

打开屏幕：打开数字人面板
刷新面板：更新面板样式，可通过配置实时更新生效
关闭屏幕：关闭数字人面板
清空日志：清空下方的回显日志

第二行为功能按钮，在打开数字人面板后，可点击下面的按钮测试驱动数字人

本地播报：播放本地pcm或wav
在线播报：播放在线pcm或wav
文本播报：使用tts功能播报文本内容
流式播报：流失播报pcm或wav
打断播报：打断当前播报的内容，清空后续播报，回到聆听状态
暂停播报：暂停当前的播报，回到聆听状态
恢复播报：回复被暂停的播报，回到播报态
插入播报：将一段文本或本地音频，插入到当前的播报中

2.3 接口说明

2.3.1 控制接口：打开面板

接口：window.desktop2dJava.open(jsonObjectStr)

参数	说明
resolution	渲染面板分辨率
figureRequest.figureName	人像名称,figures目录下的资源包名称
layerList	面板素材配置

素材支持图片，视频和数字人，配置说明如下

参数	说明
type	资源类型：IMAGE，VIDEO，DIGITAL_HUMAN
figureRequest.figureName	人像名称
position	资源位置
position.top	距离顶部像素
position.left	距离左边框像素
position.width	资源宽度比例，1.0 为资源默认宽度
position.aspect	aspect = width/height, height为资源高度
source	资源路径（非DIGITAL_HUMAN）,支持在线资源和本地资源，本地资源例(file://E:/1080_1920_4s.mp4)

样例

Plain

1{
2    'resolution': {
3        'width': 1080,
4        'height': 1920
5    },
6    'figureRequest': {
7        'figureName': 'people_dXmLV29Mx6xK2Athwn4eMK'
8    },
9    'layerList': [
10        {
11            'type': 'VIDEO',
12            'position': {
13              'top': 0.0,
14              'left': 0.0,
15              'width': 1.0,
16
17              'aspect': 0.56
18            },
19            'source': {
20              'url': 'https://meta-human-editor-prd.bj.bcebos.com/vis/2d_sdk_demo/1080_1920_4s.mp4'
21            }
22          },
23        {
24            'type': 'DIGITAL_HUMAN',
25            'position': {
26                'top': 0.119922,
27                'left': 0.189583,
28                'width': 0.619444,
29                'aspect': 1.0
30            }
31        },
32        {
33            'type': 'IMAGE',
34            'position': {
35                'top': 0.0,
36                'left': 0.0,
37                'width': 1.0,
38                'aspect': 5.0
39            },
40            'source': {
41                'url': 'https://meta-human-editor-test.cdn.bcebos.com/cea9a767-e17f-4cea-b160-152d0374bb26/material/%E6%9C%80%E6%96%B0logo_%E9%BB%91.png'
42            }
43        }
44}

2.3.2 控制接口：关闭面板

sdk接口：window.desktop2dJava.shutdown()
参数：无

2.3.3 控制接口：刷新面板

说明：更新渲染面板的素材(open接口中的layerList)
接口：window.desktop2dJava.fresh(jsonArrayStr);

参数	说明
type	资源类型：IMAGE，VIDEO，DIGITAL_HUMAN
position	资源位置
position.top	距离顶部像素
position.left	距离左边框像素
position.width	资源宽度比例，1.0 为资源默认宽度
position.aspect	aspect = width/height, height为资源高度
source	资源路径

样例

Plain

1var obj = [
2    {
3        "type": "VIDEO",
4        "position": {
5            "top": 0,
6            "left": 0,
7            "width": 1,
8
9            "aspect": 0.56
10        },
11        "source": {
12            "url": "https://meta-human-editor-prd.bj.bcebos.com/vis/2d_sdk_demo/1080_1920_4s.mp4"
13        }
14    },
15    {
16        "type": "DIGITAL_HUMAN",
17        "position": {
18            "top": 0.119922,
19            "left": 0.189583,
20            "width": 0.619444,
21            "aspect": 1
22        }
23    },
24    {
25        "type": "IMAGE",
26        "position": {
27            "top": 0,
28            "left": 0,
29            "width": 1,
30            "aspect": 5
31        },
32        "source": {
33            "url": "https://meta-human-editor-test.cdn.bcebos.com/cea9a767-e17f-4cea-b160-152d0374bb26/material/%E6%9C%80%E6%96%B0logo_%E9%BB%91.png"
34        }
35    }
36];
37window.desktop2dJava.fresh(JSON.stringify(obj));

2.3.4 本地播放PCM/WAV

命令：localDrive(text);
sdk调用：window.desktop2dJava.localDrive(text);

参数	说明
text	本地pcm或wav文件路径

样例

Plain

1window.desktop2dJava.localDrive("E:\demo\123456789.pcm");

2.3.5 在线播放PCM/WAV

sdk接口：window.desktop2dJava.webDrive(text);

参数	说明
text	在线pcm或wav文件路径

样例

Plain

1window.desktop2dJava.localDrive("https://meta-human-editor-prd.bj.bcebos.com/vis/2d_sdk_demo/987654321.wav");

2.3.6 文本播放

sdk接口：window.desktop2dJava.ttsDrive(text);

参数	说明
text	待播报的字符串

样例

Plain

1window.desktop2dJava.localDrive("这是文本播报1,这是文本播报2,这是文本播报3,这是文本播报4");

2.3.7 流式播放

sdk接口：window.desktop2dJava.streamDrive(text);

参数	说明
text	在线pcm或wav文件路径

样例

Plain

1window.desktop2dJava.streamDrive("https://meta-human-editor-prd.bj.bcebos.com/vis/2d_sdk_demo/987654321.wav");

2.3.8 打断播报

sdk接口：window.desktop2dJava.interrupt();
参数：无
样例

Plain

1window.desktop2dJava.interrupt();

2.3.9 暂停播报

sdk接口：window.desktop2dJava.pause();
参数：无
样例

Plain

1window.desktop2dJava.pause();

2.3.10 恢复播报

sdk接口：window.desktop2dJava.resume();
参数：无
样例

Plain

1window.desktop2dJava.resume();

2.3.11 插播

sdk接口：window.desktop2dJava.insertDrive(text);

参数	说明
text	本地/在线PCM、WAV或播报文本

sdk会根据text内容，区分是本地路径、URL还是播报文本，调用响应的方法进行插入播报

样例

Plain

1window.desktop2dJava.insertDrive("E:\demo\123456789.pcm");
2window.desktop2dJava.insertDrive("Ehttps://meta-human-editor-prd.bj.bcebos.com/vis/2d_sdk_demo/987654321.wav");
3window.desktop2dJava.insertDrive("这是插播播报1,这是插播播报2");

2.4 播报界面设计

面板

open接口展示	刷新面板展示：

open接口展示

设置分辨率：resolution

使用resolution参数设置渲染界面的宽和高

自动旋转：autoRotate

设置为true，面板将自动旋转至竖屏显示，设置为false则不自动旋转

数字人人像：figureRequest.figureName

人像名称，对应figures目录下人像资源包名称，其中webm格式为BGRA包含透明通道，mp4为RGB格式，不透明。

面板图层：layerList

面板按照列表顺序依次从后往前叠加，列表后面的将覆盖前面的图层

Plain

1{
2            'resolution': {
3                'width': 1080,
4                'height': 1920
5            },
6            'autoRotate': false,
7            'figureRequest': {
8                'figureName': 'people_demo_webm'
9            },
10            'layerList': [
11              {
12                'type': 'VIDEO',
13                'position': {
14                  'top': 0.0,
15                  'left': 0.0,
16                  'width': 1.0,
17                  'height': 1.0,
18                  'aspect': 0.56
19                },
20                'source': {
21                  'url': 'https://meta-human-editor-prd.bj.bcebos.com/vis/2d_sdk_demo/1080_1920_4s.mp4'
22                }
23              },
24                {
25                    'type': 'DIGITAL_HUMAN',
26                    'position': {
27                      'top': 0.119922,
28                      'left': 0.189583,
29                      'width': 0.619444,
30                      'height': 0.488672,
31                      'aspect': 0.71
32                    }
33              },
34              {
35                'type': 'IMAGE',
36                'position': {
37                  'top': 0.1,
38                  'left': 0.05,
39                  'width': 0.355,
40                  'height': 0.077,
41                  'aspect': 2.58
42                },
43                'source': {
44                  'url': 'https://meta-human-editor-test.cdn.bcebos.com/cea9a767-e17f-4cea-b160-152d0374bb26/material/%E6%9C%80%E6%96%B0logo_%E9%BB%91.png'
45                }
46              }
47            ]
48        }));
49    }

刷新接口

刷新接口的目的是重新布置面板图层，打到动态更新图层元素的目的，参数与open接口的layerList相同，除不能修改数字人人像外，其余元素都可以更改。图层顺序与open接口一致，按照列表顺序从后往前叠加，列表后面的将覆盖前面的图层

Plain

1[
2            {
3                'type': 'IMAGE',
4                'position': {
5                  'top': 0.0,
6                  'left': 0.0,
7                  'width': 1.0,
8                  'height': 1.0,
9                  'aspect': 0.56
10                },
11                'source': {
12                  'url': 'https://digital-human-test.bj.bcebos.com/mxx/pic/720p/720x1080_3.png'
13                }
14              },
15              {
16                   'type': 'DIGITAL_HUMAN',
17                   'position': {
18                      'top': 0.319922,
19                      'left': 0.189583,
20                      'width': 0.619444,
21                      'height': 0.488672,
22                      'aspect': 0.71
23                    }
24                },
25            {
26                'type': 'IMAGE',
27                'position': {
28                    'top': 0.4,
29                    'left': 0.0,
30                    'width': 0.355,
31                    'aspect': 2.58
32                },
33                'source': {
34                    'url': 'https://meta-human-editor-test.cdn.bcebos.com/cea9a767-e17f-4cea-b160-152d0374bb26/material/%E6%9C%80%E6%96%B0logo_%E9%BB%91.png'
35                }
36            }
37        ]

aspect参数说明

aspect参数的目的，是为了动态调整分辨率和素材比例，aspect值 = 目标宽/目标高，比如9/16(宽/高)的数字人，对应数字人的aspect=0.5625

2.5 配置说明

sdk的conf目录下包含两个文件，一个config.yaml为默认读取的文件，config-all.yaml为默认配置参考，用户只需修改config.yaml即可

core.driveConfig

参数	说明
licenseKey	授权的文件名

core.ttsServiceConfig

参数	说明
baseUrl	tts url路径
httpQueryParams	tts配置
- lan	语言
- per	发音人id
- spd	语速
- pit	语调
- vol	音量
appKey	appKey
secretKey	secretKey

2.5.1 TTS 配置

要受用TTS文本转语音的能力，需要购买数字人TTS服务，在开放平台创建应用并关联TTS服务，将该应用的appKey和secretKey填入后，即可使用文本驱动数字人。

2.6 人像生成

进入曦灵营销内从创作平台，点击极速克隆，参照页面说明提交资料后生成

3 开发者接口

目标：为Windows Native开发者，提供方便、通用的接口。

输入：将用户的输入指令转为Inference的输入数据，包括加载并读取本地音频、在线音频，调用TTS获取文本转语音的音频等。

输出：将Inference的输出给到用户，由用户自己处理。

流程图.png

3.1 支持的通信接口

接口	协议/格式	对比
socket	protobuf	参考demo/command.proto和avFrame.proto
websocket	protobuf	参考demo/command.proto和avFrame.proto
RTC	-	请联系我们

接口	协议/格式	对比
socket	protobuf	参考demo/command.proto和avFrame.proto
websocket	protobuf	参考demo/command.proto和avFrame.proto
RTC	-	请联系我们

3.1.1 通信协议-Protobuf

输入：

Plain

1syntax = "proto3";
2
3package com.baidu.acg.digitalhuman.desktop2d.core.model;
4
5option java_multiple_files = true;
6option java_package = "com.baidu.acg.digitalhuman.desktop2d.core.model";
7
8message CommandReq {
9  CommandType type = 1;
10  optional string text = 2;
11}
12
13enum CommandType {
14  OPEN = 0;
15  SHUTDOWN = 1;
16  DRIVE_INTERRUPT = 2;
17  DRIVE_PAUSE = 3;
18  DRIVE_RESUME = 4;
19  DRIVE_BREAK_IN = 5;
20  DRIVE_LOCAL = 6;
21  DRIVE_WEB = 7;
22  DRIVE_TTS = 8;
23  DRIVE_STREAM = 9;
24}
25
26message CommandRes {
27  int32 code = 1;
28  string message = 2;
29}

输出：

Plain

1syntax = "proto3";
2
3package com.baidu.acg.digitalhuman.desktop2d.core.model;
4
5option java_multiple_files = true;
6option java_package = "com.baidu.acg.digitalhuman.desktop2d.core.model";
7
8message AVFrameRes {
9  string frameId = 1;
10  bytes audioData = 2;
11  bytes imageData = 3;
12  string pixelFormat = 4;
13}

3.1.2 切换生产模式

修改配置文件conf/config.yaml，修改如下配置

Plain

1version: 1.0
2mode: 'PRODUCTION'
3core:
4  serverType: "Socket"
5  cmdPort: 8010
6  renderPort: 8018

其中：serverType支持Socket和WebSocket，如果您使用其它协议，请联系我们客服进行沟通。

3.1.2 socket通信demo

服务启动后，demo/command_client.py 连接服务端发送指令，demo/avFrame_client.py连接服务端，接受服务端推送的音视频数据

【准备】完成引擎的初始化，能跑通样例APP
修改配置文件，改为生产模式，参考3.1.3
启动推理服务，执行run.sh或run.ps1
启动command_client.py, 参考command_client.py，结合 2.3 接口说明进行修改
启动avFrame_client.py, 根据注释查看音视频数据信息

4 常见问题

4.1 授权问题

授权失败会返回错误码，根据错误码进行排查：

Plain

1enum class ErrorCode {
2     SUCCESS = 0,
3     LICENSE_NOT_INIT_ERROR = 1,
4     LICENSE_DECRYPT_ERROR = 2,
5     LICENSE_INFO_FORMAT_ERROR = 3,
6     LICENSE_KEY_CHECK_ERROR = 4,
7     LICENSE_ALGORITHM_CHECK_ERROR = 5,
8     LICENSE_MD5_CHECK_ERROR = 6,
9     LICENSE_DEVICE_ID_CHECK_ERROR = 7,
10     LICENSE_PACKAGE_NAME_CHECK_ERROR = 8,
11     LICENSE_EXPIRED_TIME_CHECK_ERROR = 9,
12     LICENSE_FUNCTION_CHECK_ERROR = 10,
13     LICENSE_TIME_EXPIRED = 11,
14     LICENSE_LOCAL_FILE_ERROR = 12,
15     LICENSE_REMOTE_DATA_ERROR = 13,
16     LICENSE_LOCAL_TIME_ERROR = 14,
17     LICENSE_PARAM_ERROR = 15,
18     LICENSE_KEY_FILE_ERROR = 16,
19     OTHER_ERROR = 1000
20};

4.2 应用程序无法正常启动(0x000007b)

原因：新机器没有对应的环境，缺少相应的网络库等。需先下载VC_redist.x64 安装。

4.3 显卡驱动找不到

任务管理器看不到显卡信息，到显卡官方网站下载对应显卡驱动，重启后生效。

4.4 在播报过程中切换播放源或暂停播放有轻微延迟

因为播放的画面为实时音频驱动生成，播放有一定缓冲，在插入播报、打断、暂停操作时会有几秒延迟。

2D数字人交互SDK-iOS版

照片数字人交互SDK-H5版

数字员工-开放平台

2D数字人交互SDK-Windows版

1、产品介绍

1.1、适用场景特点

1.2、核心功能

1.3 整体架构

1.4、 环境依赖

硬件依赖

软件依赖

2、使用说明

2.1、SDK下载链接

2.2、SDK的使用说明

2.2.1 下载SDK并解压

2.2.2 申请授权文件

2.2.3 模型预热

2.2.4 运行样例APP，验证功能完整性

2.3 接口说明

2.3.1 控制接口：打开面板

2.3.2 控制接口：关闭面板

2.3.3 控制接口：刷新面板

2.3.4 本地播放PCM/WAV

2.3.5 在线播放PCM/WAV

2.3.6 文本播放

2.3.7 流式播放

2.3.8 打断播报

2.3.9 暂停播报

2.3.10 恢复播报

2.3.11 插播

2.4 播报界面设计

2.5 配置说明

2.5.1 TTS 配置

2.6 人像生成

3 开发者接口

3.1 支持的通信接口

3.1.1 通信协议-Protobuf

3.1.2 切换生产模式

3.1.2 socket通信demo

4 常见问题

4.1 授权问题

4.2 应用程序无法正常启动(0x000007b)

4.3 显卡驱动找不到

4.4 在播报过程中切换播放源或暂停播放有轻微延迟

1.4、环境依赖