使用说明
本文介绍如何在你的项目中集成和使用相芯美颜道具高级版插件。
技术原理
相芯美颜道具高级版插件是对相芯 Nama SDK 核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty
方法,传入指定的 key
和 value
参数,你可以快速集成相芯的美颜能力。
setExtensionProperty
方法的 key
参数与相芯的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用该方法时只要传入指定的 key
和 value
,就可以调用对应的相芯 API,实现美颜的有关功能。
前提条件
Android 开发环境需满足以下要求:
- Android Studio 4.1 以上版本。
- 运行 Android 5.0 或以上版本的真机(非模拟器)。
示例项目
声网云市场提供了相芯美颜道具高级版插件 Android、iOS 和 Flutter 的示例代码,你可以前往插件详情页克隆或下载并进行体验。
集成和调用流程
1. 集成 SDK 和插件
开始前,你需要在项目中分别集成声网视频 SDK 和相芯美颜道具高级版插件。
1.1 使用声网 SDK 实现音视频互动
插件需要与 RTC SDK 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动:
1.2 购买和激活插件
你需要进入声网控制台 > 云市场页面,按照提示购买相芯美颜道具高级版插件,并且联系声网提供你的包名(例如 yourCompany.yourProject.faceunity
)。随后你会收到与包名唯一对应的证书文件,用于后续集成插件。
1.3 集成插件
参考以下步骤集成插件:
-
进入声网控制台 > 云市场页面,下载相芯美颜道具高级版的 Android 插件动态库压缩包。
-
解压文件夹,将所有
.aar
文件保存到项目文件夹,比如/app/libs
路径。 -
将证书文件
authpack.java
保存到你在获取证书文件时提供的包名所对应的路径下(例如:获取证书文件时提供的包名为io.agora.rte.extension.faceunity.example
,那么证书文件需要保存到/app/src/main/java/io/agora/rte/extension/faceunity/example
路径)。 -
点击下载相芯美颜插件的资源包,将所需的模型和道具文件保存到项目文件夹,比如
/app/src/main/assets/Resource
路径。资源包中提供的文件详见参考信息。 -
打开
app/build.gradle
文件,在dependencies
中添加如下行:Javaimplementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
-
导入需要用到的类:
Javaimport io.agora.rtc2.Constants;
import io.agora.rtc2.IMediaExtensionObserver;
import io.agora.rtc2.IRtcEngineEventHandler;
import io.agora.rtc2.RtcEngine;
import io.agora.rtc2.RtcEngineConfig;
import io.agora.rtc2.video.VideoCanvas;
import io.agora.rte.extension.faceunity.ExtensionManager;
1.4 升级插件
声网云市场推荐你更新插件版本前使用数据库工具 (如 SQLite) 来实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。
以下是用 SQLite 来进行插件版本管理的示例:
- 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
- 每次项目初始化时,自动检测当前项目使用的资源包版本:
- 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。
- 如果记录的资源包版本与当前匹配,则正常实现业务。
如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。
以下升级流程以相芯美颜特效插件为例:
-
参考集成插件章节下载所需平台最新版本的插件包和资源包。
-
删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
-
删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。
编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。
2. 启用插件
创建并初始化 RtcEngine
后,首先调用 enableExtension
启用插件,再调用其它 API(enableVideo
、joinChannel
等)。
RtcEngineConfig config = new RtcEngineConfig();
// 加载插件
config.addExtension("AgoraFaceUnityExtension");
mRtcEngine = RtcEngine.create(config);
// 启用插件
mRtcEngine.enableExtension("FaceUnity", "Effect", enabled);
3. 初始化插件
收到声网 SDK 的 onExtensionStarted
回调后,调用 setExtensionProperty
并传入对应的 key
和 value
,具体顺序如下:
- 初始化。对应的
key
为fuSetup
,value
为证书文件 authpack 的指针。 - 加载 AI 模型。对应的
key
为fuLoadAIModelFromPackage
,value
包含 AI 能力模型文件ai_xxx.bundle
的路径以及 AI 能力类型。
private void initExtension() {
// 初始化
try {
JSONObject jsonObject = new JSONObject();
JSONArray jsonArray = new JSONArray();
for (byte it : authpack.A()) {
jsonArray.put(it);
}
jsonObject.put("authdata", jsonArray);
setExtensionProperty("fuSetup", jsonObject.toString());
} catch (JSONException e) {
Log.e(TAG, e.toString());
}
// 加载 AI 模型
File modelDir = new File(getExternalFilesDir("assets"),
"face_unity/model/ai_face_processor.bundle");
try {
JSONObject jsonObject = new JSONObject();
jsonObject.put("data", modelDir.getAbsolutePath());
// 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8
jsonObject.put("type", 1 << 8);
setExtensionProperty("fuLoadAIModelFromPackage", jsonObject.toString());
} catch (JSONException e) {
Log.e(TAG, e.toString());
}
}
// 方便多次调用 setExtensionProperty
private void setExtensionProperty(String key, String property) {
mRtcEngine.setExtensionProperty("FaceUnity", "Effect", key, property);
}
4. 设置美颜效果和人体识别
设置美颜效果需要调用 setExtensionProperty
并传入对应的 key
和 value
,实现以下功能:
- 加载道具、调节美颜强度
- 人脸、手势和人体识别
你可以根据场景需要进行组合调用。相关的 key
和 value
详见 key-value 说明。
5. 释放资源
需要停止使用插件时,按照以下步骤释放资源:
- 调用
setExtensionProperty
并传入key
为fuDestroyLibData
,释放插件占用的资源。 - 收到
fuDestroyLibData
回调后,调用destroy
方法销毁RtcEngine
对象。
参考信息
API 参考
常见问题
问题 1:运行示例项目,美颜为什么没有生效?
通常有以下几个原因:
- 插件动态库没有保存在正确位置,或者没有导入;
- 相芯资源包中的文件没有保存在正确位置,或者缺少部分文件;
- 证书文件与 App 包名不一致,导致鉴权失败。
问题 2:为什么开启采集后需要 1s 左右才能渲染出视频?
加载相芯美颜资源的操作会造成 GL 渲染线程卡顿,加载资源的过程大概耗时 800ms。建议通过业务处理(比如添加 loading 界面)规避。
问题 3:为什么在编译 App 时会出现 models: no match
的报错?
该错误通常是由于资源包匹配问题引起的。很可能是因为在编译新插件时,没有删除旧版本的 App。建议你删除旧版 App 后重新编译运行。
素材包结构
相芯美颜道具高级版插件的资源包文件结构详见:
更多的接口调用方式可以参考相芯 Nama SDK 的文档: