Best Practices

Choose FrameType

Set ImageFrame.type before processImage. There is no extra mode argument. FrameType.VIDEO (default)

Camera preview, video calls, live streaming
Lower latency

FrameType.IMAGE

Gallery photos, export, capture stills
Higher quality, more cost per frame

input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);

Large stills (preview vs export)

Do not feed full-resolution pixels into processImage on every slider change, and do not throw the original away after scaling. When the photo opens, keep the full Bitmap and build one preview frame (long edge about 1280–1440). Slider changes call processImage on the preview (FrameType.IMAGE). Export calls processImage on a full-resolution frame with the same setters. Output size matches the input frame — do not upscale the preview. Camera preview stays capture resolution + FrameType.VIDEO.

preview.type = ImageFrame.FrameType.IMAGE;
ImageFrame previewOut = engine.processImage(preview);

full.type = ImageFrame.FrameType.IMAGE;
ImageFrame exportOut = engine.processImage(full);

Parameter ranges

Start low; raise after you confirm face detection and FPS.

API	Range	Notes
Smoothing / whitening / sharpening / rosiness / makeup intensity / filter intensity / VB blur / chroma knobs	`[0, 1]`	`0` off
`setReshape`	`[-1, 1]`	`0` off; sign is direction

Live preview (example):

engine.setSmoothing(0.25f);
engine.setWhitening(0.12f);
engine.setRosiness(0.08f);
engine.setReshape(Reshape.FACE_THIN, 0.15f);
engine.setReshape(Reshape.EYE_SIZE, 0.12f);

Enable setBeautySkinOnly(true) when you do not want smoothing on hair / clothes / background. Preset names: Parameter enums.

Memory

Use direct ByteBuffers when creating frames from pixel data:

ByteBuffer data = ByteBuffer.allocateDirect(width * height * 4);

Release native frames:

ImageFrame input = ImageFrame.createWithRGBA(data, width, height, stride);
try {
    input.type = ImageFrame.FrameType.VIDEO;
    ImageFrame output = engine.processImage(input);
    try {
        // draw / encode output
    } finally {
        if (output != null) {
            output.release();
        }
    }
} finally {
    if (input != null) {
        input.release();
    }
}

One engine per process / GL context; do not create per frame
Interactive stills: scale a copy for preview; keep the original Bitmap for export. See Large stills
convert() allocates a new frame — release it

OpenGL ES

When externalContext = true:

Construct the engine on the GL thread with a current context
Keep input texture, processImage, and output texture on that same context
Recreate the engine after context loss
Read the result with output.getTexture(), not a CPU download, when you stay on GPU

See Implement Beauty.

One engine, application context

Hold a single BeautyEffectEngine. Use getApplicationContext() so the engine outlives an Activity, and still release() when the session ends.

public final class BeautyEngineHolder {
    private static BeautyEngineHolder sInstance;
    private BeautyEffectEngine mEngine;

    public static synchronized BeautyEngineHolder get(Context context) {
        if (sInstance == null) {
            sInstance = new BeautyEngineHolder(context.getApplicationContext());
        }
        return sInstance;
    }

    private BeautyEngineHolder(Context app) {
        BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
        config.appId = "your_app_id";
        config.appKey = "your_app_key";
        mEngine = new BeautyEffectEngine(app, config);
    }

    public BeautyEffectEngine engine() {
        return mEngine;
    }

    public synchronized void release() {
        if (mEngine != null) {
            mEngine.release();
            mEngine = null;
        }
        sInstance = null;
    }
}

Always release() the engine when the session is done. ImageFrame objects also need release().

Off the UI thread

Run processImage on a camera / GL / dedicated thread. Post results to the main looper only for UI.

executor.execute(() -> {
    input.type = ImageFrame.FrameType.VIDEO;
    ImageFrame output = engine.processImage(input);
    mainHandler.post(() -> callback.onFrame(output));
});

Do not share one ImageFrame across threads without your own lock. The demo camera path processes the latest frame on the render thread.

Filters and stickers from assets

Keep .fbd files in assets/ and pass byte[] (or copy to filesDir and pass a path). Call setFilter / setSticker once when the user picks an effect, not every frame. Adjust mix with setFilterIntensity. GPU upload happens on the next processImage.

Monitor with getStats

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

If avgProcessTimeMs stays above ~33 ms on a live 30 FPS preview, drop resolution, use FrameType.VIDEO, or reduce simultaneous reshape / makeup / VB.

Persist user sliders

Store intensities yourself (SharedPreferences). Re-apply with setSmoothing, setReshape, setLipstick, … after the engine is created — the SDK does not persist UI state.

Lifecycle

onResume / onPause: start and stop the camera; keep the engine if you will resume soon
onDestroy / onDetach: engine.release() if this owner created it
externalContext: create / destroy on the GL thread

Tests

@Test
public void processRgbaFrame() {
    BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
    config.appId = "test_app_id";
    config.appKey = "test_app_key";
    BeautyEffectEngine engine = new BeautyEffectEngine(context, config);

    ByteBuffer data = ByteBuffer.allocateDirect(640 * 480 * 4);
    ImageFrame input = ImageFrame.createWithRGBA(data, 640, 480, 640 * 4);
    input.type = ImageFrame.FrameType.IMAGE;
    ImageFrame output = engine.processImage(input);

    assertNotNull(output);
    assertTrue(output.isValid());

    input.release();
    output.release();
    engine.release();
}

Instrument tests need a valid license (licenseToken or reachable /facebetter/v2/auth plus a bound package name).

Introduction

Android

iOS

macOS

Windows

Linux

Web

Choose FrameType

Large stills (preview vs export)

Parameter ranges

Memory

OpenGL ES

One engine, application context

Off the UI thread

Filters and stickers from assets

Monitor with getStats

Persist user sliders

Lifecycle

Tests

​Choose FrameType

​Large stills (preview vs export)

​Parameter ranges

​Memory

​OpenGL ES

​One engine, application context

​Off the UI thread

​Filters and stickers from assets

​Monitor with getStats

​Persist user sliders

​Lifecycle

​Tests

Choose FrameType

Large stills (preview vs export)

Parameter ranges

Memory

OpenGL ES

One engine, application context

Off the UI thread

Filters and stickers from assets

Monitor with getStats

Persist user sliders

Lifecycle

Tests