具身驱动SDK（Android版本）接入说明

一.准备工作

1.概述

本文是魔珐星云具身驱动SDK Android版本的接入文档，用于指导SDK的使用方法，默认读者已经熟悉 IDE（Eclipse 或者 Android Studio）的基本使用方法，以及具有一定的 Android 编程知识基础。

快速体验demo

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

获取方式：

GitHub：https://github.com/publicize0828/XmovLiteAvatarAndroidDemo

Gitee：https://gitee.com/xmovmaster/XmovLiteAvatarAndroidDemo

2.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"

3.配置AndroidManifest.xml文件

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

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

4.混淆规则

-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("进入离线状态")
            }
        })
   

1.初始化回调

onInitEvent(code: Int, message: String?)

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

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

onWidgetEvent(widgetData: IRawEventFrameData?)

IRawEventFrameData实体类

3.声音播报回调

onVoiceStateChange(status: String?)

4.重连在线模式回调

onReconnectEvent(code: Int, message: String?)

2.config配置

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

配置示例

{
      "input_audio": false,
      "output_audio": true,
      "resolution": {
        "width": 1080,
        "height": 1920
      },
      "init_events": [
        {
          "type": "SetCharacterCanvasAnchor",
          "x_location": 0,
          "y_location": 0,
          "width": 1,
          "height": 1
        }
      ]
    }

3.Speak

方法原型

 fun speak(ssml: String?, isStart: Boolean, isEnd: Boolean)

参数说明

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

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

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

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

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

4.断线重连

本sdk支持，当网络波动或者无网情况下，自动进入离线状态，当有网络时会自动重连。

也支持客户手动切换到离线状态，然后再重连（注意 重连只能是离线状态下进行重连，其他状态进行重连会报错）

方法原型

fun switchModel(isOffline: Boolean)

参数说明

示例代码

IXmovAvatar.get().switchModel(true) 

5.销毁

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

方法原型

  fun destroy()

示例代码

IXmovAvatar.get().destroy()

三.虚拟人状态

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

1.倾听

代码示例

IXmovAvatar.get().listen()

2.思考

代码示例

IXmovAvatar.get().think()

3.打断

代码示例

IXmovAvatar.get().interrupt()

四.返回码

该返回码为虚拟人SDK自身的返回码，具体错误在碰到之后查阅

五.兼容性说明

针对SDK兼容性已在上述设备进行测试（设备/操作系统/分辨率）
如有希望提供更多的设备兼容性测试信息，请联系我们：