使用说明

本文介绍如何在你的项目中集成和使用虹图美颜特效系列插件。

技术原理

虹图美颜特效系列插件是对虹图 HTEffect 核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 方法，传入指定的 key 和 value 参数，你可以快速集成虹图的美颜特效能力。

setExtensionProperty 方法的 key 参数与虹图的 API 名称完全对应，value 参数以 JSON 格式包装该 API 的部分或全部参数。因此，调用该方法时只要传入指定的 key 和 value，就可以调用对应的虹图 API，实现美颜特效的有关功能。

前提条件

Android 开发环境需满足以下要求：

• Android Studio 4.1 以上版本。
• 运行 Android 5.0 或以上版本的真机（非模拟器）。

示例项目

虹图美颜特效系列插件提供了 Gitee 示例项目，你可以前往克隆或下载并进行体验。

平台	语言	示例代码
Android	Java	AgoraTexelJoyExtensionDemo/Android
iOS	Objective-C	AgoraTexelJoyExtensionDemo/iOS

运行步骤

参考以下步骤快速跑通示例项目：

1. 克隆仓库：

   Shell

   git clone https://gitee.com/htai-open/agora-texel-joy-extension-demo.git

2. 下载虹图美颜特效系列的 Android 插件包。解压后，将所有 .aar 文件保存到 Android/app/libs 路径（libs 文件夹需自行创建）。

3. 联系声网获取证书文件、资源包和测试 key。

4. 将资源包中所需的模型和道具文件保存到项目文件夹的 Android/app/src/main/assets 路径（assets 文件夹需自行创建）。

5. 在 Android Studio 中打开示例项目 agora-texel-joy-extension-demo/Android。

6. 将项目与 Gradle 文件同步。

7. 打开 Android/app/src/main/java/io/agora/rte/extension/hteffect/example/Constants.java，进行如下修改：

   • 将 <YOUR_APP_ID> 替换为你的 App ID。获取 App ID 请参考开通服务。

   • mToken 和 mLicenseName 在运行 demo 时不必填写。

     Java

     public interface Constants {
         String mAppId = "<YOUR_APP_ID>";
         String mToken = null;
         String mLicenseName = "<YOUR_LICENSE_NAME>";
     }

8. 打开 Android/app/src/main/java/io/agora/rte/extension/hteffect/example/HtKey.java，进行如下修改：

   • 将 <YOUR_HT_SDK_KEY> 替换为在声网购买的由虹图提供的测试 key。

     Java

     public interface HtKey {
         String HTKey = "<YOUR_HT_SDK_KEY>";
     }

9. 连接一台 Android 真机（非模拟器），运行项目。

预期效果

运行成功后，示例项目会安装到你的设备上。

1. 启动 App 后，虹图特效插件默认开启。你可以在界面上看到 enableExtension 、setStyleFilter、setSticker 按钮，人脸数量显示为 faces:0。
2. 点击 setStyleFilter 加载风格滤镜效果。默认是自然 3 效果。
3. 点击 setSticker 设置贴纸效果。默认是兔子蝴蝶结风格。

集成和调用流程

1. 集成 SDK 和插件

开始前，你需要在项目中分别集成声网视频 SDK 和虹图美颜特效系列插件。

1.1 使用声网 SDK 实现音视频互动

插件需要与 RTC SDK 搭配使用。参考以下文档集成 RTC SDK 并实现基础的音视频互动：

实现音视频互动

信息

该插件支持声网 SDK v4.1.1 或以上版本。

1.2 购买和激活插件

你需要进入声网控制台 > 云市场页面，按照提示购买虹图美颜特效系列插件。购买后需要保存好获取的证书文件，用于后续初始化插件。

1.3 集成插件

参考以下步骤集成插件：

1. 下载虹图美颜特效系列的 Android 插件包。解压后，将所有 .aar 文件保存到项目文件夹，比如 /app/libs 路径。

2. 联系声网获取资源包，将所需的模型和道具文件保存到项目文件夹，比如 /app/src/main/assets 路径。

3. 打开 app/build.gradle 文件，在 dependencies 中添加如下行：

   Java

   implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])

4. 导入需要用到的类：

   Java

   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;

1.4 升级插件

声网云市场推荐你更新插件版本前使用数据库工具 (如 SQLite) 来实现插件版本管理，从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时，会出现 App 闪退、崩溃等现象。

以下是用 SQLite 来进行插件版本管理的示例：

1. 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
2. 每次项目初始化时，自动检测当前项目使用的资源包版本：
   • 如果无记录文件或记录的资源包版本为旧，则更新资源。成功更新后，回写最新资源包版本信息到 SQLite。
   • 如果记录的资源包版本与当前匹配，则正常实现业务。

如果你的项目已经集成过声网云市场提供的第三方插件，并需要更新插件，可以参考以下步骤来保证更新后的可用性。

以下升级流程以相芯美颜特效插件为例：

1. 参考集成插件章节下载所需平台最新版本的插件包和资源包。

2. 删除项目内旧版本的插件包及其资源包后，再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。

3. 删除设备上用老版本插件和资源包编译的 App，重新编译你的项目并运行。

注意

编译 App 时，系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行，否则可能会出现插件版本与资源包不匹配的情况，从而导致各种意外问题。

2. 启用插件

初始化 RtcEngine 时，调用 enableExtension 启用插件。

Java

RtcEngineConfig config = new RtcEngineConfig();
// 加载插件
config.addExtension("AgoraTexelJoyExtension");
mRtcEngine = RtcEngine.create(config);
// 启用插件
mRtcEngine.enableExtension("Texeljoy", "HTEffect", enabled);

3. 初始化插件

初始化插件需要调用 setExtensionProperty 并传入对应的 key 和 value 进行鉴权，推荐使用离线鉴权。

Java

private void initExtension() {
    // 初始化
    try {
        // （推荐）离线鉴权方式
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("license",HtKey.HTKey);
        setExtensionProperty("htInitHTEffectOffline", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }
}

// 方便多次调用 setExtensionProperty
private void setExtensionProperty(String key, String property) {
    mRtcEngine.setExtensionProperty("Texeljoy", "HTEffect", key, property);
}

Java

private void initExtension() {
    // 初始化
    try {
        // 在线鉴权方式
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("appId",HtKey.HTKey);
        setExtensionProperty("htInitHTEffectOnline", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }
}

// 方便多次调用 setExtensionProperty
private void setExtensionProperty(String key, String property) {
    mRtcEngine.setExtensionProperty("Texeljoy", "HTEffect", key, property);
}

4. 设置美颜效果

设置美颜效果需要调用 setExtensionProperty 并传入对应的 key 和 value，实现以下功能：

• 全局美颜
• 精准美肤、美型、美发、风格
• 贴纸、礼物、水印
• 人像抠图、绿幕抠图
• 手势识别
• 风格滤镜、特效滤镜、哈哈滤镜

你可以参考示例项目，根据场景需要进行组合调用。

API 参考

• 声网 SDK 的插件相关方法和回调
• 插件的 key-value 说明