本文介绍如何在你的项目中集成和使用虹图人像 3D 特效系列(以下简称“虹图人像 3D 插件”),包括 Android 和 iOS 平台。
虹图人像 3D 插件是对虹图 HTAvatar 核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 或 setExtensionPropertyWithVendor 方法,传入指定的 key
和 value
参数,你可以快速集成虹图的人像 3D 特效能力。
以 setExtensionProperty
为例,其中的 key
参数与虹图的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用 setExtensionProperty
时只要传入指定的 key
和 value
,就可以调用对应的虹图 API,实现人像 3D 特效的有关功能。setExtensionPropertyWithVendor
同理。
在 Gitee 上查看完整的示例代码和项目结构
平台 | 语言 | 示例项目 |
---|---|---|
Android | Java | AgoraHTAvatorExtensionDemo/Android |
iOS | Objective-C | AgoraHTAvatorExtensionDemo/iOS |
Android
git clone https://gitee.com/htai-open/agora-htavatar-extension-demo.git
.aar
文件保存到 agora-htavatar-extension-demo/Android/app/libs
路径 。(libs
文件夹需自行创建)。agora-htavatar-extension-demo/Android/app/src/main/assets
路径 。(assets
文件夹需自行创建)agora-htavatar-extension-demo/Android
。agora-htavatar-extension-demo/Android/app/src/main/java/io/agora/rte/extension/hteffectar/example/Constants.java
,进行如下修改:<YOUR_APP_ID>
替换为你的声网 App ID。获取 App ID 请参考开始使用 Agora 平台。mToken
和 mLicenseName
在运行 demo 时不必填写。public interface Constants {
String mAppId = "<YOUR_APP_ID>";
String mToken = null;
String mLicenseName = "<YOUR_LICENSE_NAME>";
}
agora-htavatar-extension-demo/Android/app/src/main/java/io/agora/rte/extension/hteffectar/example
/HtKey.java
,进行如下修改:<YOUR_HT_SDK_KEY>
替换为在声网购买的由虹图提供的测试 keypublic interface HtKey {
String HTKey = "<YOUR_HT_SDK_KEY>";
}
iOS
git clone https://gitee.com/htai-open/agora-htavatar-extension-demo.git
.framework
库文件保存到 agora-htavatar-extension-demo/iOS/ExtensionExample
。HTKey.h
和资源包 HTEffect.bundle
保存到 agora-htavatar-extension-demo/iOS/ExtensionExample
路径。agora-htavatar-extension-demo/iOS
目录,运行以下命令使用 CocoaPods 安装依赖: pod install
ExtensionExample.xcworkspace
。Config.h
,进行如下修改:<YOUR_APP_ID>
替换为你的声网 App ID。获取 App ID 请参考开始使用 Agora 平台。token
在运行 demo 时不必填写。NSString *const appID = @"<YOUR_APP_ID>";
NSString *const token = nil;
agora-htavatar-extension-demo/iOS/ExtensionExample/HTKey.h
,进行如下修改:<YOUR_HT_SDK_KEY>
替换为在声网购买的由虹图提供的测试 key:NSString *const HTKey = @"<YOUR_HT_SDK_KEY>";
运行成功后,示例项目会安装到你的 Android 或 iOS 设备上。
enableExtension
、htARSetModel
按钮。htARSetModel
设置 3D AR 道具效果。默认是拳击头套效果。目前 3D 不支持横屏适配。虹图人像 3D 插件需要与声网视频 SDK v4.x 搭配使用。参考以下文档集成视频 SDK v4.x 并实现基础的视频通话:
在声网控制台购买和激活虹图人像 3D 插件,购买时需要保存好获取的证书文件,用于后续集成插件。
Android
下载虹图人像 3D 插件的 Android 插件包。解压后,将所有 .aar
文件保存到项目文件夹的 /app/libs
路径。
联系声网获取虹图人像 3D 插件的资源包,将所需的模型和道具文件保存到项目文件夹的 /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;
在使用 3D 特效的 Java 文件对应的 xml 布局文件中添加:
<RelativeLayout
android:id="@+id/unityView"
android:layout_width="1dp"
android:layout_height="1dp">
</RelativeLayout>
在使用 3D 特效的 Java 文件中添加:
unityView = findViewById(R.id.unityView);
unityView.addView(mUnityPlayer);
iOS
下载虹图人像 3D 插件的 iOS 插件包。
解压文件夹,将所有 .framework
库文件保存到你的项目文件夹下。
将证书文件 HTKey.h
保存到项目文件夹下。
联系声网获取虹图人像 3D 插件的资源包,将 HTEffect.bundle
保存到项目文件夹下。
在 Xcode 中添加动态库,确保 Embed 属性设置为 Embed & Sign。
导入需要用到的头文件:
#import <AgoraRtcKit/AgoraRtcEngineKit.h>
#import "HTKey.h"
程序启动时在 main.m
中添加以下代码。
#import "AppDelegate.h"
#import <HTEffectAR/HTEffectARInterface.h>
int main(int argc, char * argv[]) {
[[HTEffectARInterface shareInstance] initRuntime:argc argv:argv];
NSString * appDelegateClassName;
@autoreleasepool {
// Setup code that might create autoreleased objects goes here.
appDelegateClassName = NSStringFromClass([AppDelegate class]);
}
return UIApplicationMain(argc, argv, nil, appDelegateClassName);
}
下面介绍插件相关接口的调用流程。接口的参数解释详见接口说明。
Android
初始化 RtcEngine
时,调用 enableExtension
启用插件。
private void enableExtension(boolean enabled) {
mRtcEngine.enableExtension("Texeljoy", "HTAvatar", enabled);
}
iOS
初始化 AgoraRtcEngineKit
时,调用 enableExtensionWithVendor
启用插件。
[self.agoraKit enableExtensionWithVendor:@"Texeljoy"
extension:@"HTAvatar"
enabled:self.enable];
初始化插件需要调用 setExtensionProperty
(Android)或setExtensionPropertyWithVendor
(iOS) 并传入对应的 key 和 value,具体顺序如下:
Android
private void initExtension() {
// 初始化
try {
// 离线鉴权方式
JSONObject jsonObject = new JSONObject();
jsonObject.put("license",HTKey);
setExtensionProperty("htARInitOffline", jsonObject.toString());
} catch (JSONException e) {
Log.e(TAG, e.toString());
}
}
iOS
- (void)initExtension{
// 资源拷贝
[self.agoraKit setExtensionPropertyWithVendor:@"Texeljoy"
extension:@"HTAvatar"
key:@"htARCopyResource"
value:[self toJson:@{
@"path":[[NSBundle mainBundle] pathForResource:@"HTEffect" ofType:@"bundle"]
}]];
// 离线鉴权方式
[self.agoraKit setExtensionPropertyWithVendor:@"Texeljoy"
extension:@"HTAvatar"
key:@"htARInitOffline"
value:[self toJson:@{
@"license":HTSDKKey
}]];
// (可选)设置图片格式
[self.agoraKit setExtensionPropertyWithVendor:@"Texeljoy"
extension:@"HTAvatar"
key:@"htARImageFormat"
value:[self toJson:@{
@"imageFormat":@5
}]];
}
设置 3D AR 效果需要调用 setExtensionProperty
(Android)或setExtensionPropertyWithVendor
(iOS) 并传入对应的 key 和 value,具体顺序如下:
htARRenderEnable
,开启 AR 特效。htARSetModel
,设置 AR 模型。你可以根据场景需要进行组合调用。对应的 key 和 value 详见接口说明。
插件相关所有接口的参数解释详见接口说明。