NERTC SDK 支持接入火山引擎智能美化特效 SDK（下文简称火山美颜 SDK），实现美颜、美妆、滤镜、贴纸等丰富美颜特效。在视频社交、在线教育、直播互动等场景中，您可以快速构建具备专业美颜能力的应用，提升用户在视频通话或直播过程中的形象表现力。

功能概述

通过集成火山美颜 SDK，您可以在 NERTC 音视频通话中实现以下功能：

• 美化滤镜：支持美颜、滤镜、美妆、微整形、美体特效等多种技术。
• 贴纸道具：抖音同款上万款爆款特效贴纸，效果逼真、创新有趣。
• 特效创作工具：简单易操作，支持 2D、3D 多种特效能力，为企业设计师提供可视化特效制作工具。
• 端上智能算法：200+ 自研视觉算法，低能耗、高精度、高召回。

工作原理

1. NERTC SDK 通过视频帧采集回调接口将采集到的视频帧数据回调给应用层。
2. 应用层将视频帧传递给火山美颜 SDK 进行美颜处理。
3. 火山美颜 SDK 处理完成后，将美颜后的视频帧返回给应用层。
4. 应用层将美颜后的视频帧回传给 NERTC SDK 进行编码和传输。

注意事项

• 平台兼容性：火山美颜 PC SDK 支持 Windows、macOS 和 Linux 平台。本文以 Windows 平台为例，其他平台请参考《火山美颜官网》PC 接入指南。
• 图像格式：不同平台支持的图像格式可能不同，Linux 平台主要支持 YUV420 转 ARGB 格式处理，Windows 和 macOS 支持更多格式如 I420。
• 资源管理：确保在程序退出前正确释放火山美颜相关资源，避免内存泄漏。
• 线程安全：美颜处理操作应在正确的线程中进行，避免多线程操作导致的问题。

前提条件

在集成火山美颜 SDK 前，请确保您已完成以下准备工作：

• 开发环境：Visual Studio 2017 或更高版本。
• 开发工具：Qt 5.12 或更高版本（如使用 Qt 开发）
• 已获取网易云信 AppKey
• 已集成 NERTC SDK 到您的项目中。
• 已实现基础音视频通话功能。
• 联系火山引擎技术支持获取授权火山美颜资源包（Resource），集成火山美颜 SDK 需要获取以下资源：
  • SDK：火山美颜 SDK 的核心库文件
  • Resource：美颜效果所需的素材资源包
  • SampleCode：示例代码，帮助理解集成流程

第一步：环境配置

示例代码位于火山美颜 SDK 包中的 samplecode 目录，包含完整的桌面端集成示例。

• 开发环境要求：

  • Windows 平台需使用 Visual Studio 2017 及 Qt 5.12
  • 需将 Qt 路径配置到环境变量 QT_PATH_5_12
  • 编译时使用 %QT_PATH_5_12%\msvc2017_64\bin 目录下的 qmake 等工具

• 编译示例代码：

  • 参考 root/build 目录下的构建脚本
  • 执行 root/build/win/win_x64.bat 脚本进行编译

第二步：引入依赖库

1. 示例代码中的依赖库位于 root/platform 目录，Windows 平台结构如下：

   • root/platform/libs：包含预编译的静态库文件。
   • root/platform/sdk：包含网易云信 NERTC SDK 相关资源。
   • root/platform/x64 和 root/platform/x86：包含 32 位和 64 位平台的动态库文件。

2. 在您的工程中添加依赖。

   参考示例代码中的 root/src/demo.pro 文件，将必要的依赖库添加到您的工程中。

3. 了解火山美颜接口封装。

   火山美颜 SDK 提供了封装好的接口，简化集成难度：

   • 主要接口入口：root/src/thirdparty/beauty/huoshan/model/huoshan.h
   • C++ 封装层：root/src/thirdparty/beauty/huoshan/EffectManager
     • 该封装层降低了直接使用火山 C 接口的难度。
     • 各平台特定实现位于同级的平台文件夹中，如 root/src/thirdparty/beauty/huoshan/win。
     • 如有特殊需求，您可以重新编译 EffectManager。

第三步：添加素材资源

将火山美颜 SDK 及其所需资源正确引入到您的项目中，为后续的功能开发做好准备。

1. 将获取的素材资源包（resource 文件夹）添加到工程的 root/resource/huoshan_res 目录中。

2. 资源结构需按照示例代码中的目录结构组织引入美颜资源。

   C++void BEResourceProvider::initialize(const std::string& appDir) {
       setResourceDir(appDir + "huoshan_res/");
       m_modelDir = m_resourceDir + "model/";           // 对应基础模型资源 ModelResource.bundle
       m_filterDir = m_resourceDir + "Filter/";         // 对应滤镜资源 FilterResource.bundle
       m_faceCacheDir = m_resourceDir + "faceCache/";   // 示例中暂无实际内容
       m_stickerDir = m_resourceDir + "stickers_resource/"; // 对应贴纸特效资源 StickerResource.bundle
       m_composerNodeDir = m_resourceDir + "ComposeMakeup/"; // 对应美妆相关资源 ComposeMakeup.bundle
   }
   

第四步：初始化美颜 SDK

在集成使用 SDK 之前，您可以参考并拷贝使用 root/src/thirdparty/beauty/huoshan 下资源和代码。

1. 引入头文件。

   C++#include "huoshan.h"
   #include "BEResourceModel.h"
   #include "BEResourceProvider.h"
   

2. 创建美颜实例并验证授权。

   C++// 创建火山美颜实例
   huoshan_ = new tools::huoshan();
   
   // 设置证书文件路径
   #if defined(Q_OS_MAC)
       auto license_path = gGetDefaultLicensePath();
   #else
       auto license_path = QApplication::applicationDirPath() + "/license.bag";
   #endif
   
   // 检查证书文件是否存在
   if (!QFile::exists(license_path)) {
       if (!GetLicense(license_path)) {
           delete huoshan_;
           huoshan_ = nullptr;
           logDebug("license.bag not found");
           return;
       }
   }
   
   // 设置证书路径
   huoshan_->SetLicensePath(license_path.toStdString());
   

3. 初始化美颜 SDK。

   C++// 获取资源路径
   auto resource_path = main_window_->getRtcEngine().GetResourceDir();
   logDebug("license:%s, resource_path:%s", license_path.toStdString().c_str(), resource_path.toStdString().c_str());
   
   // 初始化美颜 SDK
   huoshan_->Init(QApplication::applicationDirPath().toStdString(), resource_path.toStdString());
   
   // 关联美颜实例与 NERTC SDK
   main_window_->getRtcEngine().setHuoshan(huoshan_);
   

   EffectManager 中初始化没有失败返回值，如需检查鉴权结果，可以在 huoshan 类中封装以下接口：

   C++bool checkLicense(const std::string& license_path) {
       // 检查授权结果
       bef_effect_result_t result = bef_effect_ai_check_license_base(license_path.c_str(), false);
       if (result != 0) {
           // 授权无效，进行错误处理
           return false;
       }
       return true;
   }
   

4. 参考上文 添加素材资源 加载资源包。

第五步：启用视频帧回调

1. 开启 NERTC SDK 的视频采集回调功能。

   C++// 在加入房间前开启视频采集回调
   QJsonObject json;
   json.insert("kNERtcKeyEnableVideoCaptureObserver", true);
   
   QString str = QString::fromUtf8(QJsonDocument(json).toJson());
   rtcEngine->setParameters(str.toStdString().c_str());
   

2. 在 NERTC SDK 的 onCaptureVideoFrame 中实现视频帧回调处理。

   C++void RtcEngine::onCaptureVideoFrame(void *data,
       NERtcVideoType type,
       uint32_t width,
       uint32_t height,
       uint32_t count,
       uint32_t offset[kNERtcMaxPlaneCount],
       uint32_t stride[kNERtcMaxPlaneCount],
       NERtcVideoRotation rotation)
   {
   #if defined(Q_OS_MAC)
       {
           // 加锁保证线程安全
           std::lock_guard<std::mutex> lock(huoshan_mutex);
           if (huoshan_) {
               // 处理视频帧
               huoshan_->onCaptureVideoFrame(data, type, width, height, count, offset, stride, rotation);
           }
       }
   #else
       // 加锁保证线程安全
       std::lock_guard<std::mutex> lock(huoshan_mutex);
       if (huoshan_) {
           // 处理视频帧
           huoshan_->Process((uint8_t *)data, width, height);
       }
   #endif
   }
   

3. 图像处理实现，实际实现数据处理部分在 EffectManager 中。

   C++void huoshan::Process(unsigned char* src, int width, int height) {
       if (m_effectHandle) {
           // 加锁保证线程安全
           ProcessLock();
   #if defined(__linux__)
           static unsigned char* rgbaData = nullptr;
           static int rgbaDataSize = 0;
           if (rgbaDataSize < width * height * 4) {
               rgbaDataSize = width * height * 4;
               if (rgbaData != nullptr) {
                   delete[] rgbaData;
               }
               rgbaData = new unsigned char[rgbaDataSize];
           }
           if (rgbaData == nullptr) {
               return;
           }
           // 将 YUV420 转换为 ARGB 格式进行处理
           huoshan_YUV420ToARGB((char*)src, (char*)rgbaData, width, height);
           m_effectHandle->setInput(width, height, rgbaData, BYTED_EFFECT::pixel_format_bgra);
           unsigned char* outputData = m_effectHandle->getOutput();
           // 处理完成后转回 YUV420 格式
           huoshan_ARGBToYUV420((char*)outputData, (char*)src, width, height);
   #else
           // Windows 平台处理 i420 格式
           m_effectHandle->setInput(width, height, src, BYTED_EFFECT::pixel_format_i420);
           unsigned char* outputData = m_effectHandle->getOutput();
           // 处理首次调用
           static bool is_first = true;
           if (is_first) {
               m_effectHandle->setInput(width, height, src, BYTED_EFFECT::pixel_format_i420);
               outputData = m_effectHandle->getOutput();
               is_first = false;
           }
           // 将处理后的数据拷贝回原缓冲区
           memcpy(src, outputData, width * height * 3 / 2);
   #endif
           ProcessUnlock();
       }
   }
   

第六步：设置美颜效果

火山美颜 SDK 提供丰富的美颜功能，您可以参考 素材 key 对应说明（4.2.1 及以上） 根据需求调整各种美颜参数。

1. 设置基础美颜。

   C++void updateComposerNode(int subId, float value);
   void updateComposerNodeWithRGB(int subId, float value, std::vector<float> rgbInfo);
   void updateComposerNodeWithKey(int subId, float value, std::string key);
   void removeComposerNode(int subId);
   
   void setDefaultEffects();
   /*
    * @brief: 设置滤镜素材
    */
   void setFilter(std::string filterName);
   
   /*
    * @brief: 设置滤镜效果
    */
   void setFilterIntensity(float intensity);
   
   /*
    * @brief: 设置贴纸素材
    */
   void setSticker(std::string stickerName);
   
   /*
    * @brief: 设置 matting 素材效果
    */
   void setMattingBk(std::string image_path);
   
   /*
    * @brief: 设置绿幕素材
    */
   void setGreenBk();
   
   void setRenderCache(std::string image_path);
   
   /*
    * @brief: 删除所有特效
    */
   void removeAllEffects();
   
   /*
    * @brief: 删除贴纸素材
    */
   void resetSticker();
   

2. 常见美颜设置接口可参考资源包中示例代码中实现。

   C++//一些功能素材的整理和初始化
   void tabBeauty::InitBeautyUI()
   void tabBeauty::InitBeautyNodes()
   //虚拟背景参考
   void tabBeauty::on_add_vbg_clicked()
   //贴图参考
   void tabBeauty::on_add_sticker_clicked()
   //调节美颜参数
   void tabBeauty::on_cb_beauty_type_currentIndexChanged(int index)
   

第七步：释放资源

在应用退出前，需要按正确的顺序释放资源。

C++// 释放火山美颜资源
if (huoshan_ != nullptr) {
    huoshan_->resetSticker();
    huoshan_->removeAllEffects();
    huoshan_->DeInit();
    delete huoshan_;
    huoshan_ = nullptr;
}

// 退出 NERTC 房间并释放资源
rtcEngine->leaveChannel();
rtcEngine->release();

参考文档

以下为本文涉及的火山美颜 SDK 官网文档：

• SDK 快速接入指南（PC）
• 素材 key 对应说明（4.2.1 及以上）
• 素材包结构说明（4.2.1 及以上）