使用说明

技术原理

本文介绍如何在你的项目中集成和使用商汤高级美颜/特效系列插件。商汤高级美颜/特效系列插件是对商汤 SenseAR Effects SDK核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 方法，传入指定的 key 和 value 参数，你可以快速集成商汤的美颜能力。

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

前提条件

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

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

示例项目

声网云市场提供了商汤高级美颜/特效插件 Android、iOS 的示例代码，你可以前往插件详情下载并进行体验。

集成和调用流程

1. 集成 SDK 和插件

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

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

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

实现音视频互动

1.2 购买和激活插件

你需要进入声网控制台 > 云市场页面，按照提示购买商汤高级美颜/特效系列插件。随后你会收到专属的证书 (License) 文件，用于后续集成插件。

1.3 集成插件

参考以下步骤集成插件：

进入声网控制台 > 云市场页面下载商汤高级美颜/特效系列的 Android 插件（.aar ），保存到项目文件夹的 /app/libs 路径。
点击下载商汤美颜插件的资源包，将 License 文件以及所需的模型文件和 bundle 文件保存到项目文件夹的 /app/src/main/assets 路径。
打开 app/build.gradle 文件，在 dependencies 中添加如下行：
Java
```
implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
```

导入需要用到的类：

Java

import com.sensetime.stmobile.STMobileEffectNative;
import com.sensetime.stmobile.STMobileHumanActionNative;

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.sensetime.ExtensionManager;

1.4 升级插件

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

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

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

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

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

参考集成插件章节下载所需平台最新版本的插件包和资源包。
删除项目内旧版本的插件包及其资源包后，再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
删除设备上用老版本插件和资源包编译的 App，重新编译你的项目并运行。

注意

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

2. 启用插件

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

Java

RtcEngineConfig config = new RtcEngineConfig();
// 监听插件事件，用于接收 onEvent 回调
config.mExtensionObserver = this;
config.addExtension("AgoraSenseTimeExtension");
mRtcEngine = RtcEngine.create(config);
// 开启插件
mRtcEngine.enableExtension("SenseTime", "Effect", enabled);

3. 初始化插件

初始化插件需要调用 setExtensionProperty 并传入对应的 key 和 value，具体顺序如下：

检查激活码。对应的 key 为 st_mobile_check_activecode，value 为 License 文件的路径。
创建人体行为检测句柄。对应的 key 为 st_mobile_human_action_create，value 包含模型文件的路径和配置选项。
创建特效句柄。对应的 key 为 st_mobile_effect_create_handle，value 为空，传入 {} 即可。

Java

private void initExtension() {
    // 获取 License 路径
    File licensePath = new File(getExternalFilesDir(null), "license/" + io.agora.rte.extension.sensetime.example.Constants.mLicenseName);

    // 检查激活码
    try {
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("license_path", licensePath.getPath());
        setExtensionProperty("st_mobile_check_activecode", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }

    // 创建人体行为检测句柄
    try {
        File modelsPath = new File(getExternalFilesDir(null), "models/M_SenseME_Face_Extra_Advanced_6.0.13.model");
        JSONObject jsonObject = new JSONObject();
        jsonObject.put("model_path", modelsPath.getPath());
        jsonObject.put("config", STMobileHumanActionNative.ST_MOBILE_HUMAN_ACTION_DEFAULT_CONFIG_IMAGE);
        setExtensionProperty("st_mobile_human_action_create", jsonObject.toString());
    } catch (JSONException e) {
        Log.e(TAG, e.toString());
    }

    // 创建特效句柄
    setExtensionProperty("st_mobile_effect_create_handle", "{}");
}

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

4. 设置美颜效果

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

设置美颜的强度：对应的 key 为 st_mobile_effect_set_beauty_strength，value 包含美颜类型和美颜强度。
加载美颜素材：对应的 key 为 st_mobile_effect_set_beauty，value 包含美颜类型和素材文件路径。

Java

// 设置美颜的强度
try {
    JSONObject jsonObject = new JSONObject();
    jsonObject.put("param", STEffectBeautyType.EFFECT_BEAUTY_PLASTIC_SHRINK_GODDESS_FACE);
    jsonObject.put("val", Double.valueOf(0.8).doubleValue());
    setExtensionProperty("st_mobile_effect_set_beauty_strength", jsonObject.toString());
} catch (JSONException e) {
    Log.e(TAG, e.toString());
}

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

Xcode 9.0 或以上版本。
运行 iOS 9.0 或以上版本的真机（非模拟器）。

Shell

.
├── <ProjectName>
├── <ProjectName>.xcodeproj
└── Resource

进入声网控制台 > 云市场页面下载商汤高级美颜/特效系列的 iOS 插件（.framework），保存到 <ProjectName> 路径下。
点击下载商汤美颜插件的资源包，将 License 文件以及所需的模型文件和 bundle 文件保存到 Resource 路径下。
在 Xcode 中进入 TARGETS > Build Settings > Build Options > Enable Bitcode，设置为 No，关闭 Bitcode。

导入需要用到的头文件：

Objective-C

 #import <AgoraRtcKit/AgoraRtcEngineKit.h>
 #import <AgoraSenseTimeExtension/st_mobile_human_action.h>
 #import <AgoraSenseTimeExtension/st_mobile_effect.h>

1.4 升级插件

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

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

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

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

参考集成插件章节下载所需平台最新版本的插件包和资源包。
删除项目内旧版本的插件包及其资源包后，再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
删除设备上用老版本插件和资源包编译的 App，重新编译你的项目并运行。

注意

2. 启用插件

初始化 AgoraRtcEngineKit 时，调用 enableExtensionWithVendor 启用插件。

Objective-C

[self.agoraKit enableExtensionWithVendor:@"SenseTime"
                               extension:@"Effect"
                                 enabled:self.enable];

3. 初始化插件

初始化插件需要调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value，具体顺序如下：

检查激活码。对应的 key 为 st_mobile_check_activecode，value 为 License 文件的路径。
创建人体行为检测句柄。对应的 key 为 st_mobile_human_action_create，value 包含模型文件的路径和配置选项。
创建特效句柄。对应的 key 为 st_mobile_effect_create_handle，value 为空，传入 {} 即可。

Objective-C

- (IBAction)initExtension:(id)sender {
    {
        NSString* fileName = [[license_name lastPathComponent] stringByDeletingPathExtension];
        NSString* extension = [license_name pathExtension];
        NSError *error;
        NSData *data = [NSJSONSerialization dataWithJSONObject:@{
                                                            @"license_path": [[NSBundle mainBundle]
                                                                pathForResource:fileName
                                                                         ofType:extension]
                                                        }
                                                       options:NSJSONWritingPrettyPrinted
                                                         error:&error];
        // 检查激活码
        [self.agoraKit
            setExtensionPropertyWithVendor:@"SenseTime"
                                 extension:@"Effect"
                                       key:@"st_mobile_check_activecode"
                                     value:[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]];
    }

    {
        NSString *model_path = [[[NSBundle mainBundle]
                                 pathForResource:@"model"
                                 ofType:@"bundle"] stringByAppendingFormat:@"/%@", @"M_SenseME_Face_Extra_Advanced_6.0.13.model"];
        NSError *error;
        NSData *data = [NSJSONSerialization dataWithJSONObject:@{
                                                            @"model_path": model_path,
                                                            @"config": @(ST_MOBILE_HUMAN_ACTION_DEFAULT_CONFIG_IMAGE)
                                                        }
                                                       options:NSJSONWritingPrettyPrinted
                                                         error:&error];
        // 创建人体行为检测句柄
        [self.agoraKit
            setExtensionPropertyWithVendor:@"SenseTime"
                                 extension:@"Effect"
                                       key:@"st_mobile_human_action_create"
                                     value:[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]];
    }

    {
        // 创建特效句柄
        [self.agoraKit
            setExtensionPropertyWithVendor:@"SenseTime"
                                 extension:@"Effect"
                                       key:@"st_mobile_effect_create_handle"
                                     value:@"{}"];
    }
}

4. 设置美颜效果

设置美颜效果需要调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value，目前支持以下功能：

设置美颜的强度：对应的 key 为 st_mobile_effect_set_beauty_strength，value 包含美颜类型和美颜强度。
加载美颜素材：对应的 key 为 st_mobile_effect_set_beauty，value 包含美颜类型和素材文件路径。

Objective-C

NSError *error;
NSData *data = [NSJSONSerialization dataWithJSONObject:@{
                                                       @"param": @(EFFECT_BEAUTY_PLASTIC_SHRINK_GODDESS_FACE),
                                                       @"val": @0.8f
                                                   }
                                                   options:NSJSONWritingPrettyPrinted
                                                   error:&error];

[self.agoraKit
    setExtensionPropertyWithVendor:@"SenseTime"
                         extension:@"Effect"
                         key:@"st_mobile_effect_set_beauty_strength"
                         value:[[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]];

技术原理

前提条件

示例项目

集成和调用流程

1. 集成 SDK 和插件

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

实现音视频互动

1.2 购买和激活插件

1.3 集成插件

1.4 升级插件

2. 启用插件

3. 初始化插件

4. 设置美颜效果

API 参考

相关文档

技术原理

前提条件

示例项目

集成和调用流程

1. 集成 SDK 和插件

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

实现音视频互动

1.2 购买和激活插件

1.3 集成插件

1.4 升级插件

2. 启用插件

3. 初始化插件

4. 设置美颜效果

API 参考

相关文档

咨询电话

咨询电话

技术原理Copy Anchor Link

前提条件Copy Anchor Link

示例项目Copy Anchor Link

集成和调用流程Copy Anchor Link

1. 集成 SDK 和插件Copy Anchor Link

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

实现音视频互动

1.2 购买和激活插件Copy Anchor Link

1.3 集成插件Copy Anchor Link

1.4 升级插件Copy Anchor Link

2. 启用插件Copy Anchor Link

3. 初始化插件Copy Anchor Link

4. 设置美颜效果Copy Anchor Link

API 参考Copy Anchor Link

相关文档Copy Anchor Link

咨询电话

咨询电话

技术原理

前提条件

示例项目

集成和调用流程

1. 集成 SDK 和插件

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

1.2 购买和激活插件

1.3 集成插件

1.4 升级插件

2. 启用插件

3. 初始化插件

4. 设置美颜效果

API 参考

相关文档