Java API Reference for Android

概览

类	描述
RtcEngine	实时音视频的基础接口类。
IAvatarEngine	虚拟形象的基础接口类。
IAvatarEngineEventHandler	虚拟形象的回调接口类。
类型定义	虚拟形象接口的类型定义。

RtcEngine

实时音视频引擎。

queryAvatarEngine

创建 IAvatarEngine。

public abstract IAvatarEngine queryAvatarEngine();

返回值

• 方法调用成功，返回一个 IAvatarEngine 对象。
• 方法调用失败，返回值为空。

IAvatarEngine

虚拟形象的基础接口类，app 可调用主要方法实现元直播的相关功能。

initialize

初始化虚拟形象引擎。

public abstract int initialize(AvatarContext context);

请确保在调用其他 API 前先调用该方法创建并初始化 IAvatarEngine。

参数
context
初始化虚拟形象引擎时的配置参数。详见 AvatarContext。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

enableOrUpdateLocalAvatarVideo

创建或更新本地虚拟形象。

public abstract int enableOrUpdateLocalAvatarVideo(boolean enabled, AvatarConfigs configs);

调用该方法后，会触发 onLocalUserAvatarStarted 回调，异步返回创建或更新结果。

参数
enabled
是否创建或更新本地虚拟形象：

• true: 创建或更新本地虚拟形象。
• false: (默认) 不启用本地虚拟形象。

configs
创建或更新本地虚拟形象时的配置参数。详见 AvatarConfigs。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

getLocalUserAvatarOptions

获取本地虚拟形象的参数。

public abstract String getLocalUserAvatarOptions(String key, String args);

参数
key
指定获取的内容：

• request_dresslist: 获取本地虚拟形象的服装可选项。
• request_felist: 获取本地虚拟形象的捏脸可选项。

args
指定获取的范围：

• 传入空字符串，获取全部可选项的信息。
• 传入可选项 ID，获取指定可选项的信息。

返回值

• 方法调用成功：
  • 同步返回对应信息。当前同步回调暂不生效，仅做预留。
  • 触发 onLocalUserAvatarEvent 回调，异步返回对应信息。
• 方法调用失败，返回值为空。

setupLocalVideoCanvas

初始化虚拟形象的本地视图。

public abstract int setupLocalVideoCanvas(VideoCanvas canvas);

请确保在调用 joinChannel 方法加入频道前，先调用该方法。
调用本方法后，初始化效果仅供用户在本地设备上预览，不会对外发布。

参数
canvas
本地视频画布对象的属性。详见 VideoCanvas。
如需关闭虚拟形象的本地视图，可将 VideoCanvas 中的 view 属性设为 null。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

setLocalUserAvatarOptions

设置本地虚拟形象选项。

public abstract int setLocalUserAvatarOptions(String key, byte[] value);

参数
设置不同的功能选项，需将 key 和 value 指定为不同的值。具体见下表：

功能	key	value
设置渲染质量	set_quality	渲染质量分为 4 档： 0: (默认) low 1: medium 2: high 3: ultra
设置背景	set_bg	预置 3 种背景 (随机)： bg2d10001 bg2d10002 bg2d10003
面捕控制	playAniIdle：一定时间内捕捉不到人脸 信息输入时，调用虚拟形象休眠动画。	N/A
	resumeFaceTrack：恢复面捕。
开启/关闭换装	start_dress：(默认) 开启换装。	N/A
	stop_dress：关闭换装。
换装	send_dress: 穿戴指定换装项。	传入换装项的 ID。 示例：{\"id\":\"111071\"}。
	send_takeoff: 摘掉指定类型的换装项。	传入换装项的类型，详情参见 换装项类型映射表。 示例：{\"type\":\"53\"}。
开启/关闭捏脸	start_faceedit：(默认) 开启捏脸。	N/A
	stop_faceedit：关闭捏脸。
捏脸	send_felist	传入捏脸项 ID 和对应的捏脸系数，详情参见 捏脸项 ID 映射表。示例： {    "110203":0.5,    "110204":0.6,    "110205":0.5 }

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

registerEventHandler

添加虚拟形象引擎的事件回调。

public abstract int registerEventHandler(IAvatarEngineEventHandler handler);

参数
handler
待添加的回调句柄。详见 IAvatarEngineEventHandler。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

unregisterEventHandler

移除虚拟形象引擎的事件回调。

public abstract int unregisterEventHandler(IAvatarEngineEventHandler handler);

参数
handler
待移除的回调句柄。详见 IAvatarEngineEventHandler。

返回值

• 0: 方法调用成功。
• < 0: 方法调用失败。

IAvatarEngineEventHandler

虚拟形象的回调接口类，用于 SDK 向 app 发送事件通知。

onLocalUserAvatarStarted

本地虚拟形象创建回调。

public abstract void onLocalUserAvatarStarted(boolean success, int error_code, String msg);

调用 enableOrUpdateLocalAvatarVideo 方法后，会触发该回调，通知本地用户虚拟形象的创建结果。

参数
success
本地用户虚拟形象的创建结果：

• true: 创建成功。
• false: 创建失败。

error_code
错误码。

msg
错误描述。

常见的错误码和错误描述如下：

错误码	错误描述
ERR_OK (0)	创建成功。
ERR_FAILED (1)	一般性错误 (未明确归类)。
ERR_INVALID_ARGUMENT (2)	参数无效。
ERR_NOT_INITIALIZED (3)	SDK 尚未初始化。

onLocalUserAvatarError

本地虚拟形象异常回调。

public abstract void onLocalUserAvatarError(int err_code, String msg);

当用户的本地虚拟形象抛出异常时，会触发该回调，返回错误码及错误描述用于后续排查。

参数
err_code
错误码。

msg
错误描述。

常见的错误码和错误描述如下：

错误码	错误描述
ERR_OK (0)	创建成功。
ERR_FAILED (1)	一般性错误 (未明确归类)。
ERR_INVALID_ARGUMENT (2)	参数无效。
ERR_NOT_INITIALIZED (3)	SDK 尚未初始化。

onLocalUserAvatarEvent

获取本地虚拟形象参数回调。

public abstract void onLocalUserAvatarEvent(String key, String buf);

成功调用 getLocalUserAvatarOptions 方法后，会触发该回调，返回本地用户的可用服装列表和可用捏脸特性等。

参数

• 如获取本地用户的服装可选项，回调参数如下：
  • key: request_dresslist。
  • buf: 换装项类型、ID、名称等信息组成的 JSON 字符串，详情请参见 换装项类型映射表，示例如下：

{
  // "55" 和 "70" 为可选项的 type 类型。
  // "id" 表示可选项的 ID。
  // "name" 表示可选项的名称。
  // "icon" 后的 HTTPS 链接为图标的链接。
  // "isUsing" 表示当前是否穿戴。
    "55":[
            {"id":"55001","name":"眉毛1","icon":"https:\/\/store.gtx.fun\/avatar\/cjie\/icon\/55001.png","version":0,"tag":0,"status":0,"isUsing":0,"zOrder":0},
            {"id":"55002","name":"眉毛2","icon":"https:\/\/store.gtx.fun\/avatar\/cjie\/icon\/55002.png","version":0,"tag":0,"status":0,"isUsing":1,"zOrder":0}
        ],
    "70":[
            {"id":"70001","name":"发型1","icon":"https:\/\/store.gtx.fun\/avatar\/cjie\/icon\/70001.png","version":0,"tag":0,"status":0,"isUsing":0,"zOrder":0},
            {"id":"70002","name":"发型2","icon":"https:\/\/store.gtx.fun\/avatar\/cjie\/icon\/70002.png","version":0,"tag":0,"status":0,"isUsing":0,"zOrder":0},
        ]
}

• 如获取本地用户的捏脸可选项，回调参数如下：
  • key: request_felist。
  • buf: 捏脸项 ID 及对应捏脸系数组成的 JSON 字符串，详情请参见 换装项类型映射表。示例如下：

{
  // 前面的字符串表示捏脸项的 ID。
  // 后面的浮点数表示捏脸项对应的系数。
    "110203":0.5,
    "110204":0.6,
    "110205":0.5
}

类型定义

虚拟形象 API 的类型定义。

AvatarContext

虚拟形象引擎的配置参数。

public class AvatarContext {
  public String ai_appId;
  public String ai_license;
  public String renderer_appId;
}

属性
ai_appId
声网为 app 开发者签发的 App ID。

ai_license
第三方面捕服务的使用授权。

renderer_appId
第三方渲染服务签发的 App ID。

AvatarConfigs

虚拟形象的配置参数。

public class AvatarConfigs {
  public Constants.MediaSourceType mediaSource = Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE;
  public Context context;
  public boolean enable_face_detection = true;
  public boolean enable_human_detection = true;
  public Constants.AvatarProcessingMode mode =
      Constants.AvatarProcessingMode.AVATAR_PROCESSING_MODE_AVATAR;
};

属性
mediaSource
媒体源。详见 MediaSourceType。

context
安卓系统的 Activity。

enable_face_detection
是否开启面部表情捕捉：

• true: (默认)开启。
• false: 关闭。

enable_human_detection
预留属性，暂不生效。

mode
预留属性，暂不生效。