使用说明

本文介绍如何在你的项目中集成和使用相芯美颜道具高级版插件。

技术原理

相芯美颜道具高级版插件是对相芯 Nama 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 和 Flutter 的示例代码，你可以前往插件详情页克隆或下载并进行体验。

集成和调用流程

1. 集成 SDK 和插件

开始前，你需要在项目中分别集成声网视频 SDK 和相芯美颜道具高级版插件。

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

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

实现音视频互动

1.2 购买和激活插件

你需要进入声网控制台 > 云市场页面，按照提示购买相芯美颜道具高级版插件，并且联系声网提供你的包名（例如 yourCompany.yourProject.faceunity）。随后你会收到与包名唯一对应的证书文件，用于后续集成插件。

1.3 集成插件

参考以下步骤集成插件：

1. 进入声网控制台 > 云市场页面，下载相芯美颜道具高级版的 iOS 插件动态库压缩包。

2. 解压文件夹，将所有 .framework 文件导入项目，并将 Embed 修改为 Embed & Sign。

3. 将证书文件 authpack.h 引入你的 Xcode 项目。

4. 点击下载相芯美颜插件的资源包，将所需的模型和道具文件保存到项目文件夹，比如 Resource 路径。资源包中提供的文件详见参考信息。

   Shell

    项目文件夹示例
   .
   ├── <ProjectName>
   ├── <ProjectName>.xcodeproj
   └── Resource

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

   Objective-C

   #import <AgoraRtcKit/AgoraRtcEngineKit.h>
   #import "authpack.h"

1.4 升级插件

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

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

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

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

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

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

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

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

注意

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

2. 启用插件

创建并初始化 AgoraRtcEngineKit 后，首先调用 enableExtensionWithVendor 启用插件，再调用其它 API（enableVideo、joinChannelByToken 等）。

Objective-C

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

3. 初始化插件

收到声网 SDK 的 onExtensionStarted 回调后，调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value，具体顺序如下：

1. 初始化。对应的 key 为 fuSetup，value 为证书文件 authpack 的指针。
2. 加载 AI 模型。对应的 key 为 fuLoadAIModelFromPackage，value 包含 AI 能力模型文件 ai_xxx.bundle 的路径以及 AI 能力类型。

Objective-C

- (void)loadAIModels {
    [self.agoraKit
        setExtensionPropertyWithVendor:@"FaceUnity"
                             extension:@"Effect"
                                   key:@"fuLoadAIModelFromPackage"
                                 value:[self toJson:@{
                                   @"data": [[NSBundle mainBundle]
                                       pathForResource:@"ai_face_processor"
                                                ofType:@"bundle"],
                                   // 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR，对应取值为 1 << 8
                                   @"type": @(1 << 8)
                                 }]];

    [self.agoraKit
        setExtensionPropertyWithVendor:@"FaceUnity"
                             extension:@"Effect"
                                   key:@"fuLoadAIModelFromPackage"
                                 value:[self toJson:@{
                                   @"data": [[NSBundle mainBundle]
                                       pathForResource:@"ai_hand_processor"
                                                ofType:@"bundle"],
                                   @"type": @(1 << 3)
                                 }]];

    [self.agoraKit
        setExtensionPropertyWithVendor:@"FaceUnity"
                             extension:@"Effect"
                                   key:@"fuLoadAIModelFromPackage"
                                 value:[self toJson:@{
                                   @"data": [[NSBundle mainBundle]
                                       pathForResource:@"ai_human_processor_gpu"
                                                ofType:@"bundle"],
                                   @"type": @(1 << 9)
                                 }]];

    [self.agoraKit
        setExtensionPropertyWithVendor:@"FaceUnity"
                             extension:@"Effect"
                                   key:@"fuCreateItemFromPackage"
                                 value:[self toJson:@{
                                   @"data": [[NSBundle mainBundle]
                                       pathForResource:@"aitype"
                                                ofType:@"bundle"]
                                 }]];

    [self.agoraKit
        setExtensionPropertyWithVendor:@"FaceUnity"
                             extension:@"Effect"
                                   key:@"fuItemSetParam"
                                 value:[self toJson:@{
                                   @"obj_handle": [[NSBundle mainBundle]
                                       pathForResource:@"aitype"
                                                ofType:@"bundle"],
                                   @"name": @"aitype",
                                   @"value": @(1 << 8 | 1 << 30 | 1 << 3),
                                 }]];
}

4. 设置美颜效果和人体识别

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

• 加载道具、调节美颜强度
• 人脸、手势和人体识别

你可以根据场景需要进行组合调用。相关的 key 和 value 详见 key-value 说明。

5. 释放资源

需要停止使用插件时，按照以下步骤释放资源：

1. 调用 setExtensionPropertyWithVendor 并传入 key 为 fuDestroyLibData，释放插件占用的资源。
2. 收到 fuDestroyLibData 回调后，调用 destroy 方法销毁 AgoraRtcEngineKit 对象。

参考信息

API 参考

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

常见问题

问题 1：运行示例项目，美颜为什么没有生效？

通常有以下几个原因：

• 插件动态库没有保存在正确位置，或者没有导入；
• 相芯资源包中的文件没有保存在正确位置，或者缺少部分文件；
• 证书文件与 App 包名不一致，导致鉴权失败。

问题 2：为什么开启采集后需要 1s 左右才能渲染出视频？

加载相芯美颜资源的操作会造成 GL 渲染线程卡顿，加载资源的过程大概耗时 800ms。建议通过业务处理（比如添加 loading 界面）规避。

问题 3：为什么在编译 App 时会出现 models: no match 的报错？

该错误通常是由于资源包匹配问题引起的。很可能是因为在编译新插件时，没有删除旧版本的 App。建议你删除旧版 App 后重新编译运行。

素材包结构

相芯美颜道具高级版插件的资源包文件结构详见：

• Android 资源包结构
• iOS 资源包结构

更多的接口调用方式可以参考相芯 Nama SDK 的文档：

• Android 文档
• iOS 文档