数字人流媒体服务AndroidSDK

SDK 1.2.2升级说明

接入前须知

1. SDK不包含操作服务端实例的接口（如启动数字人、结束数字人、播报文本等功能），如有需要请参考OpenAPI文档；

2. Demo 需要依赖配合后端应用才能体验，请先确认建立好可以调用OpenAPI的后端应用。

3. 使用限制：

   1. 系统版本：支持Android 6.0，API 23及以上版本。

   2. CPU架构：支持armeabi-v7a、arm64-v8a。

接入方法

1. 下载数字人示例工程，SDK AAR包为示例工程的libs/AliyunAvatarSDK_1.2.2.aar。

2. SDK 集成依赖导入。

3. 获取设备相关权限。

集成SDK

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

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

2. 在根目录的build.gradle中添加Maven仓库地址：

allprojects {
  repositories {
    google()
    jcenter()
    //添加如下的Maven地址
    maven {
      url "http://maven.aliyun.com/nexus/content/groups/public/"
    }
  }
}

3. AliyunAvatarSDK依赖于OkHttp、DingRTC及fastjson三个库，您需要手动将相关依赖导入

implementation 'com.squareup.okhttp3:okhttp:4.4.1'
implementation 'com.alibaba:fastjson:1.2.83'
implementation 'com.ding.rtc:dingrtc-full:3.7.5'

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

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/> 

5. 可选：配置防止代码混淆。

在proguard-rules.pro文件中，添加-keep类的配置，可以防止混淆RTC SDK公共类名称。

-keep class com.serenegiant.**{*;}
-keep class org.webrtc.**{*;}
-keep class com.ding.rtc.**{*;}
-keep class com.alivc.**{*;}
-keep class com.aliyun.avatarsdk.**{*;}

互动数字人

新建一个实例

AvatarSDK avatarSDK = AvatarSDK.createDialogAvatarInstance(context,
                                            avatarSDKListener, 
                                            avatarInstanceInfo, 
                                            options);

参数说明

AvatarInstanceInfo

数字人应用基本信息，参数可由虚拟数字人开放平台-开发者信息获取

Channel

DingRTC所需要的鉴权信息，所有参数均可由StartInstance接口获得。

AvatarOptions

高级功能自定义配置

初始化

初始化调用会执行以下操作：

1. 建立websocket连接，初始化数字人交互能力

2. 进入rtc频道，拉取云端数字人音视频流

AvatarSDK avatarSDK = AvatarSDK.createDialogAvatarInstance(this, avatarSDKListener, avatarInstanceInfo,options);
avatarSDK.init();

回调及监听

回调绑定

• 初始化绑定

private AvatarSDKListener avatarSDKListener = new AvatarSDKListener() {}

@Override
protected void onCreate(Bundle savedInstanceState) {
	AvatarSDK avatarSDK = AvatarSDK.createDialogAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, options);
	avatarSDK.init();
}

• 除了在构造函数绑定监听回调外，还可以通过实例实时绑定监听回调；

private AvatarSDKListener avatarSDKListener = new AvatarSDKListener() {}

@Override
protected void onCreate(Bundle savedInstanceState) {
	AvatarSDK avatarSDK = AvatarSDK.createDialogAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, options);
	avatarSDK.setAvatarSDKListener(avatarSDKListener);
	avatarSDK.init();
}

回调方法说明

• onInitSuccess：初始化成功回调

onInitSuccess(String uid, DingRtcAudioTrack audioTrack, DingRtcVideoTrack videoTrack);

• onRecordingStart：收音开始回调

public void onRecordingStart();

• onRecordingStop：收音结束回调

public void onRecordingStop();

• onAsr：ASR识别文本回调

public void onAsr(String asrResult,String sentenceId);

• onAnswer：数字人回答文本回调

public void onAnswer(String answerResult, String sentenceId);

• onError：错误回调

public void onError(int errorCode,String source, String errorMsg);

• onUnknown：扩展回调，由IM消息通道下发的，不属于上述任何类型的数据，均会通过onUnknown对外回调

public void onUnknown(String msg);

开始收音

开始使用麦克风采集音频数据，并向服务端发送数据，自定义采集模式下不可用

avatarSDK.startRecording();

结束收音

停止使用麦克风采集音频数据，并停止向服务端发送数据，自定义采集模式下不可用

avatarSDK.stopRecording();

文本互动

使用文本与数字人进行对话互动。

avatarSDK.sendMessage("你好");

高级功能

获取原始DingRtcEngine对象

获取原始DingRtcEngine对象，可使用RTC高级功能

DingRtcEngine mAliRtcEngine = avatarSDK.getAliRtcEngine();

设置DingRtcEngine的回调监听

• 本地用户行为回调

//注意使用avatarSDK实例，而非DingRTCEngine原始对象
avatarSDK.setRtcEngineEventListener(new AvatarRtcEngineEventListener(context) {
    @Override
    public void onJoinChannelResult(int result, String channel, String userId, int elapsed) {
        //必须调用super方法，否则AvatarSDK断线重连功能无法正常工作
        super.onJoinChannelResult(result, channel, userId, elapsed);
    }

    @Override
    public void onConnectionStatusChange(DingRtcEngine.DingRtcConnectionStatus status, DingRtcEngine.DingRtcConnectionStatusChangeReason reason) {
        //必须调用super方法，否则AvatarSDK断线重连功能无法正常工作
        super.onConnectionStatusChange(status, reason);
    }

    @Override
    public void onOccurError(int error, String message) {
        //必须调用super方法，否则AvatarSDKListener无法抛出相关异常信息
        super.onOccurError(error, message);
    }
    
    @Override
    public void onAudioVolumeIndication(List<DingRtcAudioVolumeInfo> speakers) {
        super.onAudioVolumeIndication(speakers);
    }
});

• 远端用户行为回调

setRtcEngineEventListener(new AvatarRtcEngineEventListener() {
    @Override
    public void onJoinChannelResult(int result, String channel, String userId, int elapsed) {
        super.onJoinChannelResult(result, channel, userId, elapsed);
        Log.d(TAG, "onJoinChannelResult:" + result + ";channel:" + channel);
    }

    @Override
    public void onConnectionStatusChanged(DingRtcEngine.DingRtcConnectionStatus status, DingRtcEngine.DingRtcConnectionStatusChangeReason reason) {
        super.onConnectionStatusChanged(status, reason);
    }

    @Override
    public void onOccurError(int error, String message) {
        super.onOccurError(error, message);
    }

    @Override
    public void onAudioVolumeIndication(List<DingRtcAudioVolumeInfo> speakers) {
        super.onAudioVolumeIndication(speakers);
    }
});

• 获取音频裸数据回调，替代DingRtcEngine().registerAudioObserver()

avatarSDK.setAvatarRtcAudioObserver(new AvatarRtcAudioObserver() {
    @Override
    public void onCaptureRawData(DingRtcAudioFrame aliRtcAudioSample) {
        
    }

    @Override
    public void onCaptureData(DingRtcAudioFrame aliRtcAudioSample) {

    }

    @Override
    public void onRenderData(DingRtcAudioFrame aliRtcAudioSample) {

    }

    @Override
    public void onPlaybackAudioFrameBeforeMixing(String s, DingRtcAudioFrame aliRtcAudioSample) {

    }
});

• 音量回调，替代DingRtcEngine().registerAudioVolumeObserver()

  重要

  SDK 1.2.2之后请使用setRtcEngineEventListener监听音量回调

音频闪避

自动检测RTC视频流数字人说话暂停收音，默认关。

• 初始化开启：

AvatarOptions options = new AvatarOptions.Builder().autoDodge(true).build();
AvatarSDK avatarSDK = AvatarSDK.createDialogAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, options);

• 运行时开启：

avatarSDK.setAutoDodge(true);

• 关闭：

avatarSDK.setAutoDodge(false);

自定义采集

发送业务自定义采集的音频数据

avatarSDK.sendAudioBuffer(buffer);

销毁实例

断开rtc拉流、断开im连接、停止录音，销毁客户端实例；

avatarSDK.destory();

播报数字人

新建一个实例

AvatarSDK avatarSDK = AvatarSDK.createBroadcastAvatarInstance(context,
                                                           avatarSDKListener,
                                                           avatarInstanceInfo,
                                            			   options);

参数说明

AvatarInstanceInfo

数字人应用基本信息，参数可由虚拟数字人开放平台-开发者信息获取

Channel

DingRTC所需要的鉴权信息，所有参数均可由StartInstance接口获得。

AvatarOptions

高级功能自定义配置

初始化

初始化调用会执行"进入rtc频道，拉取云端数字人音视频流".

AvatarSDK avatarSDK = AvatarSDK.createBroadcastAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, null);
avatarSDK.init();

回调及监听

回调绑定

• 初始化绑定

private AvatarSDKListener avatarSDKListener = new AvatarSDKListener() {}

@Override
protected void onCreate(Bundle savedInstanceState) {
	AvatarSDK avatarSDK = AvatarSDK.createBroadcastAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, options);
	avatarSDK.init();
}

• 除了在构造函数绑定监听回调外，还可以通过实例实时绑定监听回调；

private AvatarSDKListener avatarSDKListener = new AvatarSDKListener() {}

@Override
protected void onCreate(Bundle savedInstanceState) {
	AvatarSDK avatarSDK = AvatarSDK.createBroadcastAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, options);
	avatarSDK.setAvatarSDKListener(avatarSDKListener);
	avatarSDK.init();
}

回调方法说明

• onInitSuccess：初始化成功回调

public void onInitSuccess(String uid, DingRtcAudioTrack audioTrack, DingRtcVideoTrack videoTrack);

• onError：错误回调

public void onError(int errorCode,String source, String errorMsg);

• onUnknown：扩展回调，由IM消息通道下发的，不属于上述任何类型的数据，均会通过onUnknown对外回调

public void onUnknown(String msg);

高级功能

获取原始DingRtcEngine对象

获取原始DingRtcEngine对象，可使用RTC高级功能

DingRtcEngine mAliRtcEngine = avatarSDK.getAliRtcEngine();

设置DingRtcEngine的回调监听

• 本地用户行为回调

//注意使用avatarSDK实例，而非DingRTCEngine原始对象
avatarSDK.setRtcEngineEventListener(new AvatarRtcEngineEventListener() {
    @Override
    public void onJoinChannelResult(int result, String channel, String userId, int elapsed) {
        super.onJoinChannelResult(result, channel, userId, elapsed);
        Log.d(TAG, "onJoinChannelResult:" + result + ";channel:" + channel);
    }

    @Override
    public void onConnectionStatusChanged(DingRtcEngine.DingRtcConnectionStatus status, DingRtcEngine.DingRtcConnectionStatusChangeReason reason) {
        super.onConnectionStatusChanged(status, reason);
    }

    @Override
    public void onOccurError(int error, String message) {
        super.onOccurError(error, message);
    }

    @Override
    public void onAudioVolumeIndication(List<DingRtcAudioVolumeInfo> speakers) {
        super.onAudioVolumeIndication(speakers);
    }
});

• 远端用户行为回调

//注意使用avatarSDK实例，而非DingRTCEngine原始对象
avatarSDK.setRtcEngineEventListener(new AvatarRtcEngineEventListener() {
    @Override
    public void onJoinChannelResult(int result, String channel, String userId, int elapsed) {
        super.onJoinChannelResult(result, channel, userId, elapsed);
        Log.d(TAG, "onJoinChannelResult:" + result + ";channel:" + channel);
    }

    @Override
    public void onConnectionStatusChanged(DingRtcEngine.DingRtcConnectionStatus status, DingRtcEngine.DingRtcConnectionStatusChangeReason reason) {
        super.onConnectionStatusChanged(status, reason);
    }

    @Override
    public void onOccurError(int error, String message) {
        super.onOccurError(error, message);
    }

    @Override
    public void onAudioVolumeIndication(List<DingRtcAudioVolumeInfo> speakers) {
        super.onAudioVolumeIndication(speakers);
    }
});

销毁实例

断开rtc拉流、断开im连接、停止录音，销毁客户端实例；

avatarSDK.destory();

错误码表

音视频服务错误

触发onError回调时，source字段包含"Rtc"时，标志为RTC错误，详见《DingRTC错误码表》。

数字人服务错误

触发onError回调时，source字段为"Avatar"时，标志为数字人服务错误，详见下表

常见问题

1. 目前拉到的流是一个全屏大小的流，如何适配到自定义尺寸的容器中？

   需要对容器的布局属性进行调整。参考Demo中AvatarActivity的设置方法。若没有开启透明背景，可以修改updateRemoteDisplay方法中的LayoutParams来进行调整；若开启了透明背景，则需要修改 updateRemoteDisplayByGreenBackground 方法中的LayoutParams来调整。因为视频流的比例是固定的，建议等比缩放试，使用其他比例的容器布局可能会有裁剪。示例代码如下：

   RelativeLayout.LayoutParams layout = new RelativeLayout.LayoutParams(1080, 1920);