数字人SDK_虚拟数字人-阿里云帮助中心

数字人开放平台推出的适用于Android数字人流媒体服务SDK。当您调用服务端OpenAPI StartInstance接口获取RTC和IM参数信息后，可以在Android搭建App，实现数字人拉流和双工对话。AliyunAvatarSDK通过阿里云音视频通信服务（阿里云RTC）提供视频流的订阅，并通过标准WebSocket与服务端建立IM连接。

接入前须知

SDK不包含操作服务端实例的接口（如启动数字人、结束数字人、播报文本等功能），如有需要请参考OpenAPI文档；
Demo 需要依赖配合后端应用才能体验，请先确认建立好可以调用OpenAPI的后端应用。

接入方法

下载数字人AAR包，引入到工程中。
SDK 集成依赖导入。
获取设备相关权限。

集成SDK

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

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

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

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

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'

在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"/>

重要

对于敏感权限，如 Manifest.permission.WRITE_EXTERNAL_STORAGE 和 Manifest.permission.RECORD_AUDIO 等，需要在代码中调用Activity的requestPermissions方法获取运行时权限。
对于使用Android S 及以上系统的设备，还需要再动态申请 Manifest.permission.BLUETOOTH_CONNECT 权限，以保证RTC可以正确的初始化。
您需要在App《隐私权政策》中告知用户使用了AliRTC服务，具体告知方式详见：https://terms.aliyun.com/legal-agreement/terms/suit_bu1_ali_cloud/suit_bu1_ali_cloud202112151438_20307.html?spm=a2c4g.11186623.0.0.49fd18678NSHPJ

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

在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);

参数说明

参数	类型	必填	描述
context	Context	是	安卓（Android Activity）的上下文。
avatarSDKListener	AvatarSDKListener	是	SDK状态回调，详见参考“回调及监听”章节。
avatarInstanceInfo	AvatarInstanceInfo	是	构建Avatar实例的基本配置信息，完整参数见AvatarInstanceInfo
options	AvatarOptions	否	自定义的配置信息，包括WebSocket地址、音频3A算法配置等，完整参数配置见AvatarOptions

AvatarInstanceInfo

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

名称	类型	必填	描述	示例值
tenantId	String	是	租户id	10000
appId	String	是	应用id	1234ab56cd
sessionId	String	是	会话id	123a567b-8d9e-0fgh-ab1c-2345de6f7efg
token	String	创建互动数字人实例时必填	鉴权token ，注意是StartInstance外层返回的token，不是channel里的token	0202e9b8cf531740ac782e4c35e06c795941e88941e3ae1e46ec61c1fbf58a3a
channel	object	是	webrtc鉴权信息，详见Channel

Channel

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

名称	类型	必填	描述	示例值
channelId	String	是	频道ID	108293819
token	String	是	AliRTC令牌码。	e59f61b2482b4d0562ab542da3f824f7
gslb	array	是	AliRTC通道地址	["https://rgslb.rtc.aliyuncs.com"]
appId	String	是	AliRTC应用id	ONEX7E28C7C221854
userId	String	是	AliRTC生成的UserId	userId
nonce	String	是	AliRTC服务器生成的随机字符串	CK-9b5c335b9ae75879441ee7b363886418
expiredTime	ulong	是	AliRTC通道到期时间	1674128130551

AvatarOptions

高级功能自定义配置

名称	类型	必填	描述	默认值
wsUrl	String	否	建立im连接的websocket地址	wss://avatar-im.console.aliyun.com/ws
autoStartRecord	boolean	否	是否在初始化完成后自动开启录音	false
interval	int	否	音频采集间隔，单位毫秒，取值范围：60 - 1000，超出取值范围会直接抛出运行时异常	100
autoDodge	boolean	否	是否开启音频闪避	false
aecConfig	int	否	AEC配置，取值范围为： AvatarOptions.AEC_NONE 不开启AEC AvatarOptions.AEC_RTC使用WebRTC的AEC能力 AvatarOptions.AEC_SYSTEM 使用系统自带AEC（部分机型不支持）超出取值范围会直接抛出运行时异常	AvatarOptions.AEC_SYSTEM
audioSampleRate	int	否	音频采样率，取值范围为： AvatarOptions.SAMPLE_RATE_8K AvatarOptions.SAMPLE_RATE_16K 超出取值范围会直接抛出运行时异常	AvatarOptions.SAMPLE_RATE_16K
customAudioSource	boolean	否	是否开启自定义采集，默认false。	false
maxReconnectTimeout	long	否	断线重连最大尝试时间，超出这个时间仍未重连成功将抛出断线重连超时错误。单位毫秒。	300000
decodeMode	enum	否	可根据场景需求切换解码方式，使用硬件解码可降低一定的CPU负载。警告硬件解码仅支持部分设备，且无法自动切换为软件解码，在不兼容的设备上可能会出现黑屏等问题。因此请务必确认所使用设备的兼容性。	AvatarOptions.DecodeMode.SOFTWARE_DECODE

初始化

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

建立websocket连接，初始化数字人交互能力
进入rtc频道，拉取云端数字人音视频流

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

回调及监听

回调绑定

初始化绑定

private AvatarSDKListener avatarSDKListener = new AvatarSDKListener() {}

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

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

private AvatarSDKListener avatarSDKListener = new AvatarSDKListener() {}

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

重要

建议在初始化操作init()执行前绑定监听回调，否则可能会出现回调没有被触发的情况；

回调方法说明

API	描述	支持的最低版本
onInitSuccess	SDK初始化完成	1.0.0
onRecordingStart	收音开始回调	1.0.0
onRecordingStop	收音结束回调	1.0.0
onAsr	ASR识别文本回调	1.0.0
onAnswer	数字人回答文本回调	1.0.0
onError	错误回调	1.0.0
onUnknown	扩展回调	1.0.0

onInitSuccess：初始化成功回调

public void onInitSuccess(String uid, AliRtcEngine.AliRtcAudioTrack audioTrack, AliRtcEngine.AliRtcVideoTrack videoTrack);

参数	类型	描述
uid	String	数字人用户ID。
audioTrack	AliRtcAudioTrack	数字人用户发生变化后的音频流。
videoTrack	AliRtcVideoTrack	数字人用户发生变化后的视频流。

onRecordingStart：收音开始回调

public void onRecordingStart();

onRecordingStop：收音结束回调

public void onRecordingStop();

onAsr：ASR识别文本回调

public void onAsr(String asrResult,String sentenceId);

参数	类型	描述
asrResult	String	ASR识别文本
sentenceId	String	句子id

onAnswer：数字人回答文本回调

public void onAnswer(String answerResult, String sentenceId);

参数	类型	描述
answerResult	String	数字人回答文本
sentenceId	String	句子id

onError：错误回调

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

参数	类型	描述
errorCode	int	错误码
source	String	错误来源
errorMsg	String	错误信息

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

public void onUnknown(String msg);

参数	类型	描述
msg	String	可扩展的数据字段

开始收音

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

avatarSDK.startRecording();

结束收音

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

avatarSDK.stopRecording();

绿幕抠图

在虚拟数字人开放平台后台的背景配置为绿色背景时，可以将数字人背景透明化，透出自定义背景及可交互组件，如按钮等。

重要

绿幕抠图的接入方式与非绿幕抠图完全不同，用户需要根据自身业务情况使用对应的方式进行实现。若使用了绿幕抠图的接入方式，需要将StartInstance接口中的AlphaSwitch置为True。

接入流程

监听AliRtc视频裸数据回调
初始化绿幕抠图所依赖的TransparentSurfaceView
将视频裸数据渲染至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);
    }
});

重要

建议使用以下方法获取AliRtcEngine的状态回调，请勿直接调用AliRtcEngine的接口，否则会引起AvatarSDK的功能异常。

远端用户行为回调

//注意使用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.getDialogAvatarInstance(this, avatarSDKListener, avatarInstanceInfo, options);

运行时开启：

avatarSDK.setAutoDodge(true);

关闭：

avatarSDK.setAutoDodge(false);

自定义采集

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

avatarSDK.sendAudioBuffer(buffer);

重要

如果采集间隔<60ms 或者采集间隔>1000ms，会触发运行时错误
在启用自定义采集时，开始收音、结束收音、音频闪避、回声消除功能将不生效，onRecordingStart和onRecordingStop回调也不会触发

销毁实例

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

avatarSDK.destory();

重要

该方法仅仅销毁客户端实例，若要避免云端资源浪费，请调用OpenAPI的StopInstance接口

播报数字人