本文介绍如何在你的 Flutter 项目中集成和使用相芯美颜道具高级版的 Android 和 iOS 插件(以下简称“相芯美颜插件”)。
如果你需要分别开发 Android 和 iOS app,可以在原生项目中集成插件。
相芯美颜插件是对相芯 Nama SDK核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 或 setExtensionPropertyWithVendor 方法,传入指定的 key
和 value
参数,你可以快速集成相芯的美颜能力。
以 setExtensionProperty
为例,其中的 key
参数与相芯的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用 setExtensionProperty
时只要传入指定的 key
和 value
,就可以调用对应的相芯 API,实现美颜的有关功能。setExtensionPropertyWithVendor
同理。
如果你的目标平台为 iOS,你的开发环境需要满足以下需求:
如果你的目标平台为 Android,你的开发环境需要满足以下需求:
flutter doctor
命令检查开发环境和运行环境是否满足要求。参考实现视频通话(Flutter),集成视频 SDK v4.x 并实现基础的视频通话。
你需要在声网控制台购买和激活相芯美颜插件,并且联系声网提供你的包名(例如 yourCompany.yourProject.faceunity
)。随后你会收到与包名唯一对应的证书文件。
在 Flutter 项目中,你可以通过 Gradle 和 CocoaPods 分别集成原生的 Android 和 iOS 插件,然后调用声网 SDK 提供的 API 实现插件功能。
通过 Gradle 集成 Android 插件:
.aar
文件保存到项目文件夹,比如 android/libs
路径。android/app/build.gradle
文件,在 dependencies
中添加如下行:implementation fileTree(dir: "${rootProject.projectDir}/libs", include: ["*.aar"])
通过 CocoaPods 集成 iOS 插件:
.framework
文件导入项目。.podspec
文件中添加依赖,示例如下:Pod::Spec.new do |s|
s.name = 'Extensions'
s.version = '0.1.0'
s.summary = 'ByteDance effect plugin for声网 RTE extensions.'
s.description = 'project.description'
s.homepage = 'https://github.com/AgoraIO-Community/AgoraMarketPlace'
s.author = { 'Agora' => 'developer@agora.io' }
s.source = { :path => '.' }
s.vendored_frameworks = 'FURenderKit.framework', 'AgoraFaceUnityExtension.framework'
s.platform = :ios, '9.0'
end
Podfile
文件中添加如下行:pod 'Extensions', :path => "./"
添加证书文件:将插件包里的证书文件(authpack.java
或 authpack.h
)转换成 dart 语法,并保存到项目文件夹,比如 lib
路径。authpack.java
和 authpack.h
所包含的证书数据一样。以转换 authpack.h
文件为例,将文件内的数据复制到 List<int> gAuthPackage = [];
这一行的括号中即可:
/// 填写示例:List<int> gAuthPackage = [10, 13, -98, -100, 126, ...];
List<int> gAuthPackage = [Paste your authpack data];
点击下载相芯美颜插件的资源包,将所需的模型和道具 .bundle
文件通过 Flutter assets 的方式保存到项目文件夹,比如 Resource
路径。资源包中提供的文件详见更多参考。
在 pubspec.yaml
文件中添加依赖项,示例如下:
environment:
sdk: '>=2.18.6 <3.0.0'
dependencies:
flutter:
sdk: flutter
cupertino_icons: ^1.0.2
#声网 Flutter SDK 依赖项,请使用最新版本的 agora_rtc_engine
agora_rtc_engine: ^6.0.0
path_provider: ^2.0.11
permission_handler: ^8.3.0
path: ^1.8.0
# The following section is specific to Flutter packages.
flutter:
# 添加相芯资源文件依赖项
assets:
- Resource/graphics/aitype.bundle
- Resource/items/ItemSticker/CatSparks.bundle
- Resource/model/ai_face_processor.bundle
导入需要用到的 dart 文件:
import 'package:agora_rtc_engine/agora_rtc_engine.dart';
import 'authpack.dart' as authpack;
本节介绍插件相关接口的调用流程。接口的参数解释详见接口说明。
创建并初始化 RtcEngine
后,首先调用 enableExtension
启用插件,再调用其它 API(enableVideo
、joinChannel
等)。
// On Android, you should load libAgoraFaceUnityExtension.so explicitly
if (Platform.isAndroid) {
await _rtcEngine.loadExtensionProvider(path: 'AgoraFaceUnityExtension');
}
await _rtcEngine.enableExtension(
provider: "FaceUnity", extension: "Effect", enable: true);
收到声网 SDK 的 onExtensionStarted
回调后,调用 setExtensionProperty
并传入对应的 key 和 value,具体顺序如下:
fuSetup
,value 为证书文件 authpack 的数据。fuLoadAIModelFromPackage
,value 包含 AI 能力模型文件 ai_xxx.bundle
的路径以及 AI 能力类型。Future<void> _initFUExtension() async {
// 初始化
await _rtcEngine.setExtensionProperty(
provider: 'FaceUnity',
extension: 'Effect',
key: 'fuSetup',
value: jsonEncode({'authdata': authpack.gAuthPackage}));
// 加载 AI 模型
final aiFaceProcessorPath =
await _copyAsset('Resource/model/ai_face_processor.bundle');
await _rtcEngine.setExtensionProperty(
provider: 'FaceUnity',
extension: 'Effect',
key: 'fuLoadAIModelFromPackage',
// 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8
value: jsonEncode({'data': aiFaceProcessorPath, 'type': 1 << 8}));
}
调用 setExtensionProperty
并传入对应的 key 和 value,实现以下功能:
你可以根据场景需要进行组合调用。对应的 key 和 value 详见接口说明。
设置猫耳效果的示例如下:
Future<void> _setupCatSparksEffect() async {
final aiFaceProcessorPath =
await _copyAsset('Resource/model/ai_face_processor.bundle');
await _rtcEngine.setExtensionProperty(
provider: 'FaceUnity',
extension: 'Effect',
key: 'fuLoadAIModelFromPackage',
// 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8
value: jsonEncode({'data': aiFaceProcessorPath, 'type': 1 << 8}));
final catSparksPath =
await _copyAsset('Resource/items/ItemSticker/CatSparks.bundle');
await _rtcEngine.setExtensionProperty(
provider: 'FaceUnity',
extension: 'Effect',
key: 'fuCreateItemFromPackage',
value: jsonEncode({'data': catSparksPath}));
}
需要停止使用插件时,按照以下步骤释放资源:
setExtensionProperty
,传入 key 为 fuDestroyLibData
,释放插件占用的资源。fuDestroyLibData
回调后,调用 destroy
方法销毁 RtcEngine
对象。在 GitHub 上查看完整的示例代码和项目结构:
平台 | 语言 | 示例项目 |
---|---|---|
Flutter | Dart | FaceUnity/flutter |
插件相关所有接口的参数解释和错误码,参考接口说明。