本文介绍如何在你的项目中集成和使用相芯美颜道具高级版插件(以下简称“相芯美颜插件”),包括 Android 和 iOS 平台。
你还可以在 Flutter 项目中集成原生的 Android 和 iOS 插件,具体步骤参考 Flutter 使用说明。
相芯美颜插件是对相芯 Nama SDK核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 或 setExtensionPropertyWithVendor 方法,传入指定的 key
和 value
参数,你可以快速集成相芯的美颜能力。
以 setExtensionProperty
为例,其中的 key
参数与相芯的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用 setExtensionProperty
时只要传入指定的 key
和 value
,就可以调用对应的相芯 API,实现美颜的有关功能。setExtensionPropertyWithVendor
同理。
在 GitHub 上查看完整的示例代码和项目结构:
平台 | 语言 | 示例项目 |
---|---|---|
Android | Java | FaceUnity/android |
iOS | Objective-C | FaceUnity/ios |
参考以下步骤快速跑通示例项目:
Android
git clone https://github.com/AgoraIO-Community/AgoraMarketplace.git
FaceUnity/android/README.md
文件完成后续步骤。iOS
git clone https://github.com/AgoraIO-Community/AgoraMarketplace.git
FaceUnity/ios/README.md
文件完成后续步骤。相芯美颜插件需要与声网视频 SDK v4.x 搭配使用。参考以下文档集成视频 SDK v4.x 并实现基础的视频通话:
你需要在声网控制台购买和激活相芯美颜插件,并且联系声网提供你的包名(例如 yourCompany.yourProject.faceunity
)。随后你会收到与包名唯一对应的证书文件,用于后续集成插件。
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
中添加如下行:implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
import 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;
iOS
// 项目文件夹示例
.
├── <ProjectName>
├── <ProjectName>.xcodeproj
└── Resource
.framework
文件导入项目,并将 Embed 修改为 Embed & Sign。authpack.h
引入你的 Xcode 项目。Resource
路径。资源包中提供的文件详见更多参考。#import <AgoraRtcKit/AgoraRtcEngineKit.h>
#import "authpack.h"
下面介绍插件相关接口的调用流程。接口的参数解释详见接口说明。
Android
创建并初始化 RtcEngine
后,首先调用 enableExtension
启用插件,再调用其它 API(enableVideo
、joinChannel
等)。
RtcEngineConfig config = new RtcEngineConfig();
// 加载插件
config.addExtension("AgoraFaceUnityExtension");
mRtcEngine = RtcEngine.create(config);
// 启用插件
mRtcEngine.enableExtension("FaceUnity", "Effect", enabled);
iOS
创建并初始化 AgoraRtcEngineKit
后,首先调用 enableExtensionWithVendor
启用插件,再调用其它 API(enableVideo
、joinChannelByToken
等)。
[self.agoraKit enableExtensionWithVendor:@"FaceUnity"
extension:@"Effect"
enabled:self.enable];
收到声网 SDK 的 onExtensionStarted
回调后,调用 setExtensionProperty
(Android)或 setExtensionPropertyWithVendor
(iOS)并传入对应的 key 和 value,具体顺序如下:
fuSetup
,value 为证书文件 authpack 的指针。fuLoadAIModelFromPackage
,value 包含 AI 能力模型文件 ai_xxx.bundle
的路径以及 AI 能力类型。Android
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);
}
iOS
- (void)loadAIModels {
[self.agoraKit
setExtensionPropertyWithVendor:@"FaceUnity"
extension:@"Effect"
key:@"fuLoadAIModelFromPackage"
value:[self toJson:@{
@"data": [[NSBundle mainBundle]
pathForResource:@"ai_face_processor"
ofType:@"bundle"],
// 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8
@"type": @(1 << 8)
}]];
[self.agoraKit
setExtensionPropertyWithVendor:@"FaceUnity"
extension:@"Effect"
key:@"fuLoadAIModelFromPackage"
value:[self toJson:@{
@"data": [[NSBundle mainBundle]
pathForResource:@"ai_hand_processor"
ofType:@"bundle"],
@"type": @(1 << 3)
}]];
[self.agoraKit
setExtensionPropertyWithVendor:@"FaceUnity"
extension:@"Effect"
key:@"fuLoadAIModelFromPackage"
value:[self toJson:@{
@"data": [[NSBundle mainBundle]
pathForResource:@"ai_human_processor_gpu"
ofType:@"bundle"],
@"type": @(1 << 9)
}]];
[self.agoraKit
setExtensionPropertyWithVendor:@"FaceUnity"
extension:@"Effect"
key:@"fuCreateItemFromPackage"
value:[self toJson:@{
@"data": [[NSBundle mainBundle]
pathForResource:@"aitype"
ofType:@"bundle"]
}]];
[self.agoraKit
setExtensionPropertyWithVendor:@"FaceUnity"
extension:@"Effect"
key:@"fuItemSetParam"
value:[self toJson:@{
@"obj_handle": [[NSBundle mainBundle]
pathForResource:@"aitype"
ofType:@"bundle"],
@"name": @"aitype",
@"value": @(1 << 8 | 1 << 30 | 1 << 3),
}]];
}
调用 setExtensionProperty
(Android)或 setExtensionPropertyWithVendor
(iOS)并传入对应的 key 和 value,实现以下功能:
你可以根据场景需要进行组合调用。对应的 key 和 value 详见接口说明。
需要停止使用插件时,按照以下步骤释放资源:
setExtensionProperty
(Android)或 setExtensionPropertyWithVendor
(iOS),传入 key 为 fuDestroyLibData
,释放插件占用的资源。fuDestroyLibData
回调后,调用 destroy
方法销毁 RtcEngine
(Android)或 AgoraRtcEngineKit
(iOS) 对象。插件相关所有接口的参数解释和错误码,参考接口说明。
1. 运行示例项目,美颜为什么没有生效?
通常有以下几个原因:
2. 为什么开启采集后需要 1s 左右才能渲染出视频?
加载相芯美颜资源的操作会造成 GL 渲染线程卡顿,加载资源的过程大概耗时 800ms。建议通过业务处理(比如添加 loading 界面)规避。