Duix Mobile for Android:纯离线 2D 虚拟人 SDK 集成开发实战指南(模型管理 / 语音驱动 / 动作控制)
Duix Mobile for Android:纯离线 2D 虚拟人 SDK 集成开发实战指南(模型管理 / 语音驱动 / 动作控制)
本指南以 duix-android/dh_aigc_android/README_zh.md 为主线,系统讲解 Duix Mobile for Android 这套轻量级、纯离线的 Android 2D 虚拟人解决方案的接入全过程:从工程引用、模型下载管理,到 DUIX 实例初始化、透明渲染、PCM/WAV 语音驱动与动作区间控制。阅读完本文,你将能够在 Android 10+ 设备上独立搭建一套"语音音频驱动数字人实时播报"的完整应用,并掌握底层 RenderThread 驱动链路、回调事件约定与常见问题排查方法。
一、产品定位与核心能力
Duix Mobile for Android 是一套轻量级、纯离线的 Android 平台 2D 虚拟人解决方案,支持通过语音音频驱动数字人形象并进行实时渲染,整个过程完全在本地完成,不依赖网络。
1.1 应用场景
- 部署成本低:适用于大屏终端、政务展厅、银行等无人值守场景。
- 网络依赖小:完全本地运行,无需联网,可在地铁、偏远地区稳定运行。
- 功能多样化:可服务于导览讲解、问答客服、智能陪伴等多种业务形态。
1.2 核心功能
| 功能 | 说明 |
|---|---|
| 数字人形象定制与本地渲染 | 加载模型后通过 OpenGL ES 本地实时渲染 |
| 实时语音驱动播报 | 支持 WAV 播放驱动与 PCM 流式推送驱动两种方式 |
| 动作播放控制 | 支持指定动作区间播放与随机动作播放 |
| 资源自动下载管理 | 内置基础配置与模型包的下载、解压、校验工具 |
从仓库结构看,SDK 本体位于 duix-sdk 模块,Demo 应用位于 test 模块;duix-sdk/src/main/cpp 下封装了音频特征提取(dhmfcc)、人脸渲染(dhunet)与 AES 加解密等底层能力,Java 层通过 JNI 调用(见 DuixJni.cpp)与本地渲染线程协作。
二、关键术语速查
| 术语 | 含义 |
|---|---|
| PCM | Pulse-Code Modulation,16kHz 采样率、16bit 位深、Mono 单通道的原始音频流 |
| WAV | 一种音频文件格式,支持 PCM 编码,适合短语音播放 |
| RenderSink | 渲染数据接收接口,由 SDK 提供实现,可用于自定义渲染或默认展示 |
| DUIX | 数字人主控对象,集成了模型加载、渲染、播报、动作等能力 |
| GLES | OpenGL ES,Android 渲染图像用到的图形接口 |
| SpecialAction | 模型附带的 JSON 文件,标注动作区间(例如打招呼、挥手等) |
三、SDK 获取与工程接入
3.1 Module 引用(推荐)
- 获取完整源码包,解压后将
duix-sdk目录复制到项目根目录下。 - 在项目
settings.gradle中添加:
include ':duix-sdk'
仓库中的 settings.gradle 实际配置为:
include ':duix-sdk'
include ':test'
即 SDK 模块与 Demo(test)模块并列存在,可直接参考 test 模块的接入写法。
- 在模块
build.gradle中添加依赖:
dependencies {
api project(":duix-sdk")
}
使用 api 关键字可以将 SDK 的传递依赖一并暴露给上层模块。
3.2 AAR 引用(可选)
- 将
duix-sdk模块编译出的duix-sdk-release.aar放入libs/目录。 - 添加依赖:
dependencies {
api fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
}
四、集成要求与运行环境
| 项目 | 描述 |
|---|---|
| 系统 | 支持 Android 10+ 系统 |
| CPU 架构 | armeabi-v7a, arm64-v8a |
| 硬件要求 | CPU 8 核及以上(骁龙 8 Gen2),内存 8G 及以上,可用存储空间 1GB 及以上 |
| 网络 | 无(完全本地运行) |
| 开发 IDE | Android Studio Giraffe 2022.3.1 Patch 2 |
| 内存要求 | 可用于数字人的内存 >= 800MB |
编译项目的 Gradle 使用的 JDK 版本为 17,需要在
File -> Setting -> Build, Execution, Deployment -> Gradle Projects -> Gradle JDK中选择一个 17 版本的 JDK。
从源码推断,SDK 的本地推理链路依赖 ncnn 等第三方库,因此对 CPU 核数与可用内存有明确要求;集成前请务必按上表核对目标设备配置。
五、整体使用流程
graph TD
A[检查配置与模型] --> B[构建 DUIX 实例]
B --> C[调用 init 初始化]
C --> D[展示形象 / 渲染]
D --> E[PCM 或 WAV 音频驱动]
E --> F[播放控制与动作触发]
F --> G[资源释放]
对应到源码,DUIX.init()(见 DUIX.java)会先校验本地模型文件,随后创建并启动名为 DUIXRender-Thread 的渲染线程(RenderThread,见 RenderThread.java)。渲染线程内部通过 ModelInfoLoader 加载模型信息,以约 40ms 为周期循环渲染(delay = 40 - useTime),并在页面销毁时通过 DUIX.release() 释放资源。
六、模型检查与下载管理
使用渲染服务前需要将基础配置及模型文件同步到本地存储中。SDK 中提供了 VirtualModelUtil 演示模型下载解压流程;若模型下载过慢或无法下载,开发者可以选择将模型包缓存到自己的存储服务。
函数定义:
ai.guiji.duix.sdk.client.VirtualModelUtil,源码见 VirtualModelUtil.java
// 检查基础配置是否已下载
boolean checkBaseConfig(Context context)
// 检查模型是否已下载
boolean checkModel(Context context, String name)
// 基础配置下载
void baseConfigDownload(Context context, String url, ModelDownloadCallback callback)
// 模型下载
void modelDownload(Context context, String modelUrl, ModelDownloadCallback callback)
ModelDownloadCallback 包含进度、完成、失败等回调:
interface ModelDownloadCallback {
// 下载进度
void onDownloadProgress(String url, long current, long total);
// 解压进度
void onUnzipProgress(String url, long current, long total);
// 下载解压完成
void onDownloadComplete(String url, File dir);
// 下载解压失败
void onDownloadFail(String url, int code, String msg);
}
调用示例:
if (!VirtualModelUtil.checkBaseConfig(mContext)){
VirtualModelUtil.baseConfigDownload(mContext, baseConfigUrl, callback)
}
if (!VirtualModelUtil.checkModel(mContext, modelUrl)){
VirtualModelUtil.modelDownload(mContext, modelUrl, callback)
}
6.1 本地目录约定与校验机制
从 VirtualModelUtil.java 与 DUIX.java 的实现可以确认以下存储约定:
- 所有资源存放在应用外部私有目录
getExternalFilesDir("duix")/model下; - 基础配置解压到
model/gj_dh_res,并在model/tmp/gj_dh_res写入"完成标记"目录,checkBaseConfig同时校验这两个目录是否存在; - 模型解压到
model/<模型名>,标记目录为model/tmp/<模型名>; - 若
modelName是http(s)://开头的 URL,SDK 会取 URL 最后一段去.zip作为目录名(DUIX.java);否则直接把modelName当作缓存文件名。
下载解压的底层逻辑在 DownloadZipService.java 中实现,支持进度回调、解压进度与失败码上报。onDownloadFail 的 code 含义如下(见源码注释):
| 错误码 | 含义 |
|---|---|
| -1000 | 压缩文件下载失败 |
| -1001 | 解压文件时发生异常 |
| -1002 | 目标文件夹未找到 |
| -1003 | 非法的下载 URL |
| -1004 | 非法的模型 URL |
| -1005 | 服务未初始化 |
6.2 Demo 中的完整下载编排
仓库 MainActivity.kt 演示了标准的"先基础配置、后模型"编排:先 checkBaseConfig,未就绪则 baseConfigDownload,完成后再 checkModel,未就绪则 modelDownload,全部就绪才跳转到渲染页 CallActivity,并把 modelUrl 通过 Intent 传递。示例中的模型 URL 列表(models 数组)可直接替换为你自建托管的模型包地址。
七、初始化与渲染启动
在渲染页 onCreate() 阶段构建 DUIX 对象并调用 init 接口。
函数定义:
ai.guiji.duix.sdk.client.DUIX,源码见 DUIX.java
// 构建DUIX对象
public DUIX(Context context, String modelName, RenderSink sink, Callback callback)
// 初始化DUIX服务
void init()
DUIX 对象构建说明:
| 参数 | 类型 | 描述 |
|---|---|---|
| context | Context | 系统上下文 |
| modelName | String | 可以传递模型下载的 URL(已下载完成)或缓存的文件名 |
| render | RenderSink | 渲染数据接口,SDK 提供了默认的渲染组件继承自该接口,也可以自己实现 |
| callback | Callback | SDK 处理的各种回调事件 |
其中 Callback 的定义:ai.guiji.duix.sdk.client.Callback
interface Callback {
void onEvent(String event, String msg, Object info);
}
事件常量定义在 ai.guiji.duix.sdk.client.Constant(见 Constant.java):
| 事件常量 | 取值 | 触发时机 |
|---|---|---|
| CALLBACK_EVENT_INIT_READY | init.ready |
初始化成功,info 为 ModelInfo |
| CALLBACK_EVENT_INIT_ERROR | init.error |
初始化失败,msg 携带原因 |
| CALLBACK_EVENT_AUDIO_PLAY_START | play.start |
音频开始播放 |
| CALLBACK_EVENT_AUDIO_PLAY_END | play.end |
音频播放完成 |
| CALLBACK_EVENT_AUDIO_PLAY_ERROR | play.error |
音频播放异常 |
| CALLBACK_EVENT_MOTION_START | motion.start |
动作区间开始播放 |
| CALLBACK_EVENT_MOTION_END | motion.end |
动作区间播放完成 |
调用示例:
duix = DUIX(mContext, modelUrl, mDUIXRender) { event, msg, info ->
when (event) {
ai.guiji.duix.sdk.client.Constant.CALLBACK_EVENT_INIT_READY -> {
initOK()
}
ai.guiji.duix.sdk.client.Constant.CALLBACK_EVENT_INIT_ERROR -> {
initError()
}
// ...
}
}
// 异步回调结果
duix?.init()
在 init 回调中确认初始化结果。init.ready 回调的 info 是 ModelInfo 对象,可用于获取可用的动作区间列表——Demo CallActivity.kt 中正是通过 modelInfo.motionRegions 动态生成动作按钮列表的。
7.1 数字人形象展示:透明通道渲染
使用 SDK 提供的 DUIXRenderer 和 DUIXTextureView 可快速实现支持透明通道的渲染;也可以自己实现 RenderSink 接口自定义渲染逻辑。
其中 RenderSink 的定义如下:ai.guiji.duix.sdk.client.render.RenderSink,源码见 RenderSink.java
/**
* 渲染管道,通过该接口返回渲染数据
*/
public interface RenderSink {
// frame中的buffer数据以bgr顺序排列
void onVideoFrame(ImageFrame imageFrame);
}
调用示例:使用 DUIXRenderer 及 DUIXTextureView 控件简单实现渲染展示,该控件支持透明通道,可以自由设置背景及前景。
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// ...
mDUIXRender =
DUIXRenderer(
mContext,
binding.glTextureView
)
binding.glTextureView.setEGLContextClientVersion(GL_CONTEXT_VERSION)
binding.glTextureView.setEGLConfigChooser(8, 8, 8, 8, 16, 0) // 透明
binding.glTextureView.isOpaque = false // 透明
binding.glTextureView.setRenderer(mDUIXRender)
binding.glTextureView.renderMode =
GLSurfaceView.RENDERMODE_WHEN_DIRTY // 一定要在设置完Render之后再调用
duix = DUIX(mContext, modelUrl, mDUIXRender) { event, msg, _ ->
}
// ...
}
从 DUIXRenderer.java 的实现可以看到透明渲染的关键细节:onDrawFrame 中启用 GL_BLEND,并使用 glBlendFuncSeparate(GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA, GL_ONE, GL_ZERO) 为 RGB 与 Alpha 通道分别设置混合选项,避免半透明边缘出现白色边框。同时 DUIXRenderer 提供 CROP / INSIDE 两种缩放策略(setScaleType),分别对应裁剪适配与完整展示。
另外,渲染线程通过 RenderSink.onVideoFrame 回调以 BGR 顺序排列的 ImageFrame 数据(见 RenderThread.java),如需接入自定义渲染(如投屏、AR 合成),实现该接口即可拿到原始帧缓冲。
八、语音驱动播报控制
8.1 流式推送 PCM 驱动数字人播报
PCM 格式:16k 采样率、单通道、16 位深。
函数定义:
ai.guiji.duix.sdk.client.DUIX
// 通知服务开始推送音频
void startPush()
// 推送PCM数据
void pushPcm(byte[] buffer)
// 完成一段音频推送(音频推送完就调要该函数,而不是等播放完成再调用。)
void stopPush()
startPush、pushPcm、stopPush 需要成对调用,pushPcm 不宜过长。可以在一整段音频推送完后调用 stopPush 结束当前会话,下一段音频再使用 startPush 重新开启推送。
每段 startPush 到 stopPush 中间的音频数据最少要 1 秒(32000 字节),否则无法触发口型驱动,可以自行使用空白帧填充。
调用示例:
val thread = Thread {
duix?.startPush()
val inputStream = assets.open("pcm/2.pcm")
val buffer = ByteArray(320)
var length = 0
while (inputStream.read(buffer).also { length = it } > 0){
val data = buffer.copyOfRange(0, length)
duix?.pushPcm(data)
}
duix?.stopPush()
inputStream.close()
}
thread.start()
底层驱动链路:DUIX.startPush/pushPcm/stopPush 只是把请求投递到 RenderThread 的消息队列(见 DUIX.java)。真正处理在 RenderThread.java:
handleStartPushAudio:调用scrfdncnn.newsession()开启一段新的音频会话(BnfSession),并让内部播放器进入推送态;handlePushAudio:将 PCM 数据同时交给scrfdncnn.pushpcm()(用于音频特征提取与口型驱动)和audioPlayer.pushData()(用于扬声器播放);handleStopPushAudio:调用scrfdncnn.finsession()结束会话,并通知播放器pushDone()。
这就是"音频驱动口型 + 同步出声"双路并行的实现方式。仓库 test/src/main/assets/pcm 中提供了 2.pcm、222.pcm 等测试音频可直接用于验证。
8.2 WAV 播放驱动
函数定义:
ai.guiji.duix.sdk.client.DUIX
void playAudio(String wavPath)
该函数兼容旧的 WAV 驱动数字人接口,在内部实际是调用了 PCM 推流方式实现驱动。
参数说明:
| 参数 | 类型 | 描述 |
|---|---|---|
| wavPath | String | 16k 采样率、单通道、16 位深的 wav 本地文件 |
调用示例:
duix?.playAudio(wavPath)
源码印证:从 DUIX.java 可以看到,playAudio 默认按 44 字节的 WAV 头跳过,读取剩余 PCM 数据后依次调用 startPush()、pushPcm()、stopPush(),与 8.1 节完全同一条驱动链路。
音频播放状态及进度回调:
object : Callback {
fun onEvent(event: String, msg: String, info: Object) {
when (event) {
// ...
"play.start" -> {
// 开始播放音频
}
"play.end" -> {
// 完成播放音频
}
"play.error" -> {
// 音频播放异常
}
}
}
}
这些事件由 RenderThread 内部播放器回调(onPlayStart/onPlayEnd/onPlayError)逐层转发到 DUIX 的 Callback(见 DUIX.java),分别对应 play.start、play.end、play.error。
8.3 终止当前播报
当数字人正在播报时调用该接口终止播报。
函数定义:
ai.guiji.duix.sdk.client.DUIX
boolean stopAudio();
调用示例:
duix?.stopAudio()
stopAudio 仅在 isReady 且渲染线程存在时生效并返回 true(见 DUIX.java),底层通过 MSG_STOP_PLAY_AUDIO 结束当前会话并停止播放器。
8.4 音量控制
除文档外,SDK 还提供了 setVolume(float volume) 接口,参数取值 0.0F ~ 1.0F,可动态调整数字人播报音量(见 DUIX.java)。Demo CallActivity.kt 中的静音开关即通过 setVolume(0.0F) / setVolume(1.0F) 实现。
九、动作控制
模型中支持新的动作区间标注(SpecialAction.json),动作区间信息在 init 成功回调的 ModelInfo.getSilenceRegion() / getMotionRegions() 中获取。
9.1 播放指定动作区间
函数定义:
ai.guiji.duix.sdk.client.DUIX
/**
* 播放指定动作区间
* @param name 动作区间名称,在init成功回调时,可以在ModelInfo.getSilenceRegion()中获取到可用的动作区间
* @param now 是否立即播放 true: 立即播放; false: 等待当前静默区间或动作区间播放完毕后播放
*/
void startMotion(String name, boolean now)
调用示例:
duix?.startMotion("打招呼", true)
底层实现:handleRequireMotion(见 RenderThread.java)会遍历 mModelInfo.getMotionRegions() 按名称匹配动作区间;now=true 时清除当前预览队列并立即插入目标区间帧,now=false 时则将区间帧追加到播放队列末尾,等当前静默/动作区间播完后再执行。
9.2 随机播放动作区间
随机播放场景及旧的标注协议(config.json)。
函数定义:
ai.guiji.duix.sdk.client.DUIX
/**
* 随机播放一个动作区间
* @param now 是否立即播放 true: 立即播放; false: 等待当前静默区间或动作区间播放完毕后播放
*/
void startRandomMotion(boolean now);
调用示例:
duix?.startRandomMotion(true)
handleRequireMotionRandom(见 RenderThread.java)从 motionRegions 中随机选择一个区间,插入策略与指定动作一致。动作播放开始/结束会触发 motion.start / motion.end 事件回调(见 RenderThread.java),可用于联动 UI 提示。
十、Proguard 配置
如果代码使用了混淆,请在 proguard-rules.pro 中配置:
-keep class ai.guiji.duix.DuixNcnn{*; }
DuixNcnn 是 SDK 的 JNI 桥接类(见 DuixNcnn.java),混淆时保留其全部成员可避免 native 方法签名失效。
十一、注意事项与性能监控
- 驱动渲染初始化前需要确保基础配置文件及模型下载到指定位置。
- 播放的 PCM 音频不宜过长,播放的 PCM 缓存在内存中,过长的音频流可能导致内存溢出。
- 替换预览模型可以在
MainActivity.kt文件中修改modelUrl的值,使用 SDK 中自带的文件下载解压管理以获得完整的模型文件。 - 音频驱动的格式:16k 采样率、单通道、16 位深度。
- 设备性能不足时可能导致音频特征提取的速度跟不上音频播放的速度,可以使用
duix?.setReporter()函数添加一个监控观察帧渲染返回的信息。 - 每段
startPush到stopPush中间的音频数据最少要 1 秒(32000 字节),否则无法触发口型驱动,可以自行使用空白帧填充。
setReporter 对应的接口为 RenderThread.Reporter.onRenderStat(int resultCode, boolean isLip, long useTime)(见 RenderThread.java)。每帧渲染结束后会回调 useTime(渲染耗时,毫秒)与 isLip(是否处于口型驱动状态);若渲染耗时持续接近或超过 40ms 帧周期,说明当前设备性能吃紧,应降低模型分辨率或调整推送策略。Demo 中该接口被注释保留,可取消注释用于调试面板(见 CallActivity.kt)。
十二、常见问题与排查指南
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| init 回调失败 | 模型路径错误或未下载完成 | 使用 checkModel 检查模型状态 |
| 渲染黑屏 | EGL 配置或纹理视图设置错误 | 使用 SDK 提供示例中的设置方法 |
| PCM 无播报效果 | 格式不符或未调用 startPush | 确保音频格式正确并调用推送方法 |
| 模型下载过慢 | 网络不稳定或 CDN 受限 | 支持自建模型文件托管服务 |
结合源码补充两点排查线索:init 失败时回调 msg 会携带具体原因,如 <a href="https://link.gitcode.com/i/dc762346d7c5579eec5cec23c94e2b2f" target="_blank">gj_dh_res] does not exist 表示基础配置未就绪(见 [DUIX.java);playAudio 要求 WAV 文件存在且长度大于 44 字节,否则静默无效果(见 DUIX.java)。
十三、版本记录
4.0.1
1. 支持PCM音频流驱动数字人,提升音频播放响应速度。
2. 优化动作区间播放,可根据模型配置指定播放动作区间。
3. 自定义音频播放器,去除Exoplayer播放依赖。
4. 提供简洁的模型下载同步管理工具。
3.0.5
1. 更新arm32位cpu的libonnxruntime.so版本以修复兼容问题。
2. 修改动作区间播放函数,可以使用随机播放和顺序播放,需要主动调用停止播放动作区间以回到静默区间。
3.0.4
1. 修复部分设备gl默认float低精度导致无法正常显示形象问题。
3.0.3
1. 优化本地渲染。
当前 SDK 版本号可通过 ai.guiji.duix.sdk.client.BuildConfig.VERSION_NAME 读取(Demo 主页即显示该值,见 MainActivity.kt)。
十四、开源依赖与目录导览
| 模块 | 描述 |
|---|---|
| onnx | 通用 AI 模型标准格式 |
| ncnn | 高性能神经网络计算框架(腾讯) |
对应的预编译依赖存放在仓库 duix-sdk/src/main/cpp/third 目录下,包含 ncnn-20221128-android-vulkan-shared、ncnn-20231027-android-shared 与 opencv-mobile-4.6.0-android 等;iOS 侧同源实现见 duix-ios/GJLocalDigitalDemo/GJLocalDigitalSDK。
如需继续深入,建议按以下顺序阅读仓库源码:
- DUIX.java —— 数字人主控对象全部公开接口;
- RenderThread.java —— 渲染线程消息驱动与音频会话管理;
- VirtualModelUtil.java 与 DownloadZipService.java —— 模型下载解压;
- DUIXRenderer.java 与 DUIXTextureView.java —— 透明渲染实现;
- CallActivity.kt 与 MainActivity.kt —— 完整可运行的集成示例。
如需更多帮助,请联系技术支持团队。