Implement Android Beauty

Integrate SDK

Download SDK

Go to the Download page to get the latest SDK, then extract it.

Add Dependencies

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. Configure the path of facebetter.aar according to your situation.

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 com.pixpark.facebetter.BeautyEffectEngine;
import com.pixpark.facebetter.BeautyParams.*;
import com.pixpark.facebetter.ImageBuffer;
import com.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.

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.

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId"; // Configure your appid
config.appKey = "your appkey"; // Configure your appkey
// Or provide licenseJson directly (optional, if provided, takes priority and appId/appKey are not required)
// 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;
}

Enable Effect Types

Beauty features can be enabled or disabled by type. Enable corresponding beauty types according to your subscription version. Each type also has corresponding parameters that can be adjusted.

// Basic beauty, supported by all subscription versions
int ret = mBeautyEngine.enableBeautyType(BeautyType.BASIC, true);
// Face reshape, supported by Pro, Pro+ versions
int ret = mBeautyEngine.enableBeautyType(BeautyType.RESHAPE, true);
// Makeup, supported by Pro, Pro+ versions
int ret = mBeautyEngine.enableBeautyType(BeautyType.MAKEUP, true);
// Virtual background, only supported by Pro+ version
int ret = mBeautyEngine.enableBeautyType(BeautyType.VIRTUAL_BACKGROUND, true);

Check Operation Results

All API calls should check return values:

int ret = mBeautyEngine.enableBeautyType(BeautyType.BASIC, true);
if (ret == 0) {
    Log.d("BeautyEngine", "Successfully enabled basic beauty");
} else {
    Log.e("BeautyEngine", "Failed to enable basic beauty, error code: " + ret);
}

Adjust Beauty Parameters

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 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 enableBeautyType interface:

beautyEffectEngine.enableBeautyType(BeautyParams.BeautyType.VIRTUAL_BACKGROUND, true);

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

Process Images

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.

ImageFrame outputImage = beautyEffectEngine.processImage(inputImage, BeautyEffectEngine.ProcessMode.VIDEO);

Get Processed Image Data

ImageFrame can get processed image data through ImageBuffer, such as RGBA.

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.

Lifecycle Management

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

Related Documentation

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