使用 MetaKit 插件

本文介绍如何在你的项目中集成 MetaKit 插件，体验虚拟人、Animoji、Sticker、灯光特效和背景特效功能模块。

前提条件

在集成 MetaKit 插件前，请确保开发环境满足以下要求：

• 已集成 4.3.x 版本的实时互动 SDK，并确保你已在 App 中实现了基本的实时音视频功能，请参考实现音视频互动。
  注意

  • 通过 Maven Central 集成时，指定 'io.agora.rtc:full-sdk:x.y.z'，x.y.z 替换为具体的 SDK 版本号。
  • MetaKit 插件主要用到实时互动 SDK 的面部捕捉插件 (libagora_face_capture_extension.so) 和虚拟背景插件 (libagora_segmentation_extension.so)，你可以按需删除不需要的插件以减小 App 体积。
• Android Studio 4.2 及以上版本。
• 建议使用 2019 年及以后生产的 Android 机型，确保设备的前置摄像头与麦克风功能正常。
• 可以访问互联网的计算机。如果你的网络环境部署了防火墙，参考应对防火墙限制以正常使用声网服务。

集成 MetaKit 插件

在体验 MetaKit 插件前，请参考以下步骤配置你的项目。

添加 MetaKit 插件依赖

请参考以下步骤获取并集成 MetaKit 插件：

1. 进入下载页面，下载并解压 MetaKit Android 插件。

2. 打开文件夹，解压 Libraries.zip，将解压后的文件复制到对应的项目路径中。

   库	功能	集成路径
   AgoraMetaKit.aar	渲染 runtime 层	/app/libs
   metakit.jar	wrapper 层 Java 包	/app/libs
   libagora_metakit_extension.so	wrapper 层 so	/app/src/main/jniLibs/arm64-v8a 或 /app/src/main/jniLibs/armeabi-v7a

3. 进入项目的 /app/ 目录，在 build.gradle 文件的 dependencies 节点下，添加对 libs 路径下所有 .jar 及 .aar 文件的依赖。

   Java

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

配置 MetaKit 资源

1. 打开 MetaKit Android 插件的文件夹，/assets/ 路径下包含不同场景及功能所需的 Bundle 文件资源。功能模块、用途说明和资源大小见下表：

   功能模块	用途说明	资源大小
   虚拟人	虚拟人模型分包资源 (material_avatar_xxx)，包含虚拟人形像 girl、boy 和 huamulan。可使用面捕驱动、捏脸、换装等能力。	material_avatar_girl: 17.7 MB material_avatar_boy: 5.4 MB（不支持换装） material_avatar_huamulan: 5.3 MB（不支持捏脸换装）
   Animoji	Animoji 模型分包资源 (material_animoji_xxx)，包含 Animoji 形象 dog、girlhead 和 arkit。可使用面捕驱动能力。	material_animoji_dog: 3.3 MB material_animoji_girlhead: 4.2 MB material_animoji_arkit: 2 MB
   Sticker	Sticker 模型分包资源 (material_sticker_xxx)，包含 Sticker 挂件 glass、facemask、dragonhat 和 veil。可使用面捕驱动能力。	material_sticker_glass: 2.5 MB material_sticker_facemask: 1.9 MB material_sticker_dragonhat: 2.4 MB material_sticker_veil: 2.6 MB
   背景特效	背景特效分包资源 (material_bgeffect_xxx)，包含 360（360 全景背景）和 3d（3D 背景）。	material_bgeffect_360: 3.1 MB material_bgeffect_3d: 5.6 MB
   灯光特效	灯光特效分包资源 (material_effect_xxx)，包含 3D 打光、广告灯、氛围灯、极光特效、人像边缘火焰、人像边缘光线和屏幕波纹。	material_effect_3dlight: 1.9 MB material_effect_advertiselight: 8.2 MB material_effect_envlight: 1.9 MB material_effect_aura: 2 MB material_effect_purpleflame: 2 MB material_effect_ray: 1.9 MB material_effect_wave: 1.9 MB

2. 每个单包资源 (material_xxx) 代表一种场景效果。将多个你想体验的单包资源资源 (material_xxx) 平行放置在一个根目录下，加载场景资源时，将资源目录的绝对路径设置给 MetaKit。例如，体验女孩虚拟形象和人像边缘火焰特效，步骤如下：

   1. 将 material_avatar_girl 和 material_effect_purpleflame 合成一个资源目录（如下图所示）。准备好资源目录后，将其放置在移动设备 SD 卡的目录下，如 /sdcard/metaAssets/。
   2. loadMaterial 时，将路径设置为 /sdcard/metaAssets/material_avatar_girl，体验女孩虚拟人场景。
   3. 再次 loadMaterial，将路径指定为 /sdcard/metaAssets/material_effect_purpleflame，切换为人像边缘火焰。
   
   注意

   业务层需自行确保下载解压后资源的完备性。如果目录不正确或有 Bundle 文件丢失的情况，加载时会出现异常。

处理 Android 权限请求

1. 进入项目的 /app/src/main/ 目录，在 AndroidManifest.xml 文件中添加以下权限：

   XML

   <!--必要权限-->
   <uses-permission android:name="android.permission.INTERNET"/>
   
   <!--可选权限-->
   <uses-permission android:name="android.permission.CAMERA"/>
   <uses-permission android:name="android.permission.RECORD_AUDIO"/>
   <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
   <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
   <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
   <uses-permission android:name="android.permission.BLUETOOTH"/>
   <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
   <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
   <!-- 对于 Android 12.0 及以上设备，还需要添加以下权限 -->
   <uses-permission android:name="android.permission.READ_PHONE_STATE"/>
   <uses-permission android:name="android.permission.BLUETOOTH_SCAN"/>

   其中 MetaKit 插件主要用到的 Android 系统权限如下：

   权限	功能	用途
   CAMERA	访问手机相机。	表情驱动、背景分割等功能需要访问摄像头以做 AI 推理。
   INTERNET	访问网络。	启用插件时授权 AI 模块。
   READ_EXTERNAL_STORAGE	读取外部存储。	从 SD 卡中读取 Bundle 资源文件。
   WRITE_EXTERNAL_STORAGE	写入外部存储。	记录 SDK 相关日志文件。

2. Android 6.0 及以上的版本对权限管理更加严格，除了在 AndroidManifest.xml 文件中添加静态声明外，部分权限还需要在业务逻辑中动态申请。示例代码如下：

   Java

   // 获取体验实时音视频互动所需的录音、摄像头等权限
   private String[] getRequiredPermissions(){
       if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.S) {
           // Android 12 (S) 及以上版本所需的权限列表
           return new String[]{
                   Manifest.permission.RECORD_AUDIO, // 录音权限
                   Manifest.permission.CAMERA, // 摄像头权限
                   Manifest.permission.READ_PHONE_STATE, // 读取电话状态权限
                   Manifest.permission.READ_EXTERNAL_STORAGE, // 读取外部存储权限
                   Manifest.permission.WRITE_EXTERNAL_STORAGE // 写入外部存储权限
           };
       } else {
           // Android 11 (R) 及以下版本所需的权限列表
           return new String[]{
                   Manifest.permission.RECORD_AUDIO,
                   Manifest.permission.CAMERA,
                   Manifest.permission.READ_EXTERNAL_STORAGE,
                   Manifest.permission.WRITE_EXTERNAL_STORAGE
           };
       }
   }
   
   // 检查 App 是否已获得所需的所有权限
   private boolean checkPermissions() {
       for (String permission : getRequiredPermissions()) {
           int permissionCheck = ContextCompat.checkSelfPermission(this, permission);
           if (permissionCheck != PackageManager.PERMISSION_GRANTED) {
               return false;
           }
       }
       return true;
   }

选择 CPU 架构

目前 MetaKit 插件支持 arm64-v8a 及 armeabi-v7a 架构。为减小 App 体积，建议你在集成时选择所需架构即可。示例代码如下：

Java

ndk {
    abiFilters "arm64-v8a"
}

体验 MetaKit 插件

项目配置完成后，请参照以下步骤体验 MetaKit 插件的各个功能模块。

监听插件事件回调

1. 调用 create 初始化 RtcEngine 时，你需要在 RtcEngineConfig 中做如下配置：

   • 调用 addExtension 添加面部捕捉插件 (agora_face_capture_extension) 和 MetaKit 插件 (agora_metakit_extension)。
   • 创建插件的事件回调接口类 IMediaExtensionObserver，并注册 onEvent 等插件事件回调。
   Java

   // 配置 RtcEngineConfig
   RtcEngineConfig config = new RtcEngineConfig();
   config.mContext = getBaseContext();
   config.mAppId = appId;
   config.mEventHandler = mRtcEventHandler;
   // 添加面部捕捉插件
   config.addExtension("agora_face_capture_extension");
   // 添加 MetaKit 插件
   config.addExtension("agora_metakit_extension");
   // 创建插件的事件回调接口类，注册 onEvent 等插件事件回调
   config.mExtensionObserver = new IMediaExtensionObserver() {
       public void onEvent(String provider, String extension, String key, String value)
       public void onStarted(String provider, String extension)
       public void onStopped(String provider, String extension)
       public void onError(String provider, String extension, int error, String message)
   };
   
   // 创建并初始化 RtcEngine
   mRtcEngine = RtcEngine.create(config);

2. 在回调中指定 provider 为 agora_video_filters_metakit，extension 为 metakit，即筛选来自 MetaKit 插件的事件。onEvent 会透传引擎状态，如 unityLoadFinish（Unity 环境加载完成）和 materialLoaded（场景资源加载完成）等。

   注意

   下列代码注释中介绍了每个引擎状态的含义及时序，请确保在收到确切的引擎状态后，执行对应的操作，以免出现不必要的时序问题。

   Java

   public void onEvent(String provider, String ext, String key, String msg) {
       if (!provider.equals("agora_video_filters_metakit") || !ext.equals("metakit")) return;
       Log.i(TAG, "metakitx onEvent: " + key + ", msg: " + msg);
       switch(key) {
           case "initializeFinish":
               // 引擎初始化完成
               // 如有 initialize 操作，请在最后调用 destroy 销毁引擎，确保引擎的正常生命周期，减少对性能和内存的影响
               break;
           case "unityLoadFinish":
               // Unity 环境加载完成
               // 收到此状态后，可以调用 loadMaterial 加载场景资源
               break;
           case "materialLoaded":
               // 加载场景资源成功
               // 收到此状态后，可以根据场景进一步执行捏脸换装、特效参数设置等操作
               // 如不再需要体验场景，调用 unloadMaterial 卸载场景资源
               break;
           case "materialUnLoaded":
               // 卸载场景资源完成
               // 收到此状态后，不可再次加载场景资源，仅可调用 destroy 执行引擎销毁操作
               break;
       }
   }
   public void onError(String provider, String ext, int key, String msg) {
       if (!provider.equals("agora_video_filters_metakit") || !ext.equals("metakit")) return;
       Log.i("[MetaKit]", "onError: " + key + ", msg: " + msg);
   }
   public void onStart(String provider, String ext) {
       if (!provider.equals("agora_video_filters_metakit") || !ext.equals("metakit")) return;
       Log.i("[MetaKit]", "onStart");
   }
   public void onStop(String provider, String ext) {
       if (!provider.equals("agora_video_filters_metakit") || !ext.equals("metakit")) return;
       Log.i("[MetaKit]", "onStop");
   }

启用插件

启用面部捕捉插件、虚拟背景插件和 MetaKit 插件。

注意

在启用 MetaKit 插件前，你需要先启用面部捕捉插件和虚拟背景插件。

1. 启用面部捕捉插件。

   1. 调用 registerExtension 和 enableExtension 注册并启用面部捕捉插件，传入对应的插件服务商名称 (agora_video_filters_face_capture) 和插件名称 (face_capture)。
   2. 调用 setExtensionProperty 认证和授权面部捕捉插件的 AI 模块，其中 key 为 authentication_information，value 包含公司名称 (company_id) 和面捕证书 (license)。
   注意

   公司名称和面捕证书需要联系 sales@shengwang.cn 获取。

   Java

   // 注册面部捕捉插件
   mRtcEngine.registerExtension("agora_video_filters_face_capture", "face_capture", Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE);
   // 启用面部捕捉插件
   mRtcEngine.enableExtension("agora_video_filters_face_capture", "face_capture", true);
   // 授权面部捕捉插件
   mRtcEngine.setExtensionProperty("agora_video_filters_face_capture","face_capture", "authentication_information",
           "{\"company_id\":\"agoraDemo\"," +
                   "\"license\":\"" +
                   "xxxxxxxxxx"}", Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE);

2. 启用虚拟背景插件。

   1. 调用 setParameters 设置 "rtc.video.seg_before_exts" 为 true，确保虚拟背景插件优先于 MetaKit 插件执行。
   2. 调用 enableVirtualBackground 开启虚拟背景，其中：
      • 指定背景填充 (backgroundSourceType) 为 0，将背景处理为 alpha 信息，即分割人像和背景。
      • 指定分割模式 (modelType) 为 1，即选择适用于全部场景的背景处理。
   Java

   // 确保虚拟背景插件优先于 MetaKit 插件执行
   mRtcEngine.setParameters("{\"rtc.video.seg_before_exts\":true}");
   
   VirtualBackgroundSource source = new VirtualBackgroundSource();
   // 将 backgroundSourceType 设置为 0，表示将背景处理为 alpha 信息，分割人像和背景
   source.backgroundSourceType = 0;
   source.color = 0xFFFFFF;
   source.source = "";
   source.blurDegree = 1;
   SegmentationProperty param = new SegmentationProperty();
   // 将 modelType 设置为 1，表示选择适用于全部场景的背景处理
   param.modelType = 1; 
   param.greenCapacity = 0.5f;
   // 启用虚拟背景插件
   mRtcEngine.enableVirtualBackground(true, source, param, Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE);

3. 启用 MetaKit 插件。
   调用 registerExtension 和 enableExtension 注册并启用 MetaKit 插件，传入对应的插件服务商名称 (agora_video_filters_metakit) 和插件名称 (metakit)。

   Java

   // 注册 MetaKit 插件
   mRtcEngine.registerExtension("agora_video_filters_metakit", "metakit", Constants.MediaSourceType.PRIMARY_CAMERA_SOURCE);
   // 启用 MetaKit 插件
   mRtcEngine.enableExtension("agora_video_filters_metakit", "metakit", true);

设置安卓活动上下文

调用 setExtensionProperty 设置安卓活动上下文用于启动渲染引擎，其中 key 为 setActivityContext，value 包含活动上下文地址。

注意

活动上下文地址不支持传递 Java 对象的引用地址。安卓需要将活动上下文以 C++ 指针的形式共享给 MetaKit 引擎层，因此业务层需要通过 JNI 进行转换。

Java

Activity mActivity;
JSONObject valueObj = new JSONObject();
try {
    // 获取 Activity 对象的全局引用地址并传递给渲染引擎，以确保渲染引擎可以在 C++ 层使用这个 Activity 上下文
    long address = getContextHandler(mActivity);
    valueObj.put("activityContext", String.valueOf(address));
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "setActivityContext", valueObj.toString());

C++

// 通过 JNI 将 Java 层传入的 Activity 对象转换为全局引用，并返回其地址
JNIEXPORT jlong JNICALL Java_xxx_getContextHandler
(JNIEnv *env, jobject obj, jobject context)
{
    m_contextRef = env->NewGlobalRef(context);
    jlong handler = reinterpret_cast<jlong>(m_contextRef);
    return handler;
}

初始化插件

调用 setExtensionProperty 初始化 MetaKit 插件，其中 key 为 initialize，value 为空。

Java

mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "initialize","{}");

加载场景资源

当 onEvent 回调捕获到 unityLoadFinish 事件时，代表 Unity 环境已加载完成。此时，可以调用 setExtensionProperty 加载 MetaKit 场景资源，其中 key 为 loadMaterial，value 包含场景信息。

信息

• 下文中虚拟人、Animoji、Sticker、灯光特效和背景特效的资源加载均类似此步骤 (key 为 loadMaterial)，区别仅在于加载的资源包不同 (value 中指定的资源包路径不同)。
• 资源加载操作 (loadMaterial) 可以多次执行，无需在每次加载后执行卸载操作 (unloadMaterial) 。例如：在调用 loadMaterial(pathA) 后，如需切换为其他场景资源，可以再次调用 loadMaterial(pathB)、loadMaterial(pathC) 等，每次加载会全量覆盖之前的场景，最后再执行 unloadMaterial() 卸载场景资源即可。

Java

JSONObject valueObj = new JSONObject();
try {
    // path 为 Unity 的资源包目录，请提前下载并解压好
    valueObj.put("path", path);
    // 当前仅支持一张纹理输出，因此 view 直接填 0
    valueObj.put("view", "0");
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "loadMaterial", valueObj.toString());

当 onEvent 回调捕获到 materialLoaded 事件时，代表场景资源已加载完成。接下来，你可以体验虚拟人、Animoji、Sticker、灯光特效和背景特效功能模块。

设置虚拟人

1. 调用 setExtensionProperty 请求纹理并渲染虚拟人场景，其中 key 为 loadMaterial，value 为素材的配置信息。你想选用哪个虚拟人形象，请指定对应的资源名 (material_avatar_xxx)，例如：女孩虚拟人形象的资源名为 material_avatar_girl。

   信息

   除 girl、boy 和 huamulan 三个插件中已有的虚拟形象外，声网 MetaKit 插件提供开放的美术生态，支持一键导入按声网的美术标准制作的虚拟人模型，为用户提供更灵活的创作和集成选项。联系声网技术支持使用该功能。

   Java

   long addressHandle = 0;
   JSONObject valueObj = new JSONObject();
   try {
       valueObj.put("view", String.valueOf(addressHandle));
       valueObj.put("path", path_to_material_avatar_girl);
   } catch (JSONException e) {
       e.printStackTrace();
   }
   mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "loadMaterial", valueObj.toString());

   当 onEvent 回调捕获到 materialLoaded 事件时，代表场景视图已添加完成。会展示一个 Blendshape 驱动的虚拟人形象，捕捉你的面部表情并作出对应的神态变化，跟随你的摆头等动作。

2. 对虚拟人进行捏脸操作，支持以下两种方式：

   • （推荐）方式一：加载虚拟人时，直接应用整套捏脸效果。只需要在 loadMaterial 时指定资源为 material_package_faceshape，即可加载虚拟人形象及整套捏脸数据。
   • 方式二：加载虚拟人后，动态按部位对虚拟人进行捏脸操作。调用 setExtensionProperty，其中 key 为 updateFace，value 支持传入多组捏脸部位的资源 ID 及其对应的调节幅度。详见捏脸资源。
   Java

   JSONObject valueObj = new JSONObject();
   try {
       JSONObject configObj = new JSONObject();
       configObj.put("key", "bsname"); // key 为捏脸部位的资源 ID
       configObj.put("value", 30); // value 为对应的捏脸幅度，取值范围为 [0,100]，默认值为 50
       valueObj.put("value", configObj);
   } catch (JSONException e) {
       e.printStackTrace();
   }
   
   // 根据 JSON 配置进行捏脸操作
   mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "updateFace", valueObj.toString());

3. 对虚拟人进行换装操作，支持以下两种方式：

   • （推荐）方式一：在加载虚拟人时，直接应用整套换装效果。在 loadMaterial 时指定资源为 material_package_dress2 或 material_package_dress3，即可加载虚拟人形象及整套换装效果。
   • 方式二：在加载虚拟人后，动态按部位对虚拟人进行换装操作。调用 setExtensionProperty，其中 key 为 updateDress，value 支持传入由多个换装部位的资源 ID 组成的 Int 数组。详见换装资源。
   Java

   JSONObject valueObj = new JSONObject();
   try {
       valueObj.put("id", "[10002]"); // id 设置为多个资源 ID 组成的 Int 数组
   } catch (JSONException e) {
       e.printStackTrace();
   }
   // 根据 JSON 配置进行换装操作
   mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "updateDress", valueObj.toString());

   此外，MetaKit 插件还支持切换虚拟人的形象和视角，详见虚拟人 key-value 说明。

设置 Animoji 和 Sticker

Animoji

调用 setExtensionProperty 请求纹理并渲染 Animoji 场景，其中 key 为 loadMaterial，value 为素材的配置信息。你想选用哪个 Animoji 效果，请指定对应的资源名 (material_animoji_xxx)，例如：狗狗头套 Anomoji 的资源名为 material_animoji_dog。

信息

除 dog、girlhead 和 arkit 三个插件中已有的 Animoji 外，声网 MetaKit 插件提供开放的美术生态，支持一键导入按声网的美术标准制作的 Animoji 形象，为用户提供更灵活的创作和集成选项。联系声网技术支持使用该功能。

Java

long addressHandle = 0;

JSONObject valueObj = new JSONObject();
try {
    valueObj.put("view", String.valueOf(addressHandle));
    valueObj.put("path", path_to_material_animoji_dog);
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "loadMaterial", valueObj.toString());

当 onEvent 回调捕获到 materialLoaded 事件时，代表场景视图已添加完成。此时，画面中会出现一个遮住人脸的狗狗头套，捕捉你的面部表情并作出对应的神态变化，跟随你的摆头等动作。此外，MetaKit 插件支持你切换 Animoji 形象并调节 Animoji 形象的渲染等级，详见 Animoji key-value 说明。

Sticker

调用 setExtensionProperty 请求纹理并渲染 Sticker 场景，其中 key 为 loadMaterial，value 为素材的配置信息。你想选用哪个 Sticker 效果，请指定对应的资源名 (material_sticker_xxx)，例如：眼镜贴纸的资源名为 material_sticker_glass。

信息

除 veil、glass、facemask 和 dragonhat 四个插件中已有的 Sticker 外，声网 MetaKit 插件提供开放的美术生态，支持一键导入按声网的美术标准制作的 Sticker 形象，为用户提供更灵活的创作和集成选项。联系声网技术支持使用该功能。

Java

long addressHandle = 0;

JSONObject valueObj = new JSONObject();
try {
    valueObj.put("view", String.valueOf(addressHandle));
    valueObj.put("path", path_to_material_sticker_glass);
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "loadMaterial", valueObj.toString());

当 onEvent 回调捕获到 materialLoaded 事件时，代表场景视图已添加完成。此时，视图中会展示一个遮住人眼的眼镜贴纸，跟随你的摆头等动作。

设置灯光和背景特效

灯光特效

1. 调用 setExtensionProperty 请求纹理并渲染灯光特效场景，其中 key 为 loadMaterial，value 为素材的配置信息。你想选用哪个灯光特效，请指定对应的资源名 (material_effect_xxx)，例如：3D 打光的资源名为 material_effect_3dlight。成功设置该特效后，画面中会有一盏 3D 灯光从斜方来回扫过。

   Java

   long addressHandle = 0;
   
   JSONObject valueObj = new JSONObject();
   try {
       valueObj.put("view", String.valueOf(addressHandle));
       valueObj.put("path", path_to_material_effect_3dlight);
   } catch (JSONException e) {
       e.printStackTrace();
   }
   mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "loadMaterial", valueObj.toString());

2. 调用 setExtensionProperty 调节灯光特效的参数，其中 key 为 setEffectVideo，value 中包含一系列灯光素材的配置参数。MetaKit 插件提供 3D 打光、屏幕波纹、极光特效、人像边缘火焰等灯光特效，并支持对灯光效果的颜色、强度、范围等参数进行精细化配置，详见灯光特效 key-value 说明。

   Java

   JSONObject valueObj = new JSONObject();
   JSONObject paramObj = new JSONObject();
   try {
       paramObj.put("intensity", 2.0);
       paramObj.put("scale", 0.3);
       valueObj.put("id", 1001);
       valueObj.put("enable", true);
       valueObj.put("param", paramObj);
   } catch (JSONException e) {
       e.printStackTrace();
   }
   mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "setEffectVideo", valueObj.toString());

背景特效

调用 setExtensionProperty 请求纹理并渲染背景特效场景，其中 key 为 loadMaterial，value 为素材的配置信息。你想选用哪个背景特效，请指定对应的资源名 (material_bgeffect_xxx)，例如：360 全景背景素材的资源名为 material_bgeffect_360。

Java

long addressHandle = 0;

JSONObject valueObj = new JSONObject();
try {
    valueObj.put("view", String.valueOf(addressHandle));
    valueObj.put("path", path_to_material_bgeffect_360);
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "loadMaterial", valueObj.toString());

成功设置该特效后，可以观察到视频画面背景变为 360 全景，转动手机能体验到全景效果。此外，MetaKit 插件还支持 2D 背景和 3D 背景，如需将背景替换为指定资源或开启陀螺仪效果，详见背景特效 key-value 说明。

开启纹理输出

调用 setExtensionProperty 开启纹理输出，其中 key 为 enableSceneVideo，value 中将 enable 设置为 true 开启场景视图的画面捕获。开启纹理输出后，本地纹理的渲染效果会传输到远端，加入频道的观众也能看到渲染效果。

Java

long addressHandle = 0; 
boolean on = true;

JSONObject valueObj = new JSONObject();
try {
    valueObj.put("view", String.valueOf(addressHandle));
    valueObj.put("enable", on);
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit","metakit", "enableSceneVideo", valueObj.toString());

释放资源

停止使用插件时，可以参照以下示例代码卸载场景资源并销毁引擎。

Java

// 1. 卸载场景资源
JSONObject valueObj = new JSONObject();
try {
    valueObj.put("path", path);
} catch (JSONException e) {
    e.printStackTrace();
}
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit", "unloadMaterial", "{}");

// 2. 收到 materialUnLoaded 后，销毁引擎
mRtcEngine.setExtensionProperty("agora_video_filters_metakit", "metakit",
        "destroy", "{}");

相关文档

• 插件相关 API 参考
• key-value 说明