Integrating Faceunity Beauty SDK with NERtc on Android and iOS

Beauty Introduction

This manual is intended for SO and operations members. It explains the basic concepts of beauty effects, the main integration process, and common difficulties.

Related Knowledge Overview

OpenGL ES : A subset of the OpenGL 3D graphics API designed for embedded devices such as phones, PDAs, and game consoles. In beauty pipelines, OpenGL ES is typically invoked by the beauty module (e.g., Faceunity).

Android EGL : An intermediate layer between OpenGL ES and the native window system. EGL maintains context information for the current GL thread and is thread‑related.

iOS EAGL : Apple’s EGL‑like framework for iOS, providing an Objective‑C API that bridges OpenGL ES with Core Animation and UIKit.

Faceunity (相芯) Beauty SDK

Full name: Faceunity Nama SDK (referred to as NAMA).

Android Beauty Flow

Data is processed via the SDK’s callback and then sent to the SDK for rendering (see flow diagram).

Tag 1 recommends a 360P+15fps configuration using texture rendering.

Tag 4 requires OES texture rendering during NAMA SDK initialization (see code snippet).

Tags 2, 5, 6 involve setting NERtcSDK callbacks to invoke the third‑party beauty interface; highlighted code should be reviewed.

iOS Beauty Flow

Developers can call NAMA SDK interfaces directly within the NERtcSDK video capture callback. The process is illustrated in the diagram below.

SDK Integration Resources

Official documentation: https://www.faceunity.com/developer-center.html

Android SDK version: GitHub releases

Android Sample Code: https://github.com/netease-im/Advanced-Video/tree/master/Beauty/Beauty-Android-Java

Solution 1 – Texture Rendering

Tag 1 suggests using a 360P+15fps texture rendering mode.

Solution 2 – NV21 Rendering

Set NERtcSDK rendering format to NV21. Since NV21 is used, NAMA does not need OES rendering (code highlighted in red).

Solution 3 – Dual‑Input Rendering (Texture + YUV)

Recommended to use texture + I420 to reduce data conversion. The dual‑input scheme still prefers texture input.

Modify FuRenderer.java as shown in the diagram.

iOS/macOS Usage

Official docs: https://www.faceunity.com/developer-center.html

iOS SDK list: GitHub releases

macOS SDK list: GitHub releases

Obtaining Certificates

Contact Faceunity to purchase the service and obtain the certificate file (typically authpack.h).

SDK Integration

iOS integration offers two methods:

Use CocoaPods – add the required pod to the Podfile and run pod install.

Direct download – FaceUnity‑SDK‑iOS‑v7.4.1.zip .

macOS integration also provides CocoaPods and direct download options.

Device Orientation Adaptation (iOS only)

Use CMMotionManager to obtain device orientation and configure the Faceunity interface before processing each frame.

Video Image Processing Interface

The interface takes a pixelBuffer as both input and output; developers must maintain a frame ID (increment after each call) and provide an items array of resource IDs (default 0).

Resource Management

Define an enumeration for resource IDs returned by Faceunity interfaces. Stickers, animoji, and AR masks are treated as normal items and should be created/destroyed as needed; beauty items can be retained long‑term.

Beauty Parameters, Filters, and Stickers

Refer to the documentation for iOS and macOS to see parameter ranges and usage examples.

Common Issues

After releasing NERtcSDK, also call destroyFU() to release Faceunity resources; otherwise the preview may flash black or garbled.

Green screen after enabling beauty indicates the NERtc video frame format should be set to TEXTURE_RGB.

Android Specifics

Minimum system version: Android 4.3 (API 18) with OpenGL ES 2.0 support. No need to create an EGL context manually; NERtcSDK’s view handles it.

iOS Specifics

Minimum system version: iOS 9.0+. In setupWithData, set shouldCreateContext to YES to let Faceunity create its own context.

macOS Specifics

Minimum system version: macOS 10.6+. Same recommendation for context creation as iOS.

Summary

With the rise of video chat, many customers adopt beauty effects to enhance visual quality. Third‑party beauty SDKs such as Faceunity provide complete code samples. By routing video frames through the external beauty library and returning the processed frames to NERtc, developers can quickly integrate and troubleshoot beauty features.