火山美颜 - 音视频通话 2.0

更新时间： 2025/06/24 13:50:03

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

功能概述

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

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

工作原理

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

注意事项

纹理转换：由于 NERTC SDK 提供的是 OES 纹理，而火山美颜 SDK 需要 2D 纹理，因此需要进行纹理格式转换。
图像方向：移动设备摄像头采集的图像方向与显示方向可能不一致，需要正确设置图像旋转方向。
线程安全：美颜处理应在 OpenGL 线程中进行，避免多线程操作导致的异常。
资源释放：请确保在释放 NERTC SDK 资源之前，正确释放火山美颜相关资源，否则可能导致内存泄漏或应用崩溃。

前提条件

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

安卓设备系统版本 5.0 (API Level 21) 及以上。
确保 Android Studio 为 Dolphin 及以上版本。
已获取网易云信 AppKey。
已集成 NERTC SDK 到您的项目中。
已实现基础音视频通话功能。
如果您需要开启安全鉴权，可以从网易云信服务端获取 Token。
已从火山引擎获取以下资源：
- 火山美颜 SDK 及相关资源文件
- 火山美颜 SDK 的证书文件（LicenseBag.bundle）

第一步：环境集成

如需创建新项目，在 Android Studio 里，依次选择 Phone and Table > Empty Activity，创建 Android 项目。详情请参考《安卓开发者中心》创建项目。

使用 Maven Central 集成网易云信 NERTC SDK。如果您已完成本步骤，请跳过此步。

根据更新日志选择 NERTC SDK 版本号，然后在项目级 build.gradle 文件中添加 Maven Central 仓库和 NERTC SDK 依赖：

Groovybuildscript {
    repositories {
        mavenCentral()
        // 其他仓库...
    }
}

allprojects {
    repositories {
        mavenCentral()
        // 其他仓库...
    }
}

dependencies {
    // x.y.z 表示网易云信 NERTC SDK 的版本号，如 5.8.20
    implementation 'com.netease.yunxin:nertc:x.y.z'
}

集成火山美颜 SDK。详细步骤请参考《火山引擎官网文档》SDK 快速接入指南。
1. 将火山提供的 ByteEffect 模块集成到您的项目中：
  - 将 effectAAR-release.aar 放到 ByteEffect/libs 目录下。
  - 在应用模块的 build.gradle 文件中添加依赖：
```
Groovydependencies {
    // api fileTree(include: ['*.jar', '*.aar'], dir: 'libs') // sample 中的写法
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])   // 接入时写法
}
```
2. 将火山美颜场景化 Android Demo 下的 ByteEffect Module 集成到您的项目中。
3. 修改 ByteEffect/src/main/java/com/effectsar/labcv/core/Config.java 文件中的 LICENSE_NAME 为您申请到的火山美颜证书文件名。

添加项目中所需要的权限。

在 AndroidManifest.xml 中添加以下权限：

XML<!-- 网络相关权限 -->
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/>

<!-- 视频相关权限 -->
<uses-permission android:name="android.permission.CAMERA"/>
<!-- 允许应用程序使用摄像头硬件资源 -->
<uses-feature android:name="android.hardware.camera"/>
<uses-feature android:name="android.hardware.camera.autofocus"/>

<!-- 音频相关权限 -->
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<!-- 修改音频设置 -->
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

<!-- 蓝牙相关权限 -->
<uses-permission android:name="android.permission.BLUETOOTH"/>
<!-- 蓝牙连接权限，此权限还需在运行应用时动态申请，否则 Android 12 及以上的设备蓝牙无法正常工作 -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<!-- 蓝牙 startBluetoothSco 会用到此权限 -->
<uses-permission android:name="android.permission.BROADCAST_STICKY"/>

<!-- 其他必要权限 -->
<!-- NERTC SDK 5.4.0 及之后版本需要，更改设备的网络状态，如打开或关闭网络连接、更改网络类型等。-->
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
<!-- 获取设备信息 -->
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>

<!-- 如果 Android targetSdkVersion >= 31，需要添加以下标签，否则虚拟背景功能无法使用 -->
<application>
    <uses-native-library android:name="libOpenCL.so" android:required="false"/>
</application>
<!-- App 需要的其他设备权限 -->

在 app/proguard-rules.pro 文件中添加如下代码，防止网易云信 NERTC SDK 代码被混淆：
```
Groovy-keep class com.netease.** {*;}
```

第二步：资源准备

将火山美颜 SDK 提供的资源文件复制到项目对应路径：

美颜资源	项目路径
resource/LicenseBag.bundle	ByteEffect/src/main/assets/resource
resource/ModelResource.bundle	ByteEffect/src/main/assets/resource
resource/ComposeMakeup.bundle	ByteEffect/src/main/assets/resource
resource/StickerResource.bundle	ByteEffect/src/main/assets/resource
resource/FilterResource.bundle	ByteEffect/src/main/assets/resource

拷贝资源文件到沙盒路径。

在应用启动时，需要将美颜资源从 assets 复制到应用的沙盒路径中：

Kotlin// 初始化资源下载器并下载资源
if (download == null)
    download = ResDownload(this)
download?.download()

第三步：初始化 SDK

调用 init 初始化网易云信 NERTC SDK。

Kotlin// 创建 RTC 回调实例
private val rtcCallback = object : AbsNERtcCallbackEx() {
    // 实现必要的回调方法...
}

val appKey = "your_netease_rtc_appkey" // 从网易云信控制台申请的 AppKey
NERtcEx.getInstance().init(applicationContext, appKey, option)

初始化火山美颜 SDK。

Kotlinif (mEffectManager == null) {
    mEffectManager = EffectManager(applicationContext, EffectResourceHelper(applicationContext), EffectLicenseHelper.getInstance(applicationContext))
    val ret = mEffectManager?.init()
    if (ret != EffectsSDKEffectConstants.EffectsSDKResultCode.BEF_RESULT_SUC) {
        Log.e("Beauty", "美颜 SDK 初始化失败，错误码: $ret")
    }
}

第四步：视频处理流程

启动视频采集和设置本地画布。

Kotlin// 开启视频
var ret = NERtcEx.getInstance().enableLocalVideo(true)
if (ret != NERtcConstants.ErrorCode.OK) {
    print("enableLocalVideo failed, ret: $ret")
}
// 设置本地画布
val localVideoCanvas = findViewById<NERtcVideoView>(R.id.local_render)
ret = NERtcEx.getInstance().setupLocalVideoCanvas(localVideoCanvas)
if (ret != NERtcConstants.ErrorCode.OK) {
    print("setupLocalVideoCanvas failed, ret: $ret")
}

设置视频帧回调 setVideoCallback，对视频帧应用美颜效果。

KotlinNERtcEx.getInstance().setVideoCallback(object: NERtcVideoCallback {
    override fun onVideoCallback(videoFrame: NERtcVideoFrame?): Boolean {
        val result = videoFrame?.let {
            // 创建纹理转换配置
            val transition: ImageUtil.Transition = ImageUtil.Transition()
                .rotate(0F).flip(false, false)
            // 将 OES 纹理转换为 2D 纹理
            val inputTex: Int = mImageUtil.transferTextureToTexture(videoFrame!!.textureId,
                EffectsSDKEffectConstants.TextureFormat.Texture_Oes,
                EffectsSDKEffectConstants.TextureFormat.Texure2D,
                videoFrame!!.width,
                videoFrame!!.height,
                transition)
            // 准备输出纹理
            val outputTex: Int =
                mImageUtil.prepareTexture(videoFrame!!.width, videoFrame!!.height)
            if (mEffectManager == null) return false

            // 设置相机位置并处理纹理
            // 设置前置摄像头
            mEffectManager!!.setCameraPosition(true)
            val ret = mEffectManager!!.process(inputTex,
                outputTex,
                videoFrame!!.width,
                videoFrame!!.height,
                OrientationSensor.getOrientation(
                    videoFrame!!.rotation),
                System.nanoTime())
            // 更新处理后的纹理
            if (ret) {
                videoFrame!!.textureId = outputTex
                videoFrame!!.format = NERtcVideoFrame.Format.TEXTURE_RGB
            }
            ret
        }
        return result!!
    }
}, false)

调用 joinChannel 加入音视频房间。

Kotlin// 如果开启了鉴权，此处填写从网易云信服务器获取的 token
var ret = NERtcEx.getInstance().joinChannel(token, channelName, uid.toLong(), null)
if (ret != NERtcConstants.ErrorCode.OK) {
    Toast.makeText(this, getString(R.string.join_channel_error), Toast.LENGTH_SHORT).show()
    return
}

第五步：设置美颜特效

火山美颜 SDK 提供丰富的美颜特效功能，您可以根据需求设置不同的美颜效果。详情请参考火山美颜 SDK 快速接入指南《SDK 参数设置，如设置美颜、贴纸、滤镜等》章节。

第六步：释放资源

在退出通话或应用退出时，需要按照正确的顺序释放资源：

KotlinNERtcEx.getInstance().apply {

    // 移除视频帧回调
    setVideoCallback(null, false)
    // 离开房间
    leaveChannel()
}

Kotlin// 释放火山美颜资源
download?.release()
mImageUtil?.release()
mEffectManager?.destroy()
// 释放 NERTC SDK 资源
NERtcEx.getInstance().release()

此文档是否对你有帮助？

有帮助

去反馈

功能概述
工作原理
注意事项
前提条件
第一步：环境集成
第二步：资源准备
第三步：初始化 SDK
第四步：视频处理流程
第五步：设置美颜特效
第六步：释放资源