数字人端渲染Android SDK

一、系统要求

• 系统版本：支持Android 8.0及以上版本。

• CPU类型：支持armeabi-v7a、arm64-v8a。

• 设备类型：仅限大屏设备，无法在手机端集成。

• 支持的数字人：仅支持3D数字人，暂不支持2D数字人。

• 硬件要求：需要高通845/RK3588同级别及以上的硬件水平。

二、集成步骤

1. 在项目中使用时，您需要把AvatarClientRenderSDK.aar放入app模块下的libs文件夹中，并在build.gradle文件中添加导入。

implementation fileTree(include: ['*.aar'], dir: 'libs')

2. AvatarClientRenderSDK强依赖于lifecycle-common、okhttp、fastjson、tea-openapi四个库，您需要手动将相关依赖导入。

 implementation 'androidx.lifecycle:lifecycle-common:2.4.0'
 implementation 'com.alibaba:fastjson:1.2.83'
 implementation 'com.squareup.okhttp3:okhttp:4.4.1'
 implementation 'com.aliyun:tea-openapi:0.3.0'

3. 此外，若需要打开远程日志及崩溃监测功能，还需要手动导入以下依赖。注意：开启远程日志功能会需要采集设备日志等信息，所有采集动作均使用阿里云移动研发平台Emas完成，所涉及到的用户信息采集可以参考Emas隐私权政策。

 implementation('com.aliyun.ams:alicloud-android-ha-adapter:1.1.5.2-open@aar') {
 transitive = true
 exclude group: 'com.squareup.okhttp3'
 exclude group: 'com.squareup.okio'
 }
 implementation('com.aliyun.ams:alicloud-android-tlog:1.1.4.4-open@aar') {
 transitive = true
 exclude group: 'com.squareup.okhttp3'
 exclude group: 'com.squareup.okio'
 }
 implementation('com.aliyun.ams:alicloud-android-ha-crashreporter:1.2.5')

4. 在app/src/main/AndroidManifest.xml文件中添加如下代码，获取相应的设备权限。

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

5. 在代码中将license文件拷贝到本地应用目录中，鉴权模块将读取应用目录中的文件信息进行鉴权。可以参考Demo工程中，MainActivitiy的 copyLicenseFile方法实现。

三、接口说明

3.1 接口清单

3.2 主流程接口

1. initSDK

初始化SDK，进行鉴权和初始化配置等

调用方式

avatarSDK = AvatarSDK.getInstance(context, avatarSDKListener);
// 1. 使用STS鉴权，推荐该方案
avatarSDK.initSDK(container, accessKeyId, accessKeySecret, securityToken, lifecycle, initConfig);
// 2. 直接使用账号的AKSK鉴权，需要客户端拿到AK&SK，可能存在安全风险，不推荐
//avatarSDK.initSDK(container, accessKeyId, accessKeySecret, lifecycle, initConfig);

参数说明

InitConfig说明

2. queryAvatarList

获取当前实例下的可用数字人角色列表。列表结果在onQueryAvatarListResult回调中返回。

调用方式

avatarSDK.queryAvatarList(1, 20);

参数说明

3. renderAvatar

根据avatarCode加载指定的数字人角色，若本地无角色相关素材，SDK会自动下载素材至本地。加载相关回调见onRenderAvatarStart、onRenderAvatarSuccess、onRenderAvatarFailure三个回调接口，下载相关回调见onAssetDownloadProgress、onAssetDownloadSuccess、onAssetDownloadFailure三个回调接口。

调用方式

avatarSDK.renderAvatar(code);

参数说明

4. sendMessage

播报一段文本，数字人会基于文本做TTS生成和表情动作驱动。

调用方式

avatarSDK.sendMessage(msg, uniqueCode);

参数说明

5. interruptPlay

打断当前播报并清空所有未播报、待播报数据，立即恢复到空闲状态。

avatarSDK.interruptPlay();

6. destroy

释放资源，断开Websocket链接，销毁Unity进程，请勿在主应用进程中调用，将会导致应用直接退出。

调用方式

avatarSDK.destroy();

3.3 配置接口

注：所有配置均建议在initSDK接口中的initConfig 字段中做初始化配置。

1. setVolume

调节播报音量

调用方式

avatarSDK.setVolume(value);

参数说明

2. setAvatarRotationY

指定数字人水平角度

调用方式

int rotation = 60;
avatarSDK.setAvatarRotationY(rotation);

参数说明

3. setCameraType

指定camera机位，包括全身、半身、特写等，枚举值见initSDK接口中的说明。

avatarSDK.setCameraType(CameraType.Default);

参数说明

4. setBackground

设置场景背景

调用方式

String path = "http://aaa.bbb/ccc.png"
avatarSDK.setBackground(imagePath);

参数说明

4

5. getAvatarConfig

获取上述所有配置的值，在回调接口的onGetAvatarConfig方法中返回。

调用方式

avatarSDK.getAvatarConfig()

返回示例

{
 "backgroundURL": "",
 "cameraType": "CAMERA_POS_BODY",
 "rotationY": 0,
 "useCrashReporter": true,
 "volume": 100
}

3.4 功能接口

1. isPlaying

查询当前播报状态

boolean isPlaying = avatarSDK.isPlaying();

2. clearCache

清除所有已下载到本地的文件，包括3D模型及背景图片等。

avatarSDK.clearCache();

3. downloadAvatar

下载指定数字人的资源到本地存储中，在下载回调接口中返回下载状态。

avatarSDK.downloadAvatar(code);

参数说明

4. getDeviceInfo

获取设备信息，包含当前设备的设备ID、设备类型

String deviceInfo = avatarSDK.getDeviceInfo();

3.5 回调接口

回调listener在生成SDK实例时传入

avatarSDK = AvatarSDK.getInstance(MainActivity.this, avatarSDKListener);

1. onInitResult (int code, String message)

在调用initSDK之后会触发的回调，返回SDK初始化结果，code为0时即为初始化成功。

2. onQueryAvatarListResult (String result)

在调用quaryAvatarList之后会触发的回调，返回可用的数字人角色列表。

返回数据示例:

{
 "list": [
 {
 "code": "CH_sBXSW4166SgVnECq",
 "name": "Jack",
 "portrait": "https://nuwa-live-image.oss-cn-beijing.aliyuncs.com/yun-vh/unity/MO_zTRB2XUWJu/20230816164605.411.png"
 }
 ],
 "pageNo": 1,
 "pageSize": 50,
 "totalCount": 9,
 "totalPage": 1
}

3. onRenderAvatarStart (String avatarCode)

开始渲染指定的数字人角色。

4. onRenderAvatarSuccess (String avatarCode)

数字人角色渲染成功。

5. onRenderAvatarFailure (String avatarCode, int errorCode, String message)

数字人角色渲染失败。

6. onAssetDownloadProgress (String avatarCode, int currentFileNum, int totalFileNum)

数字人资产下载进度。

参数说明：

7. onAssetDownloadSuccess (String avatarCode)

数字人资产下载成功。

8. onAssetDownloadFailure (String avatarCode, int errorCode, String errorMsg)

数字人资产下载失败。

9. onPlayStart(String uniqueCode）

播报开始。

10. onPlayEnd(String uniqueCode）

播报结束。

11. onGetAvatarConfig (String configJson)

当前的数字人及场景配置，在调用getAvatarConfig接口之后触发。

返回数据示例:

{
 "backgroundURL": "",
 "cameraType": "CAMERA_POS_BODY",
 "rotationY": 0,
 "useCrashReporter": true,
 "volume": 100
}

12. onError (int errorCode, String errorMsg)

异常回调，参考错误码说明。

四、错误码说明

五、常见问题

• Q：调用鉴权接口打印错误信息： errorMsg : code: 503, The request has failed due to a temporary failure of the server. request id:

• A：RAM用户没有访问数字人开放平台权限，需要赋予相应权限，参考《使用STS临时访问凭证调用虚拟数字人服务》

• Q：sdk 集成必须打开android.useAndroidX=true么？

• A：是的，如果有使用了support-v4、support-v7等依赖，需要在gradle.properties文件中添加android.enableJetifier=true

• Q：在初始化时有报错，sdk返回 16001000鉴权失败

• A：license文件没有被正确的复制，请参考Demo工程中的 copyLicenseFile方法实现。