数字人流媒体服务AndroidSDK

接入前须知

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

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

3. 使用限制：

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

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

接入方法

1. 下载数字人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、AliRTC及fastjson三个库，您需要手动将相关依赖导入

implementation 'com.squareup.okhttp3:okhttp:4.4.1'
implementation 'com.alibaba:fastjson:1.2.83'
implementation 'com.aliyun.rtc:AliRTC-Full:2.5.7.0.22011719573410'

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.alivc.**{*;}

互动数字人

新建一个实例

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

参数说明

AvatarInstanceInfo

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

Channel

AliRTC所需要的鉴权信息，所有参数均可由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：初始化成功回调

public void onInitSuccess(String uid, AliRtcEngine.AliRtcAudioTrack audioTrack, AliRtcEngine.AliRtcVideoTrack 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();

透明背景

在启动数字人实例时若选择开启了透明通道，可以将数字人背景透明化，透出自定义背景及可交互组件，如按钮等。

接入流程

1. 监听AliRtc视频裸数据回调

2. 初始化透明背景所依赖的TransparentSurfaceView

3. 将视频裸数据渲染至TransparentSurfaceView上面

代码参考

以下为实现透明背景的核心代码，完整代码请参考Demo。

//监听AliRtc视频裸数据回调
privite void initAsBroadcastAvatar(){
    ...//
    mAliRtcEngine.registerVideoSampleObserver(mVideoObserver);
    ...
}

//初始化透明背景所依赖的TransparentSurfaceView
private void updateRemoteDisplayByGreenBackground() {
    ...
    surfaceView = new TransparentSurfaceView(AvatarActivity.this);
    surfaceView.init();
    ...
}

//将视频裸数据渲染至TransparentSurfaceView上面
private final AliRtcEngine.AliRtcVideoObserver mVideoObserver = new AliRtcEngine.AliRtcVideoObserver() {
    @Override
    public boolean onRemoteVideoSample(String callId, AliRtcEngine.AliRtcVideoSourceType sourceType, AliRtcEngine.AliRtcVideoSample videoSample) {
        ...
        if (surfaceView != null) {
            VideoRenderer.VideoRenderFrame frame = new VideoRenderer.VideoRenderFrame(RenderPixelFormat.I420,
                    videoSample.dataFrameY, videoSample.dataFrameU, videoSample.dataFrameV,
                    videoSample.width, videoSample.height,
                    videoSample.strideY, videoSample.strideU, videoSample.strideV);
            surfaceView.renderFrame(frame);
        }
        ...
        return super.onRemoteVideoSample(callId, sourceType, videoSample);
    }
};

文本互动

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

avatarSDK.sendMessage("你好");

高级功能

获取原始AliRTCEngine对象

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

AliRtcEngine mAliRtcEngine = avatarSDK.getAliRtcEngine();

设置AliRtcEngine的回调监听

• 本地用户行为回调

//注意使用avatarSDK实例，而非AliRTCEngine原始对象
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(AliRtcEngine.AliRtcConnectionStatus status, AliRtcEngine.AliRtcConnectionStatusChangeReason reason) {
        //必须调用super方法，否则AvatarSDK断线重连功能无法正常工作
        super.onConnectionStatusChange(status, reason);
    }

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

• 远端用户行为回调

//注意使用avatarSDK实例，而非AliRTCEngine原始对象
avatarSDK.setRtcEngineNotify(new AvatarRtcEngineNotify(context) {
    @Override
    public void onRemoteTrackAvailableNotify(String uid, AliRtcEngine.AliRtcAudioTrack audioTrack, AliRtcEngine.AliRtcVideoTrack videoTrack) {
        //必须调用super方法，否则AvatarSDK无法回调onInitSuccess
        super.onRemoteTrackAvailableNotify(uid, audioTrack, videoTrack);
    }
    @Override
    public void onBye(int code) {
        //必须调用super方法，否则AvatarSDKListener无法抛出相关异常信息
        super.onBye(code);
    }
});

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

avatarSDK.setAvatarRtcAudioObserver(new AvatarRtcAudioObserver() {
    @Override
    public void onCaptureRawData(AliRtcEngine.AliRtcAudioSample aliRtcAudioSample) {
        
    }
    
    @Override
    public void onCaptureData(AliRtcEngine.AliRtcAudioSample aliRtcAudioSample) {

    }
    @Override
    public void onRenderData(AliRtcEngine.AliRtcAudioSample aliRtcAudioSample) {

    }
    @Override
    public void onPlaybackAudioFrameBeforeMixing(String s, AliRtcEngine.AliRtcAudioSample aliRtcAudioSample) {
        
    }
});

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

avatarSDK.setAvatarRtcAudioVolumeObserver(new AvatarRtcAudioVolumeObserver() {
    @Override
    public void onAudioVolume(List<AliRtcEngine.AliRtcAudioVolume> speakers, int totalVolume) {
        super.onAudioVolume(speakers, totalVolume);
    }
    @Override
    public void onActiveSpeaker(String uid) {
        super.onActiveSpeaker(uid);
    }
});

音频闪避

自动检测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

AliRTC所需要的鉴权信息，所有参数均可由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, AliRtcEngine.AliRtcAudioTrack audioTrack, AliRtcEngine.AliRtcVideoTrack videoTrack);

• onError：错误回调

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

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

public void onUnknown(String msg);

透明背景

在启动数字人实例时若选择开启了透明通道，可以将数字人背景透明化，透出自定义背景及可交互组件，如按钮等。

接入流程

1. 监听AliRtc视频裸数据回调

2. 初始化透明背景所依赖的TransparentSurfaceView

3. 将视频裸数据渲染至TransparentSurfaceView上面

代码参考

以下为实现透明背景的核心代码，完整代码请参考Demo。

//监听AliRtc视频裸数据回调
privite void initAsBroadcastAvatar(){
    ...//
    mAliRtcEngine.registerVideoSampleObserver(mVideoObserver);
    ...
}

//初始化透明背景所依赖的TransparentSurfaceView
private void updateRemoteDisplayByGreenBackground() {
    ...
    surfaceView = new TransparentSurfaceView(AvatarActivity.this);
    ...
    surfaceView.init();
    ...
}

//将视频裸数据渲染至TransparentSurfaceView上面
private final AliRtcEngine.AliRtcVideoObserver mVideoObserver = new AliRtcEngine.AliRtcVideoObserver() {
    @Override
    public boolean onRemoteVideoSample(String callId, AliRtcEngine.AliRtcVideoSourceType sourceType, AliRtcEngine.AliRtcVideoSample videoSample) {
        ...
        if (surfaceView != null) {
            VideoRenderer.VideoRenderFrame frame = new VideoRenderer.VideoRenderFrame(RenderPixelFormat.I420,
                    videoSample.dataFrameY, videoSample.dataFrameU, videoSample.dataFrameV,
                    videoSample.width, videoSample.height,
                    videoSample.strideY, videoSample.strideU, videoSample.strideV);
            surfaceView.renderFrame(frame);
        }
        ...
        return super.onRemoteVideoSample(callId, sourceType, videoSample);
    }
};

高级功能

获取原始AliRTCEngine对象

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

AliRtcEngine mAliRtcEngine = avatarSDK.getAliRtcEngine();

设置AliRtcEngine的回调监听

• 本地用户行为回调

//注意使用avatarSDK实例，而非AliRTCEngine原始对象
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(AliRtcEngine.AliRtcConnectionStatus status, AliRtcEngine.AliRtcConnectionStatusChangeReason reason) {
        //必须调用super方法，否则AvatarSDK断线重连功能无法正常工作
        super.onConnectionStatusChange(status, reason);
    }

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

• 远端用户行为回调

//注意使用avatarSDK实例，而非AliRTCEngine原始对象
avatarSDK.setRtcEngineNotify(new AvatarRtcEngineNotify(context) {
    @Override
    public void onRemoteTrackAvailableNotify(String uid, AliRtcEngine.AliRtcAudioTrack audioTrack, AliRtcEngine.AliRtcVideoTrack videoTrack) {
        //必须调用super方法，否则AvatarSDK无法回调onInitSuccess
        super.onRemoteTrackAvailableNotify(uid, audioTrack, videoTrack);
    }
    @Override
    public void onBye(int code) {
    //必须调用super方法，否则AvatarSDKListener无法抛出相关异常信息
        super.onBye(code);
    }
});

销毁实例

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

avatarSDK.destory();

错误码表

音视频服务错误

触发onError回调时，source字段为"AliRtc"时，标志为RTC错误，详见《AliRTC错误码》。

数字人服务错误

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

常见问题

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

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

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