Android SDK 接入指南

一、开发环境与源码准备

1. 安装开发工具

安装 & 配置 Android Studio

2. 快速体验demo

Android 压缩包附带的 apk 文件中是虚拟人 demo 的安装包，可以直接安装到 Android 手机上。并快速体验在您的手机上的表现。

获取方式：
GitHub：https://github.com/publicize0828/XmovLiteAvatarAndroidDemo
Gitee：https://gitee.com/xmovmaster/XmovLiteAvatarAndroidDemo

Android 压缩包附带的 demo 文件夹中是虚拟人的示例工程，使用 Android studio 打开示例工程，完成以下步骤配置，然后直接运行起来测试：

a. 替换 demo_configs.json 中的 appid 和 appSecret
b. demo_configs.json 中的 config 按需配置
c. MockAudioInputsData.json 是支持自行输入音频数据的示例格式

二、依赖配置与系统声明

1. 将开发包拷贝到工程

将SDK中libs目录下的aar包拷贝到自己工程的libs目录下，如没有该目录需新建。

在app文件夹下的build.gradle的dependencies中配置对应版本的aar依赖详细代码如下：

implementation files('libs/xmovdigitalhuman-xxx.aar')

2. 添加外部第三方依赖 详细代码如下：

    implementation "javax.vecmath:vecmath:1.5.2"
    implementation "com.google.code.gson:gson:2.13.1"
    implementation "com.squareup.okhttp3:okhttp:5.1.0"
    implementation "org.msgpack:msgpack-core:0.9.3"
    implementation "io.socket:socket.io-client:2.1.0"
    // Protobuf 依赖
    implementation("com.google.protobuf:protobuf-javalite:3.21.12")
    // ExoPlayer dependency for WebM/Opus streaming
    implementation "androidx.media3:media3-exoplayer:1.9.0"

根 build.gradle.kts文件中增加protobuf相关配置

3. 校验系统自带依赖

确保当前工程的构建脚本中已包含以下核心系统组件与测试框架。

4. 配置AndroidManifest.xml文件

在manifest标签内添加必要的权限支持

<uses-permission android:name="android.permission.INTERNET"/>

5. 混淆规则

-keep public class com.xmov.metahuman.sdk.data.**{*;}
-keep public class com.xmov.metahuman.sdk.impl.data.**{*;}
-keep public class com.xmov.metahuman.sdk.impl.transport.http.**{*;}
-keep public interface com.xmov.metahuman.sdk.IXmovAvatar {*;}
-keep class com.xmov.metahuman.sdk.IXmovAvatar$Companion { *;}
-keep public interface com.xmov.metahuman.sdk.IAvatarListener {
    public protected *;
}
-keep public interface com.xmov.metahuman.sdk.PreCacheListener {
    public protected *;
}

通过上面的几个步骤，工程就配置完成了，接下来就可以在工程中使用虚拟人SDK进行开发了。

三、SDK 初始化与回调接管

1. 初始化

使用SDK功能前，必须先进行初始化操作。

方法原型

fun init(
        context: Context,
        layout: ViewGroup,
        initConfig: InitConfig,
        listener: IAvatarListener?
    )

参数描述

InitConfig 类介绍

在初始化监听器中，需接管以下核心底层事件流：

     IXmovAvatar.get().init(this, mBinding.avatarLayout, initConfig.appId, initConfig.appSecret,initConfig.gatewayServer,object : IAvatarListener {
            override fun onInitEvent(code: Int, message: String?) {
                LogUtil.d("onInitEvent code:$code,message:$message")
            }

            override fun onWidgetEvent(widgetData: IRawEventFrameData?) {
                LogUtil.d("onWidgetEvent widgetData:$widgetData")
            }

            override fun onNetworkInfo(sdkNetworkInfo: SDKNetworkInfo?) {
                LogUtil.d("onNetworkInfo $sdkNetworkInfo")
            }

            override fun onMessage(sdkMessage: SDKMessage?) {
                LogUtil.d("onMessage $sdkMessage")
            }

            override fun onStateChange(state: String?) {
                LogUtil.d("onStateChange $state")
            }

            override fun onStatusChange(status: SDKStatus?) {
                LogUtil.d("onStatusChange $status")
            }

            override fun onStateRenderChange(state: String?, duration: Long) {
                LogUtil.d("onStateRenderChange state：$state,duration:$duration")
            }

            override fun onVoiceStateChange(status: String?) {
                LogUtil.d("onVoiceStateChange state：$status")
                runOnUiThread {
                    if ("voice_end" == status) {
                    } else if ("voice_start" == status) {
                    }
                }
            }

            override fun onDebugInfo(debugInfo: JSONObject) {
                // LogUtil.d("onDebugInfo debugInfo：$debugInfo")
            }

            override fun onReconnectEvent(code: Int, message: String?) {
                toast("重连：code=$code message=$message")
            }

            override fun onOfflineEvent() {
                toast("进入离线状态")
            }
        })
   

2. 初始化回调

onInitEvent(code: Int, message: String?)

方法返回参数分为外层code和result，含义如下：

3. 事件回调（字幕回调）

onWidgetEvent(widgetData: IRawEventFrameData?)

IRawEventFrameData实体类

4. 声音播报回调

onVoiceStateChange(status: String?)

5. 重连在线模式回调

onReconnectEvent(code: Int, message: String?)

6. SDK在运行过程中的错误回调

可在该回调中，进行重新初始化逻辑，保证设备长期运行

onSDKRuntimeError(code: Int, message: String?)

7. speak事件回调

返回speak事件的开始，结束，错误状态

onSpeakStateChange(speakState: String?,clientSpeakId: String?,errorMsg: String?)

四、全局参数配置对象

在进行初始化时，initConfig中的config是一个json 字符串，可以定制化做一些配置

1. config配置

在进行初始化时，initConfig中的config是一个json 字符串，可以定制化做一些配置config字段名介绍

2. LayoutConfig介绍

（1）container（容器配置）

（2）avatar（数字人布局配置）

注意：align需要容器为约束布局ConstraintLayout 类型生效

4. 配置示例

{
      "max_reconnect_count": 5,
      "render_time_out": 12,
      "input_audio": false,
      "output_audio": true,
      "resolution": {
        "width": 1080,
        "height": 1920
      },
      "layout": {
        "container": {
          "size": [1080, 1920]
        },
        "avatar": {
          "h_align": "center",
          "v_align": "middle",
          "scale": 1,
          "offset_x": 0,
          "offset_y": 0
        }
      }
    }

五、核心能力与状态控制

1. Speak

方法原型参数说明

支持全文本和流式文本输入

（1）全文本输入时代码示例：

IXmovAvatar.get().speak("welcomeMessage", true, true, false,null)

(2) 流式文本输入时代码示例

//开头
IXmovAvatar.get().speak("msg 1", true, false, false,null)
IXmovAvatar.get().speak("msg 2", false, false, false,null)
...
//结尾
IXmovAvatar.get().speak("msg 2", false, true, false,null)

2. 虚拟人常用的一下动作状态切换

1.倾听

代码示例

IXmovAvatar.get().listen()

2.思考

代码示例

IXmovAvatar.get().think()

3.打断

代码示例

IXmovAvatar.get().interrupt()

3. 断线

重连本sdk支持，当网络波动或者无网情况下，自动进入离线状态，当有网络时会自动重连。也支持客户手动切换到离线状态，然后再重连（注意 重连只能是离线状态下进行重连，其他状态进行重连会报错）方法原型

fun switchModel(isOffline: Boolean)

参数说明

示例代码

IXmovAvatar.get().switchModel(true) 

4. 销毁

销毁sdk实例，断开连接 进行资源释放。虚拟人退出时调用方法原型

  fun destroy()

示例代码

IXmovAvatar.get().destroy()

5. 日志开关

在调试阶段可以打开日志，方便分析问题，应用发布时可关闭日志，提升性能，默认是打开日志的关闭日志方法原型

fun hideDebugInfo()

示例代码

IXmovAvatar.get().hideDebugInfo()

打开日志方法原型

fun showDebugInfo()

示例代码

IXmovAvatar.get().showDebugInfo()

六、底层驱动引擎替换

只针对带唤醒的demo工程

1. 唤醒词

更换唤醒词，需要提供讯飞的sdk包

1. 解压讯飞唤醒sdk的压缩包，在项目源码中替换 ivw中的xxx.jet文件
2. 代码中需要修改唤醒词字符串匹配规则

2. 换LLM

1. 更换对应llm厂商的apikey，defaultMode， defaultPointID(豆包)

2. 重新实现llm流式返回实现

3. 换ASR

1. asr 厂商的一些常量设置

2. 代码实现

七、工程调试与终端构建

1. 调试与运行

模拟器

Step 1

Step 2

Step 3

真机

Step 1

Step 2

2. 打包

环境准备

本项目需要安装 JDK 11 或更高版本。

为了获得最佳的构建兼容性，推荐使用 Java 17 或 Java 21。

如果未安装 JDK，可参考以下教程：

JDK 17 安装教程
JDK 21 安装教程

基础机制

打包流程主要通过执行项目根目录下的 ./gradlew 脚本完成。该脚本会自动下载并匹配项目所需的 Gradle 版本，无需手动配置 Gradle 环境。

打包流程

1. 定位目录：在终端中，确保当前路径已定位至项目根目录。

2. 执行指令：输入以下命令开始打包：

./gradlew bundleRelease

输出文件位置

构建命令执行成功后，终端会显示 "BUILD SUCCESSFUL"。此时生成的发布包位于项目的 build 目录下。

文件路径：app/build/outputs/apk/release/

常见问题与注意事项

权限问题 如果您在打包时遇到 Permission denied 或类似权限问题，请先在终端执行以下命令赋予脚本执行权限：

chmod +x gradlew

⚠️ 最佳实践

编译清理：建议在打包 Release 版本前先执行 clean 指令，确保包体内不包含旧代码缓存。
多任务合并：您可以一次性执行清理和打包，命令如下：

./gradlew clean assembleRelease

八、错误排查与兼容矩阵

1. 返回码

该返回码为虚拟人SDK自身的返回码，具体错误在碰到之后查阅主要用于onInitEvent、onReconnectEvent、onSDKRuntimeError回调

2. 兼容性说明

针对SDK兼容性已在上述设备进行测试（设备/操作系统/分辨率）

如有希望提供更多的设备兼容性测试信息，请联系我们：