Implement Beauty - Facebetter

Add SDK Dependency

Method A: Maven Online Integration (Recommended)

Add the Maven repository address to your project’s root build.gradle or settings.gradle:

repositories {
    mavenCentral()
}

Add the dependency in your module’s build.gradle:

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

Alternatively, if you use the modern Version Catalog (libs.versions.toml) to manage dependencies (recommended, as used in the Demo):

Add the following to gradle/libs.versions.toml:

[versions]
facebetter = "1.2.2"

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

Use it in your module’s build.gradle:

dependencies {
    implementation libs.facebetter
}

Method B: Manual AAR Integration

Go to the Download page to get the latest SDK, then extract it. Copy the facebetter.aar library from the SDK package to your project path, such as the libs directory. Modify the project’s build.gradle and add the facebetter.aar dependency in the dependencies section:

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

Permission Configuration

Add necessary permissions in AndroidManifest.xml:

<!-- Network permission (required): for appId and appKey network verification -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Storage permission (optional): only needed when writing log files -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- Camera permission (optional): only needed when using camera capture in demo -->
<uses-permission android:name="android.permission.CAMERA" />

Permission Descriptions:

Network Permission: Required. SDK needs network connection to verify appId and appKey to ensure the app runs normally.
Storage Permission: Optional. Only needed when file logging is configured (logConfig.fileEnabled = true).
Camera Permission: Optional. Only needed when using camera capture for beauty processing in the app. Not required if only processing existing images.

Import Classes

Facebetter engine mainly has four classes that need to be imported into the files where they are used:

import net.pixpark.facebetter.BeautyEffectEngine;
import net.pixpark.facebetter.BeautyParams.*;
import net.pixpark.facebetter.ImageBuffer;
import net.pixpark.facebetter.ImageFrame;

Log Configuration

Logging is disabled by default and can be enabled as needed. Both console logging and file logging switches are supported.

Logging should be enabled before creating the beauty engine, otherwise you may not see initialization logs.

BeautyEffectEngine.LogConfig logConfig = new BeautyEffectEngine.LogConfig();
// Console logging
logConfig.consoleEnabled = true;
// File logging
logConfig.fileEnabled = true;
// Log level
logConfig.level = BeautyEffectEngine.LogLevel.INFO;
// Log storage path
logConfig.fileName = "xx/xx/facebetter.log";
BeautyEffectEngine.setLogConfig(logConfig);

Create Configuration Engine

Follow the instructions on this page to get your appid and appkey. Verification Priority:

If licenseJson is provided, use license data verification (supports online response and offline license)
Otherwise, use appId and appKey for automatic online verification

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId"; // Configure your appid (optional, not required if licenseJson is provided)
config.appKey = "your appkey"; // Configure your appkey (optional, not required if licenseJson is provided)
// Optional: Use license data verification (takes priority if provided)
// config.licenseJson = "your license json string";
mBeautyEngine = new BeautyEffectEngine(this, config);

Error Handling

After creating the engine, it’s recommended to check if it was successful:

if (mBeautyEngine == null) {
    Log.e("BeautyEngine", "Failed to create beauty engine");
    return;
}

Adjust Beauty Parameters

All beauty parameters range from [0.0, 1.0]. Set to 0 to disable the effect.

Set Skin Beauty Parameters

Use the setBeautyParam interface to set skin beauty parameters. Parameter range [0.0, 1.0].

float value = 0.5; // Value range [0.0, 1.0]
int ret = mBeautyEngine.setBeautyParam(BasicParam.SMOOTHING, value);

Supported skin beauty parameters:

public static enum BasicParam {
    SMOOTHING(0),   // Smoothing
    SHARPENING(1),  // Sharpening
    WHITENING(2),   // Whitening
    ROSINESS(3);    // Rosiness
}

Set Skin-Only Beauty

Use the setSkinOnlyBeauty interface to set whether beauty effects are applied only to skin regions. When enabled, beauty effects (smoothing, whitening, etc.) will only be applied to detected skin areas, leaving non-skin areas unchanged.

// Enable skin-only beauty
int ret = mBeautyEngine.setSkinOnlyBeauty(true);

// Disable skin-only beauty (apply to entire image)
ret = mBeautyEngine.setSkinOnlyBeauty(false);

After enabling skin-only beauty, even with high beauty parameter values, non-skin areas (such as background, clothing, etc.) will not be affected.

Set Face Reshape Parameters

Use the setBeautyParam interface to set face reshape parameters. Parameter range [0.0, 1.0].

beautyEffectEngine.setBeautyParam(BeautyParams.ReshapeParam.FACE_THIN, 0.5f);

Supported face reshape parameters:

public enum ReshapeParam {
  FACE_THIN(0),      // Face thinning
  FACE_V_SHAPE(1),   // V-shaped face
  FACE_NARROW(2),    // Narrow face
  FACE_SHORT(3),     // Short face
  CHEEKBONE(4),      // Cheekbone
  JAWBONE(5),        // Jawbone
  CHIN(6),           // Chin
  NOSE_SLIM(7),      // Nose slimming
  EYE_SIZE(8),       // Eye enlargement
  EYE_DISTANCE(9);   // Eye distance
}

Set Makeup Parameters

beautyEffectEngine.setBeautyParam(BeautyParams.MakeupParam.LIPSTICK, 0.5f);

Supported makeup parameters:

public enum MakeupParam {
  LIPSTICK(0),  // Lipstick
  BLUSH(1);     // Blush
}

Set Virtual Background

Enable virtual background through the setVirtualBackground interface:

// Set background mode
BeautyParams.VirtualBackgroundOptions options = new BeautyParams.VirtualBackgroundOptions();
options.mode = BeautyParams.BackgroundMode.BLUR;  // Blur background
beautyEffectEngine.setVirtualBackground(options);

// Set background image (need to set to IMAGE mode first)
BeautyParams.VirtualBackgroundOptions imageOptions = new BeautyParams.VirtualBackgroundOptions();
imageOptions.mode = BeautyParams.BackgroundMode.IMAGE;
imageOptions.backgroundImage = imageFrame;  // ImageFrame object
beautyEffectEngine.setVirtualBackground(imageOptions);

Using Filters and Stickers

Filter Functionality

Filters are set through the setFilter interface. Filter resource files (.fbd) must be registered via registerFilter first.

// 1. Register filter resource
String filterId = "chuxin";
String fbdPath = getFilesDir() + "/filters/chuxin.fbd";
mBeautyEngine.registerFilter(filterId, fbdPath);

// 2. Use filter
mBeautyEngine.setFilter(filterId);

// 3. Adjust filter intensity (0.0 - 1.0)
mBeautyEngine.setFilterIntensity(0.8f);

Sticker Functionality

Stickers are set through the setSticker interface and also need to be registered first.

// 1. Register sticker resource
String stickerId = "cherry";
String fbdPath = getFilesDir() + "/stickers/cherry.fbd";
mBeautyEngine.registerSticker(stickerId, fbdPath);

// 2. Use sticker
mBeautyEngine.setSticker(stickerId);

// 3. Clear sticker
mBeautyEngine.setSticker("");

Set Callbacks

Monitor engine events (license validation and engine initialization status):

EngineCallbacks callbacks = new EngineCallbacks();
callbacks.onEngineEvent = (code, message) -> {
    if (code == EngineEventCode.LICENSE_VALIDATION_SUCCESS) {
        // License validation succeeded
        Log.d(TAG, "License validation succeeded");
    } else if (code == EngineEventCode.LICENSE_VALIDATION_FAILED) {
        // License validation failed
        Log.e(TAG, "License validation failed: " + message);
    } else if (code == EngineEventCode.INITIALIZATION_COMPLETE) {
        // Engine initialization completed
        Log.d(TAG, "Engine initialization completed");
    } else if (code == EngineEventCode.INITIALIZATION_FAILED) {
        // Engine initialization failed
        Log.e(TAG, "Engine initialization failed: " + message);
    }
};
beautyEffectEngine.setCallbacks(callbacks);

Event codes:

EngineEventCode.LICENSE_VALIDATION_SUCCESS (0): License validation succeeded
EngineEventCode.LICENSE_VALIDATION_FAILED (1): License validation failed
EngineEventCode.INITIALIZATION_COMPLETE (100): Engine initialization completed
EngineEventCode.INITIALIZATION_FAILED (101): Engine initialization failed

Process Images

ImageFrame objects must call release() after use, otherwise it will cause memory leaks.

Create Images

Image data is encapsulated through ImageFrame, supporting formats: I420, NV12, NV21, RGB, RGBA, BGR, BGRA. Create ImageFrame with RGBA

ByteBuffer data = ByteBuffer.allocateDirect(width * height * 4);
ImageFrame inputImage = ImageFrame.createWithRGBA(data, width, height, stride);

Create ImageFrame with image file

ImageFrame inputImage = ImageFrame.createWithFile("xxx.png");

Rotate Images

ImageFrame has built-in image rotation methods that can be used as needed.

int result = inputImage.rotate(ImageBuffer.Rotation.ROTATION_90);

Rotation angles

public enum Rotation {
  ROTATION_0(0),    // 0 degrees
  ROTATION_90(1),   // Clockwise 90 degrees
  ROTATION_180(2),  // Clockwise 180 degrees
  ROTATION_270(3);  // Clockwise 270 degrees
}

Process Images

processMode includes VIDEO and IMAGE modes. VIDEO mode is suitable for live streaming and video scenarios with higher efficiency. IMAGE mode is suitable for image processing scenarios.

inputImage.type = ImageFrame.FrameType.VIDEO;
ImageFrame outputImage = beautyEffectEngine.processImage(inputImage);

The engine automatically maintains input/output format consistency. If input is NV21 format, output is NV21 format; if input is RGBA format, output is RGBA format.

Get Processed Image Data

ImageBuffer buffer = outputImage.toRGBA();
ByteBuffer data = buffer.getData();
int dataSize = buffer.getSize();

int width = buffer.getWidth();
int height = buffer.getHeight();
int stride = buffer.getStride();

Get I420 data

ImageBuffer buffer = outputImage.toI420();
// Get continuous I420 memory data
ByteBuffer data = buffer.getData();
// Get I420 data length
int dataSize = buffer.getSize();
// Get Y, U, V component data separately
ByteBuffer dataY = buffer.getDataY();
ByteBuffer dataU = buffer.getDataU();
ByteBuffer dataV = buffer.getDataV();

int strideY = buffer.getStrideY();
int strideU = buffer.getStrideU();
int strideV = buffer.getStrideV();

ImageFrame can be converted to various formats through built-in toXXX methods: I420, NV12, NV21, RGB, RGBA, BGR, BGRA. These methods can be used for format conversion.

External Texture Processing

When using external texture processing, you must ensure the OpenGL context is on the main thread and pass externalContext = true during engine initialization.

Use Cases

External texture processing is suitable for the following scenarios:

OpenGL/OpenGL ES Rendering Pipeline Integration: When your application already uses OpenGL for rendering, you can directly use textures as input and output, avoiding CPU-GPU data copying
Real-time Video Processing: Process textures directly in video rendering callbacks to reduce memory copy overhead
Performance Optimization: Avoid downloading texture data to CPU memory and uploading back to GPU, improving processing efficiency

Configure External Context

When using external texture processing, you need to enable the externalContext option when creating the engine:

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId";
config.appKey = "your appKey";
config.externalContext = true;  // Enable external context mode

BeautyEffectEngine engine = new BeautyEffectEngine(context, config);

Important Notes:

When externalContext = true, the engine will not create its own OpenGL context, but use the current thread’s OpenGL context
The engine must be created in a valid OpenGL context
Input and output textures must be in the same OpenGL context

Create Texture Frame

Use the ImageFrame.createWithTexture() method to create an image frame from an OpenGL texture:

// Create ImageFrame from OpenGL texture
int textureId = ...;  // Your OpenGL texture ID
int width = 1920;
int height = 1080;
int stride = width * 4;  // RGBA format, 4 bytes per pixel

ImageFrame inputFrame = ImageFrame.createWithTexture(textureId, width, height, stride);
if (inputFrame == null) {
    Log.e(TAG, "Failed to create ImageFrame from texture");
    return;
}

Parameter Description:

textureId: OpenGL texture ID (type GL_TEXTURE_2D)
width: Texture width (pixels)
height: Texture height (pixels)
stride: Row stride (bytes), usually width * 4 (RGBA format)

Get Output Texture

After processing the image, you can get the output texture through ImageBuffer.getTexture():

// Process image
inputFrame.type = ImageFrame.FrameType.IMAGE;
ImageFrame outputFrame = engine.processImage(inputFrame);
if (outputFrame == null) {
    Log.e(TAG, "processImage returned null");
    return;
}

// Get output texture
ImageBuffer textureBuffer = outputFrame.getBuffer();
if (textureBuffer == null) {
    Log.e(TAG, "getBuffer returned null");
    return;
}

// Get output texture ID and dimensions
int outputTextureId = textureBuffer.getTexture();
int outputWidth = textureBuffer.getWidth();
int outputHeight = textureBuffer.getHeight();

Complete Example

public class ExternalTextureActivity extends AppCompatActivity
    implements GLTextureRenderer.OnProcessVideoFrameCallback {
    
    private BeautyEffectEngine engine;
    
    @Override
    public int onProcessVideoFrame(
        GLTextureRenderer.TextureFrame srcFrame, 
        GLTextureRenderer.TextureFrame dstFrame) {
        
        // Lazy initialize engine (in OpenGL context)
        if (engine == null) {
            BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
            config.appId = "your appId";
            config.appKey = "your appKey";
            config.externalContext = true;  // Key: enable external context
            
            engine = new BeautyEffectEngine(this, config);
            engine.setBeautyParam(BasicParam.SMOOTHING, 0.5f);
        }
        
        // Create ImageFrame from input texture
        int stride = srcFrame.width * 4;
        ImageFrame inputFrame = ImageFrame.createWithTexture(
            srcFrame.textureId, srcFrame.width, srcFrame.height, stride);
        if (inputFrame == null) {
            return -1;
        }
        
        // Process image
        ImageFrame outputFrame = engine.processImage(
            inputFrame, BeautyEffectEngine.ProcessMode.IMAGE);
        if (outputFrame == null) {
            return -2;
        }
        
        // Get output texture
        ImageBuffer textureBuffer = outputFrame.getBuffer();
        if (textureBuffer == null) {
            return -3;
        }
        
        // Set output texture information
        dstFrame.textureId = textureBuffer.getTexture();
        dstFrame.width = textureBuffer.getWidth();
        dstFrame.height = textureBuffer.getHeight();
        
        return 0;  // Success
    }
}

Important Notes

1. Context Requirements

Engine must be created in a valid OpenGL context: When externalContext = true, the engine uses the current thread’s OpenGL context, so the engine must be created in the OpenGL rendering thread
Context consistency: Input texture, engine processing, and output texture must be in the same OpenGL context
Thread safety: OpenGL operations must be executed in the same thread

2. Texture Format Requirements

Input texture format: Supports GL_RGBA format GL_TEXTURE_2D textures

Texture parameters: It is recommended to set the following texture parameters for best results:

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);

3. Performance Optimization

Lazy initialization: Initialize the engine in the first rendering callback to ensure it is created in the correct OpenGL context
Reuse ImageFrame: If possible, reuse ImageFrame objects to reduce object creation overhead
Process mode selection:
- ProcessMode.VIDEO: Suitable for real-time video stream processing, higher performance
- ProcessMode.IMAGE: Suitable for single frame image processing, better quality

4. Memory Management

Release resources timely: Release ImageFrame and ImageBuffer objects after use
Texture lifecycle: Output textures are managed by the engine and do not need manual deletion, but input textures need to be managed by the caller

5. Error Handling

Check return values: All API calls should check return values
Null pointer checks: Check if return values of createWithTexture() and processImage() are null
Texture validity: Ensure input texture ID is valid and bound to the current OpenGL context

6. Common Issues

Engine creation failure: Check if it is created in an OpenGL context and if externalContext is correctly set
Texture processing failure: Check if texture format is RGBA and texture parameters are correctly set
Context loss: If the OpenGL context is destroyed, the engine needs to be recreated

Lifecycle Management

You must call release() to release engine resources when Activity/Fragment is destroyed, otherwise it will cause memory leaks.

Release Resources

When Activity or Fragment is destroyed, be sure to release engine resources:

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

Memory Management

Release ImageFrame and ImageBuffer objects timely
Avoid repeatedly creating large numbers of image objects in loops
Recommend reusing ImageFrame objects

// Release resources after use
if (inputImage != null) {
    inputImage.release();
}
if (outputImage != null) {
    outputImage.release();
}
if (buffer != null) {
    buffer.release();
}

Best Practices - Performance optimization and architecture design recommendations
Common Issues - Common questions and troubleshooting
API Reference - Complete API documentation

​Add SDK Dependency

​Method A: Maven Online Integration (Recommended)

​Method B: Manual AAR Integration

​Permission Configuration

​Import Classes

​Log Configuration

​Create Configuration Engine

​Error Handling

​Adjust Beauty Parameters

​Set Skin Beauty Parameters

​Set Skin-Only Beauty

​Set Face Reshape Parameters

​Set Makeup Parameters

​Set Virtual Background

​Using Filters and Stickers

​Filter Functionality

​Sticker Functionality

​Set Callbacks

​Process Images

​Create Images

​Rotate Images

​Process Images

​Get Processed Image Data

​External Texture Processing

​Use Cases

​Configure External Context

​Create Texture Frame

​Get Output Texture

​Complete Example

​Important Notes

​1. Context Requirements

​2. Texture Format Requirements

​3. Performance Optimization

​4. Memory Management

​5. Error Handling

​6. Common Issues

​Lifecycle Management

​Release Resources

​Memory Management

​Related Documentation

Add SDK Dependency

Method A: Maven Online Integration (Recommended)

Method B: Manual AAR Integration

Permission Configuration

Import Classes

Log Configuration

Create Configuration Engine

Error Handling

Adjust Beauty Parameters

Set Skin Beauty Parameters

Set Skin-Only Beauty

Set Face Reshape Parameters

Set Makeup Parameters

Set Virtual Background

Using Filters and Stickers

Filter Functionality

Sticker Functionality

Set Callbacks

Process Images

Create Images

Rotate Images

Process Images

Get Processed Image Data

External Texture Processing

Use Cases

Configure External Context

Create Texture Frame

Get Output Texture

Complete Example

Important Notes

1. Context Requirements

2. Texture Format Requirements

3. Performance Optimization

4. Memory Management

5. Error Handling

6. Common Issues

Lifecycle Management

Release Resources

Memory Management

Related Documentation