RTC SDK 提供与智能美化特效 SDK 联合方案，你可以通过调用 RTC SDK 提供的美颜处理接口，快速接入，对本地采集的视频添加美颜、滤镜、贴纸等特效。相较于通过 RTC 自定义视频前处理功能接入第三方美颜，集成更快捷、使用更方便、效果更佳。
本文介绍如何在 RTC 应用中接入火山引擎智能美化产品，实现美颜功能。

前提条件 #

• 已在项目中集成 3.50 及以上版本的 RTC SDK 并实现 RTC 视频通话功能。为保证你可以体验所有新增特性，推荐使用 最新版本 RTC SDK。支持本功能的 SDK 详见API 参考。
• 通过解压 RTC SDK 压缩包获取对应平台的火山引擎智能美化 SDK。
• 已购买火山引擎智能美化特效产品，并获取到符合业务功能需求的产品 License 和素材资源包。

  注意：

1. 请确保获取的 License 和特效素材资源与接入的火山引擎智能美化 SDK 版本完全一致，以保证相关功能的正常使用。
2. 完整的授权信息参考智能特效在线授权说明。

• 操作系统需满足以下要求：
  • Android 5.0+
  • iOS 11+（不支持模拟器）
  • macOS 10.11+
  • Windows 7+

Android 端功能实现 #

智能美化特效库及相关资源集成 #

1. 下载并解压 Android 端 RTC SDK，获取智能美化特效库 effectAAR-release_V4.x.xLite.aar 文件。
2. 将特效库文件添加至 Android 项目中的 app/libs 文件夹中。注意，若对特效库文件进行重命名，则需确保特效库名在 Android 工程中一致。此处以重命名为 ByteEffect.aar 为例。
   
3. 在项目根目录下 <yourprojectname>/app/build.gradle 文件的 dependencies 中使用 implementation 字段添加智能美化特效库，并点击 Sync 按钮同步。

dependencies {
    //...
    implementation(name: 'ByteEffect', ext: 'aar')
    implementation 'com.volcengine:VolcEngineRTC:3.xx.xxx'
}

4. 新建 assets 文件夹，并在该文件夹下添加自定义美颜文件夹（此处以 Effect 为例），将获取到的特效素材资源文件拷贝至 Effect 文件夹中。

注意：

1. LicenseBag.bundle 中存放特效证书，其他 bundle 中存放各类型的素材资源文件。
2. 特效证书的包名需与项目的包名保持一致，否则证书无法生效。

API 调用时序图 #

初始化 #

1. Android 中内置素材时是把素材放到 assets 中，其中的文件内容无法通过路径获取，所以需要初次启动 app 时将其拷贝到应用私有目录中使用。相关代码在API Example 中可以获取，你也可以自行编写复制资源的代码。

通过下方示例中 getExternalResourcePath() 函数可以获取指定的资源拷贝路径，指定的路径可以自定义。copyAssetFolder() 会将 assets 路径下的资源拷贝到指定的资源路径下，这里需要保证资源路径和拷贝路径都正确。

// 初始化美颜资源文件
// 将安装包内的资源文件拷贝到外部存储上
public static void initVideoEffectResource() {
    Context context = mAppCxt;
    File licensePath = new File(getExternalResourcePath(), "LicenseBag.bundle");
    licensePath.deleteOnExit();
    copyAssetFolder(context, "Effect/LicenseBag.bundle", licensePath.getAbsolutePath());
    
    File modelPath = new File(getExternalResourcePath(), "ModelResource.bundle");
    if (!modelPath.exists()) {
        copyAssetFolder(context, "Effect/ModelResource.bundle", modelPath.getAbsolutePath());
    }
    File stickerPath = new File(getExternalResourcePath(), "StickerResource.bundle");
    if (!stickerPath.exists()) {
        copyAssetFolder(context, "Effect/StickerResource.bundle", stickerPath.getAbsolutePath());
    }
    File filterPath = new File(getExternalResourcePath(), "FilterResource.bundle");
    if (!filterPath.exists()) {
        copyAssetFolder(context, "Effect/FilterResource.bundle", filterPath.getAbsolutePath());
    }
    File composerPath = new File(getExternalResourcePath(), "ComposeMakeup.bundle");
    if (!composerPath.exists()) {
        copyAssetFolder(context, "Effect/ComposeMakeup.bundle", composerPath.getAbsolutePath());
    }
    File virtualPicturePath = new File(getExternalResourcePath(), "virtual_background.png");
    if (!virtualPicturePath.exists()) {
        copyAssetFile(context, "virtual_background.png", virtualPicturePath.getAbsolutePath());
    }
}

public static String getExternalResourcePath() {
    return mAppCxt.getExternalFilesDir("assets").getAbsolutePath() + "/Effect/";
}

public static String getEffectPortraitPath() {
    return getStickerPathByName("matting_bg");
}

public static String getStickerPathByName(String name) {
    return mAppCxt.getExternalFilesDir("assets").getAbsolutePath() + "/Effect/StickerResource.bundle/stickers/" + name;
}

public static String getFilterPathByName(String name) {
    return mAppCxt.getExternalFilesDir("assets").getAbsolutePath() + "/Effect/FilterResource.bundle/Filter/" + name;
}

public static String getBeautyPath() {
    return mAppCxt.getExternalFilesDir("assets").getAbsolutePath() + "/Effect/ComposeMakeup.bundle/ComposeMakeup/beauty_Android_lite";
}

public static String getStylePathByName(String name) {
    return mAppCxt.getExternalFilesDir("assets").getAbsolutePath() + "/Effect/ComposeMakeup.bundle/ComposeMakeup/style_makeup/" + name;
}

2. 调用 createRTCEngine 创建引擎并开启视频采集后，你需先初始化美颜资源，并设置美颜资源和证书路径，方可开启美颜，在本地预览画面中看到美颜效果。注意，你需设置完整的证书文件路径，即指定到具体的证书文件；模型文件路径指定到 ModelResource.bundle 这层即可。

集成完成后，可通过调用 initCVResource()，查看返回值，判断是否集成成功。

private void configEffect() {
    //EffectManager 为自定义封装的美颜工具类
    EffectManager.initVideoEffectResource();
    String licPath = EffectManager.getLicensePath();
    String modelPath = EffectManager.getModelPath();
    IVideoEffect effect = mRTCEngine.getVideoEffectInterface();
    int result = effect.initCVResource(licPath, modelPath);
    result = effect.enableVideoEffect();
}

关闭所有美颜特效。

effect.disableVideoEffect();

美颜 #

美颜特效素材存放在 ComposeMakeup.bundle 文件中，使用 setEffectNodes 设置素材路径并使用 updateEffectNode 更新特效强度才可显示美颜效果。updateEffectNode 可以设置的素材 key 可以参考素材key对应说明。

注意：资源路径需要指定到 ../ComposeMakeup.bundle/ComposeMakeup/beauty_Android_lite 这层。

private void configEffect(){
    //...省略美颜资源初始化和美颜配置代码
    //美颜设置
    String composePath = EffectManager.getBeautyPath();
    List<String> nodes = Arrays.asList(composePath);
    result = effect.setEffectNodes(nodes);
    result = effect.updateEffectNode(composePath,"smooth",0.8f);
 }

贴纸 #

贴纸特效素材存放在 StickerResource.bundle 文件中，需使用的接口为 setEffectNodes 设置素材路径后方可显示贴纸效果。

注意：贴纸路径需要指定到特定贴纸名，例如 ../StickerResource.bundle/stickers/stickers_zhaocaimao

private void configEffect(){
    //...省略美颜资源初始化和美颜配置代码
    //贴纸
    String stickerPath = EffectManager.getStickerPathByName("stickers_zhaocaimao");
    List<String> nodes = Arrays.asList(stickerPath);
    result = effect.setEffectNodes(nodes);
}

风格妆 #

风格妆特效素材存放在 ComposeMakeup.bundle 文件中，需使用 setEffectNodes 设置素材路径并使用 updateEffectNode 更新特效强度方可显示风格妆效果。updateEffectNode 可以设置的素材 key 可以参考素材key对应说明。

注意：风格妆路径需要指定到特定风格妆名，例如 ../ComposeMakeup.bundle/ComposeMakeup/style_makeup/aidou

private void configEffect(){
    //...省略美颜资源初始化和美颜配置代码
    //风格妆
    String stylePath = EffectManager.getStylePathByName("nuannan");
    List<String> nodes = Arrays.asList(stylePath);
    result = effect.setEffectNodes(nodes);
    result = effect.updateEffectNode(composePath,"Filter_ALL",0.8f);
    result = effect.updateEffectNode(stylePath,"Makeup_ALL",0.8f);
}

滤镜 #

滤镜特效素材存放在 FilterResource.bundle 文件中，使用 setColorFilter 设置素材路径后，可使用 setColorFilterIntensity 调整滤镜强度。默认强度为 1.0，取值范围 [0, 1]，超出范围时设置无效。

注意：滤镜路径需要指定到特定滤镜名，例如 ../FilterResource.bundle/Filter/Filter_01_38

private void configEffect(){
    //...省略美颜资源初始化和美颜配置代码
    effect.setColorFilter(filterPath);
    effect.setColorFilterIntensity(0.8f);
}

虚拟背景 #

使用 enableVirtualBackground(backgroundStickerRes, source) 开启虚拟背景特效，参数 bg_sticker_res 为背景贴纸素材的绝对路径，参数 source 为期望设置的背景，当你期望设置一张自定义图片作为背景时，需将 sourceType 指定为 SourceTypeImage，并通过 sourcePath 设置自定义背景图片的绝对路径。

注意：虚拟背景的贴纸特效素材类型必须选择为 “matting_bg”。

private void configEffect(){
    //...省略美颜资源初始化和美颜配置代码
    //开启虚拟背景
    VirtualBackgroundSource backgroundSource = new VirtualBackgroundSource();
    backgroundSource.sourceType = VirtualBackgroundSourceType.IMAGE;
    backgroundSource.sourcePath = EffectManager.getExternalResourcePath() + File.separator + "virtual_background.png";
    String portraitPath = EffectManager.getEffectPortraitPath();
    effect.enableVirtualBackground(portraitPath,backgroundSource);
    //关闭虚拟背景
    effect.disableVirtualBackground();
}

旧版智能美化特效 API 未更新。

旧版智能美化特效 #

智能美化特效相关接口自 3.50 版本起由 RTCVideo 类迁移至 IVideoEffect 类。若你使用 3.50 之前版本的 RTC SDK，需通过 RTCVideo 实例调用智能美化特效相关接口。强烈建议你使用最新版 RTC SDK 以体验更加丰富而全面的智能美化特效功能，旧版接口也将在 3.56 版本删除。

API 调用时序图

接口使用

private void configEffect(){
    EffectManager.initVideoEffectResource();
    String licPath = EffectManager.getLicensePath();

    String modelPath = EffectManager.getModelPath();
    //美颜
    String composePath = EffectManager.getBeautyPath();
    //滤镜
    String filterPath = EffectManager.getFilterPathByName("Filter_01_38");
    //贴纸
    String stickerPath = EffectManager.getStickerPathByName("stickers_zhaocaimao");
    //妆容
    String stylePath = EffectManager.getStylePathByName("nuannan");
    List<String> nodes = Arrays.asList(composePath,stickerPath);
    int result = mRTCVideo.checkVideoEffectLicense(EffectManager.getApplicationContext(),licPath);
    mRTCVideo.setVideoEffectAlgoModelPath(modelPath);
    result = mRTCVideo.enableVideoEffect(true);
    result = mRTCVideo.setVideoEffectNodes(nodes);
    result = mRTCVideo.updateVideoEffectNode(composePath,"smooth",0.8f);
    mRTCVideo.setVideoEffectColorFilter(filterPath);
    mRTCVideo.setVideoEffectColorFilterIntensity(0.8f);
    mRTCVideo.updateVideoEffectNode(stylePath,"Filter_ALL",0.8f);
    mRTCVideo.updateVideoEffectNode(stylePath,"Makeup_ALL",0.8f);
    
    //开启虚拟背景
    VirtualBackgroundSource backgroundSource = new VirtualBackgroundSource();
    backgroundSource.sourceType = VirtualBackgroundSourceType.SourceTypeImage;
    backgroundSource.sourcePath = EffectManager.getExternalResourcePath() + File.separator + "virtual_background.png";
    String portraitPath = EffectManager.getEffectPortraitPath();
    mRTCEngine.setBackgroundSticker(portraitPath, backgroundSource);
    //关闭
    mRTCEngine.setBackgroundSticker(null, backgroundSource);
}

iOS 端功能实现 #

智能美化特效库及相关资源集成 #

我们提供两种集成方式：直接集成和通过本地 pod 方式集成。你可根据实际需求任选其一。

直接集成

1. 下载并解压 iOS 端 RTC SDK，获取智能美化特效库 effect-sdk.framework 文件。
2. 将 effect-sdk.framework 文件手动拖入项目工程中，并在 General 中将其 embed 属性设置为 Embed & Sign 模式。
   
3. 将获取到的前提条件手动添加至工程中。
   

   注意：特效证书的包名需与项目的 bundle Identifier 保持一致，否则无法生效。

通过本地 Cocoapods 方式集成

请确保已有 Cocoapods 相关配置。

1. 下载并解压 iOS 端 RTC SDK，获取智能美化特效库 effect-sdk.framework 文件。

2. 创建智能美化特效 SDK 的配置文件。创建文件 BytedEffectSDK.podspec，内容如下：

   Pod::Spec.new do |spec|
     spec.name         = 'BytedEffectSDK'
     spec.version      = '4.x.x' # 接入的火山引擎智能美化 SDK 版本
     spec.summary      = 'Demo for effect-sdk'
     spec.description  = 'Demo for effect-sdk'
     spec.homepage     = 'https://github.com/volcengine'
     spec.license      = { :type => 'Copyright', :text => 'Bytedance copyright' }
     spec.author       = { 'bytertc' => 'bytertc@bytedance.com' }
     spec.source       = { :path => './'}
     spec.ios.deployment_target = '11.0'
     spec.vendored_frameworks = 'effect-sdk.framework'
     spec.requires_arc = true
     spec.libraries = 'stdc++', 'z'
     spec.frameworks   = 'Accelerate','AssetsLibrary','AVFoundation','CoreGraphics','CoreImage','CoreMedia','CoreVideo','Foundation','QuartzCore','UIKit','CoreMotion'
     spec.weak_frameworks = 'Metal','MetalPerformanceShaders', 'Photos', 'CoreML'
   
   #  spec.resources = ['Resource/*.{bundle}']
   end
   

3. 将 BytedEffectSDK.podspec、effect-sdk.framework、Resource 文件放置在文件的同级目录：
   

4. 将火山引擎智能美化 SDK 添加到 Cocoapods 项目目录中。在 Podfile 文件中追加如下内容：

   pod 'BytedEffectSDK', :path => './BytedEffectSDK'
   

5. 在 Podfile 文件所在目录执行如下命令：

   pod install