Duix-Mobile 集成验证笔记：离线实时 AI 数字人 SDK 怎么在手机上跑通
【免费下载链接】Duix-Mobile🚀 The best real-time interactive AI avatar(digital human) with on-premise deployment and <1.5 s latency.项目地址: https://gitcode.com/GitHub_Trending/du/Duix-Mobile
Duix-Mobile 是一套实时交互式 AI 数字人移动端 SDK，主打端侧部署：模型跑在手机上，唇形同步与渲染不经过云端。下文的结论和坑位都来自仓库里的文档与源码，不是印象。
仓库结构：一个 Gradle 模块加一套 C++ 核心
先给判断：这个仓库交付的是 SDK，不是装完就能用的 App。两条产品线共享同一套 C++ 核心，你只需要关注自己平台那一侧的封装层。
图：仓库演示素材，展示数字人实时交互画面
Android 侧的入口是 duix-android/dh_aigc_android/，核心是duix-sdk这个 Gradle 模块：
- 模型检查与下载在
VirtualModelUtil，初始化、推流、动作控制在DUIX（见 duix-sdk/src/main/java/ai/guiji/duix/sdk/client/）。 - 渲染组件
DUIXRenderer/DUIXTextureView支持透明背景，也可以自己实现RenderSink接管渲染管线。 - 真正的算法在 native 层 duix-sdk/src/main/cpp/，按职责拆成三个静态库：
dhmfcc做音频前端（FFT、MFCC 特征提取），dhunet做唇形驱动网络，dhcore管内存与队列；依赖 ncnn、onnxruntime 和 OpenCV，由 CMakeLists.txt 统一链接。 - Java 层只通过
DuixNcnn的 native 方法（pushpcm、filrst等）与 C++ 核心通信。
iOS 侧是 duix-ios/GJLocalDigitalSDK/，同一套duixsdka/目录结构与 Android 的 cpp 一一对应（dhmfcc、dhunet、dhcore），对外封装为GJLDigitalManager。维护时改核心算法两端同步，这也是双端行为差异的排查线索。
跑通前的硬门槛：硬件、内存与模型资源
文档给出的集成要求很具体，先核对再动手，能省掉大半排查时间。
| 项目 | Android | iOS |
|---|---|---|
| 系统 | Android 10+，armeabi-v7a / arm64-v8a | iOS 12.0+，Xcode 12+ |
| 硬件参考 | 骁龙 8 Gen 2 级别、8GB 以上内存 | iPhone 8+，建议 A12+、≥3GB 内存 |
| 资源 | 数字人至少占用 800MB 内存，预留 1GB 以上存储 | — |
| 网络 | 无（完全本地运行） | 无 |
模型资源有两份，都走下载：
- 基础配置包
gj_dh_res，SDK 内置下载地址（见 Constant.java）； - 人物模型包，官方提供 4 个公开数字人（Leo、Oliver、Sofia、Lily），下载入口在 README 的发布页链接里。
图：官方公开的 4 个数字人模型之一，集成时按需替换
如果模型下载慢，文档明确允许把模型包缓存到自己的存储服务，不强制走官方地址。
最小集成路径：从 clone 到第一帧渲染
git clone https://gitcode.com/GitHub_Trending/du/Duix-MobileAndroid 端按 duix-android 文档 走三步：
- 把
duix-sdk目录拷进项目根目录，settings.gradle里include ':duix-sdk'，模块build.gradle加api project(":duix-sdk")。 - 用
VirtualModelUtil检查并下载基础配置与模型。 - 构造
DUIX（传入模型、渲染 sink、回调），调init()，初始化结果走init.ready/init.error回调；渲染用DUIXRenderer挂到DUIXTextureView。
iOS 端按 duix-ios 文档：拖入GJLocalDigitalSDK.framework（Embed & Sign）、链接AVFoundation，然后在 Info.plist 声明麦克风权限：
<key>NSMicrophoneUsageDescription</key> <string>App requires microphone access to drive digital human voice broadcast</string>最小调用链是initBaseModel → toStart → toStartRuning，渲染视图必须是已挂载的showView。
仓库自带验证素材：demo 工程的 assets 里有现成的 PCM 与 WAV 音频（test/src/main/assets/），res/ 目录有 270p / 540p 两档预渲染人物视频与背景图，跑通前可以直接拿这些文件验证驱动链路，不急着接自己的 TTS。
验证清单可以按顺序做：
checkBaseConfig返回 true（配置包已就位）；init回调为init.ready；- 推一段 PCM，听到声音且画面口型同步；
- 换一个人物模型目录，
init仍然成功。
PCM 流驱动：最容易踩的几个坑
数字人靠音频驱动，Android 的驱动协议是startPush → pushPcm → stopPush三段式，文档里写了三条硬约束：
- 格式固定为 16kHz、单声道、16bit 的 PCM；
- 每段（两次 push 之间）音频至少 1 秒（32000 字节），否则唇形驱动不会触发，可以用空白帧补齐；
- 音频不要一次推太长，PCM 会缓存在内存里，长音频可能撑爆内存，应分段推流。
初始化阶段的失败大多有明确原因，Android FAQ 给了对照表：
| 现象 | 可能原因 | 处理 |
|---|---|---|
| init 回调失败 | 模型路径错误或未下载 | 用checkModel检查模型状态 |
| 渲染黑屏 | EGL 配置或 TextureView 设置问题 | 按文档示例配置 |
| PCM 推流无效果 | 格式不对或未调startPush | 核对格式与调用顺序 |
iOS 侧对应四张排查项：初始化返回 -1 查 Info.plist 授权字段、无渲染输出查showView是否挂载、播放无响应查音频格式与路径、播放提前结束查continueSession用法。
适用边界：适合谁，不适合谁
这个 SDK 的卖点"全离线"要拆开看。它离线的是渲染与唇形驱动这条链路；对话本身依赖的 LLM、ASR、TTS 并不在仓库内，官方 FAQ 的答复是"完全支持集成自定义或第三方服务"——也就是说智能程度由你自己接的模型决定，SDK 只负责把音频变成会动的数字人。
几个事实供决策参考：
- 弱网或完全离线的播报、问答场景是它的主场，这正是文档里反复强调"不依赖服务器"的原因；
- 定制私有形象走官方邮箱渠道，官方说法是提供 15 秒到 2 分钟的视频即可完成；
- 流式音频（边合成边播放、支持打断）自 2025 年 7 月 17 日版本起提供；
- 官方给出的延迟数据是"骁龙 8 Gen 2 上实测低于 120ms"，低端设备文档也承认特征提取速度可能跟不上播放速度，可以用
duix.setReporter()监控帧渲染信息，是否达标建议在自己的目标机型上实测； - iOS 端有授权机制，
init返回 0 即未授权，接入前先看文档第 8 节的回调定义。
一句话收束：Duix-Mobile 把"数字人能不能离线跑"从产品问题变成了工程问题——硬件档位、模型资源、PCM 格式三件事核对完，剩下的就是按回调和 FAQ 排查，仓库里的文档比宣传文案更有用。
【免费下载链接】Duix-Mobile🚀 The best real-time interactive AI avatar(digital human) with on-premise deployment and <1.5 s latency.项目地址: https://gitcode.com/GitHub_Trending/du/Duix-Mobile
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
