本文介绍如何在你的项目中集成和使用火山引擎智能美化特效插件,包括 Android 和 iOS 平台。
火山引擎智能美化特效插件是对火山引擎 AI 开放平台 CV SDK核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 或 setExtensionPropertyWithVendor 方法,传入指定的 key
和 value
参数,你可以快速集成火山引擎的美化特效能力。
以 setExtensionProperty
为例,其中的 key
参数与火山引擎的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用 setExtensionProperty
时只要传入指定的 key
和 value
,就可以调用对应的火山引擎 API,实现美化特效的有关功能。setExtensionPropertyWithVendor
同理。
火山引擎智能美化特效插件需要与声网视频 SDK v4.x 搭配使用。参考以下文档集成视频 SDK v4.x 并实现基础的视频通话:
Android
.aar
文件保存到项目文件夹的 /app/libs
路径。/app/src/main/assets
路径。素材包中提供的文件详见素材包结构说明。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.bytedance.ExtensionManager;
iOS
Resource
文件夹,位置如下:.
├── <ProjectName>
├── <ProjectName>.xcodeproj
│ ├── project.pbxproj
│ ├── project.xcworkspace
│ └── xcshareddata
└── Resource
.framework
包保存到 <ProjectName>
路径下。Resource
路径下。素材包中提供的文件详见素材包结构说明。 #import <AgoraRtcKit/AgoraRtcEngineKit.h>
#import "BDResourceHelper.h"
本节介绍插件相关接口的调用流程。接口的参数解释详见接口说明。
Android
初始化 RtcEngine
时,调用 enableExtension
启用插件。
RtcEngineConfig config = new RtcEngineConfig();
// 监听插件事件,用于接收 onEvent 回调
config.mExtensionObserver = this;
config.addExtension("AgoraByteDanceExtension");
mRtcEngine = RtcEngine.create(config);
// 开启插件
mRtcEngine.enableExtension("ByteDance", "Effect", enabled);
iOS
初始化 AgoraRtcEngineKit
时,调用 enableExtensionWithVendor
启用插件。
AgoraRtcEngineConfig *config = [AgoraRtcEngineConfig new];
// 监听插件事件,用于接收 onEvent 回调
config.eventDelegate = self;
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithConfig:config
delegate:self];
// 开启插件
[self.agoraKit enableExtensionWithVendor:@"ByteDance"
extension:@"Effect"
enabled:self.enable];
初始化插件需要调用 setExtensionProperty
(Android)或 setExtensionPropertyWithVendor
(iOS)并传入对应的 key 和 value,具体顺序如下:
bef_effect_ai_check_license
,value 为授权文件 LicenseBag.bundle
的路径。授权文件位于素材包内。bef_effect_ai_init
,value 包含算法模型文件 ModelResource.bundle
的路径和设备名。算法模型文件位于素材包内。Android
private void initExtension() {
String[] resources = new String[] {"byte_dance/LicenseBag.bundle", "byte_dance/ModelResource.bundle"};
loadBundle(resources, () -> {
File destFile = getExternalFilesDir(null);
// 获取授权文件的路径
File licensePath = new File(
destFile,
"byte_dance/LicenseBag.bundle/" + io.agora.rte.extension.bytedance.example.Constants.mLicenseName);
// 检查授权
try {
JSONObject jsonObject = new JSONObject();
jsonObject.put("licensePath", licensePath.getPath());
setExtensionProperty("bef_effect_ai_check_license", jsonObject.toString());
} catch (JSONException e) {
Log.e(TAG, e.toString());
}
// 获取算法模型文件的路径
File strModelDir = new File(destFile, "byte_dance/ModelResource.bundle");
// 初始化特效
try {
JSONObject jsonObject = new JSONObject();
jsonObject.put("strModelDir", strModelDir.getPath());
jsonObject.put("deviceName", "");
setExtensionProperty("bef_effect_ai_init", jsonObject.toString());
} catch (JSONException e) {
Log.e(TAG, e.toString());
}
});
}
// 方便多次调用 setExtensionProperty
private void setExtensionProperty(String key, String property) {
mRtcEngine.setExtensionProperty("ByteDance", "Effect", key, property);
}
iOS
- (IBAction)initExtension:(id)sender {
NSError *error;
NSData *data = [NSJSONSerialization
dataWithJSONObject:@{@"licensePath": [self.resourceHelper licensePath]}
options:NSJSONWritingPrettyPrinted
error:&error];
// 检查授权
[self.agoraKit
setExtensionPropertyWithVendor:@"ByteDance"
extension:@"Effect"
key:@"bef_effect_ai_check_license"
value:[[NSString alloc]
initWithData:data
encoding:NSUTF8StringEncoding]];
data = [NSJSONSerialization dataWithJSONObject:@{
@"strModelDir": [self.resourceHelper modelDirPath],
@"deviceName": @""
}
options:NSJSONWritingPrettyPrinted
error:&error];
// 初始化特效
[self.agoraKit
setExtensionPropertyWithVendor:@"ByteDance"
extension:@"Effect"
key:@"bef_effect_ai_init"
value:[[NSString alloc]
initWithData:data
encoding:NSUTF8StringEncoding]];
data =
[NSJSONSerialization dataWithJSONObject:@{@"mode": @1, @"orderType": @0}
options:NSJSONWritingPrettyPrinted
error:&error];
}
设置美颜效果需要调用 setExtensionProperty
(Android)或 setExtensionPropertyWithVendor
(iOS)并传入对应的 key 和 value,目前支持以下功能:
你可以根据场景需要进行组合调用。对应的 key 和 value 详见接口说明。
在 GitHub 上查看完整的示例代码和项目结构:
平台 | 语言 | 示例代码 |
---|---|---|
Android | Java | ByteDance/android |
iOS | Objective-C | ByteDance/ios |
Android
克隆仓库:
git clone https://github.com/AgoraIO-Community/AgoraMarketPlace.git
进入声网控制台 > 云市场 >火山引擎智能美化特效页面,点击下载 Android 插件包,然后点击联系我们获取专属的证书文件(.licbag
)。
解压下载的 Android 插件包,将所有 .aar
文件保存到项目文件夹的 ByteDance/android/app/libs
路径。
点击下载火山引擎智能美化特效插件的素材包,将所有文件保存到 ByteDance/android/app/src/main/assets/Resource
路径。素材包中提供的文件详见素材包结构说明。
在 Android Studio 中打开示例项目 ByteDance/android
。
将项目与 Gradle 文件同步。
将你的证书文件(.licbag
)保存在 ByteDance/android/app/src/main/assets/LicenseBag.bundle
路径下。
打开 Config.java
文件,进行如下修改:
<YOUR_APP_ID>
替换为你的 App ID。获取 App ID 请参考开始使用声网平台。<YOUR_LICENSE_NAME>
替换为你的证书文件名称。例如:证书文件为 bytedance_4.2.3.licbag
,则在这里填入bytedance_4.2.3.licbag
。public interface Config {
String mAppId = "<YOUR_APP_ID>";
String mToken = null;
String mLicenseName = "<YOUR_LICENSE_NAME>";
}
连接一台 Android 真机(非模拟器),运行项目。
iOS
克隆仓库:
git clone https://github.com/AgoraIO-Community/AgoraMarketPlace.git
进入声网控制台 > 云市场 >火山引擎智能美化特效页面,点击下载 iOS 插件包,然后点击联系我们获取专属的证书文件(.licbag
)。
点击下载火山引擎智能美化特效插件的素材包,将所有文件保存到 ByteDance/ios/Resource
路径。素材包中提供的文件详见素材包结构说明。
将你的证书文件(.licbag
)保存在 ByteDance/ios/Resource/LicenseBag.bundle
路径下。
在终端中进入 ByteDance/ios
目录,运行以下命令使用 CocoaPods 安装依赖:
pod install
在 Xcode 中打开项目 ByteDance/ios/ExtensionExample.xcworkspace
。
解压下载的 iOS 插件包,将所有 .framework
文件导入项目,并将 Embed 修改为 Embed & Sign。
打开 AppID.m
文件,进行如下修改:
<YOUR_APP_ID>
替换为你的 App ID。获取 App ID 请参考开始使用声网平台<YOUR_LICENSE_NAME>
替换为你的证书文件名称。例如:证书文件为 bytedance_4.2.3.licbag
,则在这里填入bytedance_4.2.3.licbag
。NSString *const appID = <#YOUR_APP_ID#>;
NSString *const token = nil;
NSString *const license_name = <#YOUR_LICENSE_NAME#>;
连接一台 iOS 真机(非模拟器),运行项目。
运行成功后,示例项目会安装到你的 Android 或 iOS 设备上。
disableExtension
、 initExtension
、setComposer
和 setSticker
按钮。setComposer
设置滤镜。setSticker
设置装扮贴纸。素材包中提供的文件详见素材包结构说明。
插件相关所有接口的参数解释详见接口说明。