使用说明

  • iOS

更新时间

了解云市场在不同平台上的集成商汤高级美颜和特效插件方式,包括接入流程、关键配置和平台差异。

本文介绍如何在你的项目中集成和使用商汤高级美颜/特效系列插件。

技术原理

商汤高级美颜/特效系列插件是对商汤 SenseAR Effects SDK核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionPropertyWithVendor 方法,传入指定的 key 和 value 参数,你可以快速集成商汤的美颜能力。

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

前提条件

iOS 开发环境需满足以下要求:

  • Xcode 9.0 或以上版本。
  • 运行 iOS 9.0 或以上版本的真机(非模拟器)。

示例项目

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

集成和调用流程

1. 集成 SDK 和插件

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

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

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

1.2 购买和激活插件

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

1.3 集成插件

参考以下步骤集成插件:

  1. 在项目文件夹下新建 Resource 文件夹,位置如下:

    Shell
    .
    ├── <ProjectName>
    ├── <ProjectName>.xcodeproj
    └── Resource
  2. 进入声网控制台 > 云市场页面下载商汤高级美颜/特效系列的 iOS 插件 (.framework),保存到 <ProjectName> 路径下。

  3. 点击下载商汤美颜插件的资源包,将 License 文件以及所需的模型文件和 bundle 文件保存到 Resource 路径下。

  4. 在 Xcode 中进入 TARGETS > Build Settings > Build Options > Enable Bitcode,设置为 No,关闭 Bitcode。

  5. 导入需要用到的头文件:

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

1.4 升级插件

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

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

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

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

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

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

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

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

注意

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

2. 启用插件

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

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

3. 初始化插件

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

  1. 检查激活码。对应的 key 为 st_mobile_check_activecode,value 为 License 文件的路径。
  2. 创建人体行为检测句柄。对应的 key 为 st_mobile_human_action_create,value 包含模型文件的路径和配置选项。
  3. 创建特效句柄。对应的 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]];

API 参考

相关文档

本文只实现了最基础的美颜功能。更多的接口调用方式请参考商汤 SenseAR Effects SDK 的文档(位于商汤美颜插件的资源包内)。