使用说明

  • Flutter

更新时间

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

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

技术原理

相芯美颜道具高级版插件是对相芯 Nama SDK 核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 方法,传入指定的 key 和 value 参数,你可以快速集成相芯的美颜能力。

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

前提条件

开发环境要求

如果你的目标平台为 iOS,你的开发环境需要满足以下需求:

  • Flutter 2.0 或更高版本
  • Dart 2.14.0 或更高版本
  • macOS 操作系统
  • 最新版本的 Xcode

如果你的目标平台为 Android,你的开发环境需要满足以下需求:

  • Flutter 2.0 或更高版本
  • Dart 2.14.0 或更高版本
  • macOS 或 Windows 操作系统
  • 最新版本的 Android Studio

运行环境要求

  • 如果你的目标平台为 iOS,你需要有一台 iOS 的设备。
  • 如果你的目标平台为 Android,你需要有一台 Android 设备或模拟器。

信息

你需要运行 flutter doctor 命令检查开发环境和运行环境是否满足要求。

示例项目

声网云市场提供了相芯美颜道具高级版插件 Android、iOS 和 Flutter 的示例项目,你可以前往插件详情页克隆或下载并进行体验。

集成和调用流程

1. 集成 SDK 和插件

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

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

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

1.2 购买和激活插件

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

1.3 集成插件

参考以下步骤集成插件:

  1. 在 Flutter 项目中,根据实际需要集成原生的 Android 和/或 iOS 插件:

  1. 添加证书文件:将插件包里的证书文件(authpack.java 或 authpack.h)转换成 dart 语法,并保存到项目文件夹,比如 lib 路径。authpack.java 和 authpack.h 所包含的证书数据一样。以转换 authpack.h 文件为例,将文件内的数据复制到 List<int> gAuthPackage = []; 这一行的 [] 中即可:

    Dart
    /// 填写示例:List<int> gAuthPackage = [10, 13, -98, -100, 126, ...];
    List<int> gAuthPackage = [Paste your authpack data];
  1. 点击下载相芯美颜插件的资源包,将所需的模型和道具 .bundle 文件通过 Flutter assets 的方式保存到项目文件夹,比如 Resource 路径。资源包中提供的文件详见参考信息。
  1. 在 pubspec.yaml 文件中添加依赖项,示例如下:

    YAML
    environment:
      sdk: '>=2.18.6 <3.0.0'
    
    dependencies:
      flutter:
        sdk: flutter
    
      cupertino_icons: ^1.0.2
      #声网 Flutter SDK 依赖项,请使用最新版本的 agora_rtc_engine
      agora_rtc_engine: ^6.0.0
      path_provider: ^2.0.11
      permission_handler: ^8.3.0
      path: ^1.8.0
    
    # The following section is specific to Flutter packages.
    flutter:
    
      # 添加相芯资源文件依赖项
      assets:
        - Resource/graphics/aitype.bundle
        - Resource/items/ItemSticker/CatSparks.bundle
        - Resource/model/ai_face_processor.bundle
  2. 导入需要用到的 dart 文件:

    Dart
    import 'package:agora_rtc_engine/agora_rtc_engine.dart';
    import 'authpack.dart' as authpack;

1.4 升级插件

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

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

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

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

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

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

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

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

注意

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

2. 启用插件

创建并初始化 RtcEngine 后,首先调用 enableExtension 启用插件,再调用其它 API(enableVideo、joinChannel 等)。

Dart
// On Android, you should load libAgoraFaceUnityExtension.so explicitly
if (Platform.isAndroid) {
  await _rtcEngine.loadExtensionProvider(path: 'AgoraFaceUnityExtension');
}
await _rtcEngine.enableExtension(
    provider: "FaceUnity", extension: "Effect", enable: true);

3. 初始化插件

当收到声网 SDK 的 onExtensionStarted 回调后,你可以在主线程或其他工作线程中调用 setExtensionProperty 并传入对应的 key 和 value 进行初始化:

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

注意

声网建议你在 onExtensionStarted 回调中仅做标记处理(比如设置一个 flag),避免在回调中直接执行初始化等耗时操作,以防阻塞 SDK 事件循环。

Dart
Future<void> _initFUExtension() async {
  // 初始化
  await _rtcEngine.setExtensionProperty(
      provider: 'FaceUnity',
      extension: 'Effect',
      key: 'fuSetup',
      value: jsonEncode({'authdata': authpack.gAuthPackage}));

  // 加载 AI 模型
  final aiFaceProcessorPath =
      await _copyAsset('Resource/model/ai_face_processor.bundle');
  await _rtcEngine.setExtensionProperty(
      provider: 'FaceUnity',
      extension: 'Effect',
      key: 'fuLoadAIModelFromPackage',
      // 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8
      value: jsonEncode({'data': aiFaceProcessorPath, 'type': 1 << 8}));
}

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

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

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

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

设置猫耳效果的示例如下:

Dart
Future<void> _setupCatSparksEffect() async {
  final aiFaceProcessorPath =
      await _copyAsset('Resource/model/ai_face_processor.bundle');
  await _rtcEngine.setExtensionProperty(
      provider: 'FaceUnity',
      extension: 'Effect',
      key: 'fuLoadAIModelFromPackage',
      // 通过 type 参数设置 AI 能力类型为 FUAITYPE_FACEPROCESSOR,对应取值为 1 << 8
      value: jsonEncode({'data': aiFaceProcessorPath, 'type': 1 << 8}));

  final catSparksPath =
      await _copyAsset('Resource/items/ItemSticker/CatSparks.bundle');
  await _rtcEngine.setExtensionProperty(
      provider: 'FaceUnity',
      extension: 'Effect',
      key: 'fuCreateItemFromPackage',
      value: jsonEncode({'data': catSparksPath}));
}

5. 释放资源

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

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

参考信息

API 参考

常见问题

问题 1:运行示例项目,美颜为什么没有生效?

通常有以下几个原因:

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

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

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

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

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

素材包结构

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

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