Implement Beauty

Add the SDK

Method A: Maven (recommended)

In the project build.gradle / settings.gradle repositories:

repositories {
    mavenCentral()
}

Module build.gradle:

dependencies {
    implementation 'net.pixpark:facebetter:2.0.0'
}

Version Catalog (gradle/libs.versions.toml):

[versions]
facebetter = "2.0.0"

[libraries]
facebetter = { group = "net.pixpark", name = "facebetter", version.ref = "facebetter" }

dependencies {
    implementation libs.facebetter
}

Method B: Local AAR

Download the SDK from Download, copy facebetter.aar into libs/, then:

dependencies {
    implementation files('libs/facebetter.aar')
    implementation libs.appcompat
    implementation libs.material
}

Permissions

AndroidManifest.xml:

<!-- Required for online auth (appId + appKey → /facebetter/v2/auth) -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Optional: only if you write SDK logs outside app storage -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- Optional: camera preview / live beauty -->
<uses-permission android:name="android.permission.CAMERA" />

Permission	When
Network	Required for online `appId` + `appKey`. Offline `licenseToken` does not need the network for validation
Storage	Only if `LogConfig.fileEnabled` writes outside the app directory
Camera	Only if you capture live frames

Request CAMERA at runtime on API 23+.

Imports

import net.pixpark.facebetter.BeautyEffectEngine;
import net.pixpark.facebetter.BeautyParams.*;
import net.pixpark.facebetter.EngineCallbacks;
import net.pixpark.facebetter.EngineEventCode;
import net.pixpark.facebetter.EngineStats;
import net.pixpark.facebetter.ErrorCode;
import net.pixpark.facebetter.ImageFrame;

Logging

Logging is off by default. Enable it before new BeautyEffectEngine(...).

Call setLogConfig before constructing the engine, or you will miss initialization logs.

BeautyEffectEngine.LogConfig logConfig = new BeautyEffectEngine.LogConfig();
logConfig.consoleEnabled = true;
logConfig.fileEnabled = true;
logConfig.level = BeautyEffectEngine.LogLevel.INFO;
logConfig.fileName = getFilesDir() + "/facebetter.log";
BeautyEffectEngine.setLogConfig(logConfig);

Create the engine

Credentials: Subscription. Auth details: Auth & License. If licenseToken is non-empty, it is used (license token / {token} JSON / offline .lic). Otherwise appId + appKey call /facebetter/v2/auth.

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId";
config.appKey = "your appKey";
// config.licenseToken = "/* license token, {token} JSON, or .lic contents */";
// config.externalContext = false;

BeautyEffectEngine engine;
try {
    engine = new BeautyEffectEngine(this, config);
} catch (IllegalArgumentException e) {
    Log.e(TAG, "Invalid EngineConfig", e);
    return;
}

The constructor does not return null; it throws if config is invalid. Watch EngineEventCode.INITIALIZATION_COMPLETE / INITIALIZATION_FAILED on callbacks for async init.

Beauty

Intensity [0.0, 1.0]. 0 disables the effect. Check ErrorCode.SUCCESS (0).

engine.setSmoothing(0.5f);
engine.setSmoothingStyle(SmoothingStyle.NATURAL);
engine.setWhitening(0.3f);
engine.setWhiteningStyle(WhiteningStyle.COLD_WHITE);
engine.setSharpening(0.2f);
engine.setRosiness(0.15f);
engine.setBeautySkinOnly(true);

With setBeautySkinOnly(true), smoothing / whitening / sharpening / rosiness apply only on detected skin. Clothing and background stay unchanged.

Styles: Parameter enums.

Reshape

Range [-1.0, 1.0]. 0 is off.

engine.setReshape(Reshape.FACE_THIN, 0.4f);
engine.setReshape(Reshape.EYE_SIZE, 0.3f);
engine.setReshape(Reshape.CHIN, -0.2f);

All 26 parameters (FACE_THIN … BROW_THICKNESS) and positive / negative directions: Parameter enums.

Body reshape

Range [0.0, 1.0]. 0 is off. Register resource_body.fbd with addResourcePack first (not in the AAR). See Parameter enums and Optional resource packs.

engine.addResourcePack(loadAssetBytes("resource_body.fbd"));
engine.setBodyReshape(BodyReshape.WAIST_SLIM, 0.4f);
engine.setBodyReshape(BodyReshape.LEG_STRETCH, 0.3f);
engine.setBodyReshape(BodyReshape.TORSO_LONG, 0.3f);

Makeup

Set intensity, then style and/or color.

engine.setLipstick(0.6f);
engine.setLipstickColor(LipstickColor.ROUGE);

engine.setBlush(0.4f);
engine.setBlushStyle(BlushStyle.SUN_KISSED);
engine.setBlushColor(BlushColor.CORAL_PINK);

engine.setContour(0.35f);
engine.setContourStyle(ContourStyle.NATURAL);

engine.setEyeShadow(0.45f);
engine.setEyeShadowStyle(EyeShadowStyle.SOFT);
engine.setEyeShadowColor(EyeShadowColor.PLUM);

engine.setEyeLiner(0.4f);
engine.setEyeLinerStyle(EyeLinerStyle.CLASSIC);

engine.setEyebrow(0.35f);
engine.setEyebrowStyle(EyebrowStyle.NATURAL);

engine.setEyelash(0.4f);
engine.setEyelashStyle(EyelashStyle.CLASSIC);

engine.setPupil(0.3f);
engine.setPupilColor(PupilColor.HAZEL);

Full preset lists: Parameter enums.

Virtual background and chroma key

Blur (0 clears), still image, or chroma-key mask + fill.

engine.setVirtualBackgroundBlur(0.6f);

int ret = engine.setVirtualBackground("/sdcard/bg.jpg");
if (ret != ErrorCode.SUCCESS) {
    Log.e(TAG, "setVirtualBackground failed: " + ret);
}

byte[] png = loadAssetBytes("backgrounds/office.png");
engine.setVirtualBackground(png);

engine.setChromaKey(ChromaKeyColor.GREEN);
engine.setChromaKeySimilarity(0.4f);
engine.setChromaKeySmoothness(0.3f);
engine.setChromaKeyDesaturation(0.2f);

engine.clearChromaKey();
engine.clearVirtualBackground();

clearChromaKey() restores portrait segmentation and does not remove the current blur/image fill.

Filters and stickers

Load a .fbd from a file path or assets. No register step.

engine.setFilter(getFilesDir() + "/filters/vivid.fbd");
engine.setFilterIntensity(0.8f);

byte[] lut = loadAssetBytes("filters/vivid.fbd");
engine.setFilter(lut);

engine.clearFilter();

engine.setSticker(getFilesDir() + "/stickers/cherry.fbd");
byte[] sticker = loadAssetBytes("stickers/cherry.fbd");
engine.setSticker(sticker);
engine.clearSticker();

3D stickers need the optional resource_3d.fbd pack (not in the AAR). See Optional resource packs. Register it from your app assets, then apply a 3D sticker .fbd:

engine.addResourcePack(loadAssetBytes("resource_3d.fbd"));
engine.set3DSticker(loadAssetBytes("stickers/3d/oculos.fbd"));
engine.clear3DSticker();

Filter / sticker changes take effect on the next processImage.

private byte[] loadAssetBytes(String path) throws IOException {
    try (InputStream in = getAssets().open(path);
         ByteArrayOutputStream out = new ByteArrayOutputStream()) {
        byte[] buf = new byte[4096];
        int n;
        while ((n = in.read(buf)) >= 0) {
            out.write(buf, 0, n);
        }
        return out.toByteArray();
    }
}

Callbacks and stats

EngineCallbacks callbacks = new EngineCallbacks();
callbacks.onEngineEvent = (code, message) -> {
    switch (code) {
        case EngineEventCode.LICENSE_VALIDATION_SUCCESS:
            Log.d(TAG, "License OK");
            break;
        case EngineEventCode.LICENSE_VALIDATION_FAILED:
            Log.e(TAG, "License failed: " + message);
            break;
        case EngineEventCode.INITIALIZATION_COMPLETE:
            Log.d(TAG, "Engine ready");
            break;
        case EngineEventCode.INITIALIZATION_FAILED:
            Log.e(TAG, "Init failed: " + message);
            break;
        default:
            break;
    }
};
callbacks.onFaceLandmarks = results -> {
    Log.d(TAG, "faces=" + results.size());
};
engine.setCallbacks(callbacks);

EngineStats stats = engine.getStats();
Log.d(TAG, "fps=" + stats.fps + " avgMs=" + stats.avgProcessTimeMs
    + " sessionS=" + stats.sessionTimeS);

Process frames

Call ImageFrame.release() on every frame you create (and on processImage output). Skipping this leaks native memory.

Set ImageFrame.type to FrameType.IMAGE (still) or FrameType.VIDEO (camera / live). processImage takes only the frame — no extra mode argument.

ByteBuffer data = ByteBuffer.allocateDirect(width * height * 4);
ImageFrame input = ImageFrame.createWithRGBA(data, width, height, width * 4);
input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);

From a file or Bitmap:

ImageFrame input = ImageFrame.createWithFile("/sdcard/photo.jpg");
input.type = ImageFrame.FrameType.IMAGE;
ImageFrame output = engine.processImage(input);
Bitmap preview = output.toBitmap();

Rotate / mirror before processing if the camera sensor is rotated:

input.rotate(ImageFrame.Rotation.ROTATION_90);
input.mirror("horizontal");

The engine keeps input and output pixel formats aligned (NV21 in → NV21 out, RGBA in → RGBA out).

Read pixels with getData() / planar accessors, or convert:

ImageFrame rgba = output.convert(ImageFrame.Format.RGBA);
ByteBuffer pixels = rgba.getData();
int w = rgba.getWidth();
int h = rgba.getHeight();
int stride = rgba.getStride();
rgba.release();

ImageFrame i420 = output.convert(ImageFrame.Format.I420);
ByteBuffer y = i420.getDataY();
ByteBuffer u = i420.getDataU();
ByteBuffer v = i420.getDataV();
i420.release();

Camera pipeline

Typical Camera2 YUV_420_888 → engine → display:

Image.Plane[] planes = image.getPlanes();
ImageFrame input = ImageFrame.createWithAndroid420(
    image.getWidth(), image.getHeight(),
    planes[0].getBuffer(), planes[0].getRowStride(),
    planes[1].getBuffer(), planes[1].getRowStride(),
    planes[2].getBuffer(), planes[2].getRowStride(),
    planes[1].getPixelStride());
if (input == null) {
    image.close();
    return;
}
if (isFrontCamera) {
    input.rotate(ImageFrame.Rotation.ROTATION_270);
    input.mirror("horizontal");
} else {
    input.rotate(ImageFrame.Rotation.ROTATION_90);
}
input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);
image.close();

External texture (OpenGL ES)

Create the engine on the GL thread with externalContext = true. Input and output textures must share that context.

Use this when you already render with OpenGL ES and want to avoid CPU round-trips.

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId";
config.appKey = "your appKey";
config.externalContext = true;
BeautyEffectEngine engine = new BeautyEffectEngine(context, config);
engine.setSmoothing(0.5f);

int stride = srcWidth * 4;
ImageFrame input = ImageFrame.createWithTexture(srcTextureId, srcWidth, srcHeight, stride);
if (input == null) {
    return;
}
input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);
if (output == null) {
    input.release();
    return;
}
int dstTextureId = output.getTexture();
int dstWidth = output.getWidth();
int dstHeight = output.getHeight();
output.release();
input.release();

Recommended sampler state for input GL_TEXTURE_2D:

GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR);
GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR);
GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE);
GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE);

Notes:

Input texture: GL_TEXTURE_2D, typically RGBA; stride is usually width * 4
Lazy-create the engine in the first GL callback so the context is current
Output texture is owned by the SDK; do not glDeleteTextures it. Release the ImageFrame
If the GL context is lost, release() the engine and create it again on the new context
Use FrameType.VIDEO for live GL pipelines
For TRTC / Agora / LiveKit and similar SDKs: Third-party Integration

Lifecycle

Call engine.release() in onDestroy / onDetach. Unreleased engines leak GPU and native memory.

@Override
protected void onDestroy() {
    super.onDestroy();
    if (mBeautyEngine != null) {
        mBeautyEngine.release();
        mBeautyEngine = null;
    }
}

if (input != null) {
    input.release();
}
if (output != null) {
    output.release();
}

Introduction

Android

iOS

macOS

Windows

Linux

Web

Add the SDK

Method A: Maven (recommended)

Method B: Local AAR

Permissions

Imports

Logging

Create the engine

Beauty

Reshape

Body reshape

Makeup

Virtual background and chroma key

Filters and stickers

Callbacks and stats

Process frames

Camera pipeline

External texture (OpenGL ES)

Lifecycle

​Add the SDK

​Method A: Maven (recommended)

​Method B: Local AAR

​Permissions

​Imports

​Logging

​Create the engine

​Beauty

​Reshape

​Body reshape

​Makeup

​Virtual background and chroma key

​Filters and stickers

​Callbacks and stats

​Process frames

​Camera pipeline

​External texture (OpenGL ES)

​Lifecycle

​Related

Add the SDK

Method A: Maven (recommended)

Method B: Local AAR

Permissions

Imports

Logging

Create the engine

Beauty

Reshape

Body reshape

Makeup

Virtual background and chroma key

Filters and stickers

Callbacks and stats

Process frames

Camera pipeline

External texture (OpenGL ES)

Lifecycle

Related