API Reference

This page matches SDK 2.0.0. Package: net.pixpark.facebetter. Makeup, reshape, whitening, and smoothing presets: Parameter enums. Auth: License & Auth.

All setter methods return int. 0 (ErrorCode.SUCCESS) means success; a negative value is an error code.

Logging

Call BeautyEffectEngine.setLogConfig before constructing the engine so initialization logs are captured.

LogLevel

public enum LogLevel {
  TRACE(0, "TRACE"),
  DEBUG(1, "DEBUG"),
  INFO(2, "INFO"),
  WARN(3, "WARN"),
  ERROR(4, "ERROR"),
  CRITICAL(5, "CRITICAL");
}

Method	Description
`int getLevel()`	Numeric level (`0`–`5`)
`String getName()`	Name string
`boolean isEnabledFor(LogLevel other)`	`true` if this level is at least as severe as `other`
`static LogLevel fromLevel(int level)`	Lookup by numeric value, or `null`
`static LogLevel fromName(String name)`	Case-insensitive lookup, or `null`

LogConfig

Nested class: BeautyEffectEngine.LogConfig.

Field	Type	Default	Description
`consoleEnabled`	`boolean`	`false`	Write to logcat / stdout
`fileEnabled`	`boolean`	`false`	Write to a file
`level`	`LogLevel`	`INFO`	Minimum level to emit
`fileName`	`String`	`""`	Log file path; used only when `fileEnabled` is `true`

public static class LogConfig {
  public boolean consoleEnabled = false;
  public boolean fileEnabled = false;
  public LogLevel level = LogLevel.INFO;
  public String fileName = "";

  public LogConfig();
  public LogConfig(boolean consoleEnabled, boolean fileEnabled, LogLevel level, String fileName);
}

public static void setLogConfig(LogConfig config);

Throws IllegalArgumentException if config or config.level is null.

Engine

EngineConfig

Nested class: BeautyEffectEngine.EngineConfig.

Field	Type	Default	Description
`appId`	`String`	—	Dashboard App ID
`appKey`	`String`	—	Dashboard App Key
`licenseToken`	`String`	—	License token string, `{token}` JSON, or offline `.lic` contents
`externalContext`	`boolean`	`false`	`true` = use the caller’s OpenGL ES context; `false` = SDK-owned context

Auth priority: if licenseToken is non-empty, the SDK validates that token locally. Otherwise appId + appKey are required and the SDK calls /facebetter/v2/auth. Details: License & Auth.

public static class EngineConfig {
  public String appId;
  public String appKey;
  public String licenseToken;
  public boolean externalContext = false;

  public EngineConfig();
  public EngineConfig(String appId, String appKey);
  public boolean isValid();
}

isValid() returns true when licenseToken is non-empty, or when both appId and appKey are non-empty.

BeautyEffectEngine

Main engine. Construct once, call release() when the Activity / Fragment is destroyed.

public BeautyEffectEngine(Context context, EngineConfig config);
public void release();

The constructor throws IllegalArgumentException if context or config is null, or if config.isValid() is false. The SDK reads context.getPackageName() for license binding.

FrameType

Set on ImageFrame.type before processImage. There is no separate process-mode argument.

Value	Description
`IMAGE`	Single photo / still. Higher quality.
`VIDEO`	Camera / live stream. Lower latency. Default.

public enum FrameType {
  IMAGE(0),
  VIDEO(1);
}

public ImageFrame processImage(ImageFrame inputFrame);

Reads inputFrame.type. Returns the processed frame (same pixel format as input), or null if the engine was already released. Throws IllegalArgumentException if inputFrame or inputFrame.type is null.

Beauty

Intensity range [0.0, 1.0] unless noted. 0 turns the effect off.

public int setSmoothing(float value);
public int setSmoothingStyle(SmoothingStyle style);
public int setWhitening(float value);
public int setWhiteningStyle(WhiteningStyle style);
public int setSharpening(float value);
public int setRosiness(float value);
public int setBeautySkinOnly(boolean enabled);

Method	Description
`setSmoothing`	Skin smoothing intensity
`setSmoothingStyle`	Smoothing look (`NATURAL`, `TEXTURE`, `SMOOTH`)
`setWhitening`	Whitening intensity
`setWhiteningStyle`	Whitening LUT (`COLD_WHITE`, `PINK_WHITE`, `WARM_WHITE`, `WHEAT`, `TAN`)
`setSharpening`	Sharpening intensity
`setRosiness`	Rosy-tone intensity
`setBeautySkinOnly`	`true` = apply skin beauty only on detected skin; `false` = whole frame

Style enums: Parameter enums.

Reshape

public int setReshape(Reshape param, float value);

Intensity range [-1.0, 1.0]. 0 is off. Positive and negative are opposite directions.

public enum Reshape {
  FACE_THIN(0), FACE_V_SHAPE(1), FACE_NARROW(2), FACE_SHORT(3),
  CHEEKBONE(4), JAWBONE(5), CHIN(6), NOSE_SLIM(7),
  EYE_SIZE(8), EYE_DISTANCE(9), FACE_SMALL(10), FOREHEAD(11),
  NOSE_LONG(12), PHILTRUM(13), MOUTH_SIZE(14), MOUTH_POSITION(15),
  MOUTH_SMILE(16), LIP_THICKNESS(17), EYE_ROUND(18), EYE_POSITION(19),
  EYE_ANGLE(20), EYE_CORNER_OPEN(21), LOWER_EYELID(22),
  BROW_POSITION(23), BROW_DISTANCE(24), BROW_THICKNESS(25);
}

Positive / negative meaning for each value: Parameter enums.

Makeup

Intensity [0.0, 1.0]. Set intensity, then style (mask) and/or color (tint). Pupil and contour do not take a separate tint the same way; see Parameter enums.

public int setLipstick(float value);
public int setLipstickColor(LipstickColor color);

public int setBlush(float value);
public int setBlushStyle(BlushStyle style);
public int setBlushColor(BlushColor color);

public int setContour(float value);
public int setContourStyle(ContourStyle style);

public int setEyeShadow(float value);
public int setEyeShadowStyle(EyeShadowStyle style);
public int setEyeShadowColor(EyeShadowColor color);

public int setEyeLiner(float value);
public int setEyeLinerStyle(EyeLinerStyle style);
public int setEyeLinerColor(EyeLinerColor color);

public int setEyebrow(float value);
public int setEyebrowStyle(EyebrowStyle style);
public int setEyebrowColor(EyebrowColor color);

public int setEyelash(float value);
public int setEyelashStyle(EyelashStyle style);
public int setEyelashColor(EyelashColor color);

public int setPupil(float value);
public int setPupilColor(PupilColor color);

Preset names live in BeautyParams.*. Full tables: Parameter enums.

Virtual background and chroma key

Portrait segmentation is the default mask. Chroma key replaces the mask source; fill is still blur or a still image.

public int setChromaKey(ChromaKeyColor color);
public int clearChromaKey();
public int setChromaKeySimilarity(float value);
public int setChromaKeySmoothness(float value);
public int setChromaKeyDesaturation(float value);

public int setVirtualBackgroundBlur(float level);
public int setVirtualBackground(String imagePath);
public int setVirtualBackground(byte[] imageData);
public int clearVirtualBackground();

Method	Description
`setChromaKey`	Use chroma keying as the mask (`GREEN`, `BLUE`, `RED`)
`clearChromaKey`	Restore portrait-segmentation mask; does not clear the current fill
`setChromaKeySimilarity`	How close a pixel must be to the key colour. `[0.0, 1.0]`
`setChromaKeySmoothness`	Edge feather. `[0.0, 1.0]`
`setChromaKeyDesaturation`	Spill suppression on semi-transparent edges. `[0.0, 1.0]`
`setVirtualBackgroundBlur`	Background blur. `[0.0, 1.0]`. `0` clears the virtual background
`setVirtualBackground(String)`	Replace background with a PNG/JPG file. Path must be non-empty
`setVirtualBackground(byte[])`	Same, from encoded PNG/JPG bytes
`clearVirtualBackground`	Clear blur or image fill

public enum ChromaKeyColor {
  GREEN(0),
  BLUE(1),
  RED(2);
}

Empty path / empty byte[] returns ErrorCode.INVALID_ARGUMENT.

Filters and stickers

Pass a .fbd file path or the file bytes (for example from assets). The resource takes effect on the next processed frame. There is no register / unregister API.

public int setFilter(String fbdFilePath);
public int setFilter(byte[] fbdData);
public int clearFilter();
public int setFilterIntensity(float intensity);

public int setSticker(String fbdFilePath);
public int setSticker(byte[] fbdData);
public int clearSticker();

Method	Description
`setFilter`	Apply a LUT filter from a `.fbd` path or in-memory bytes
`clearFilter`	Remove the current LUT
`setFilterIntensity`	Mix `[0.0, 1.0]`
`setSticker`	Apply a 2D sticker from a `.fbd` path or bytes
`clearSticker`	Remove the current sticker

Empty path / empty byte[] returns ErrorCode.INVALID_ARGUMENT.

Stats and callbacks

public EngineStats getStats();
public int setCallbacks(EngineCallbacks callbacks);

getStats() returns a snapshot. Fields are 0 if the engine is not initialized. setCallbacks returns ErrorCode.INVALID_ARGUMENT if callbacks is null.

EngineStats

public class EngineStats {
  public double fps;
  public double avgProcessTimeMs;
  public double sessionTimeS;

  public EngineStats();
  public EngineStats(double fps, double avgProcessTimeMs, double sessionTimeS);
}

Field	Description
`fps`	Recent processing FPS
`avgProcessTimeMs`	Average `processImage` time in milliseconds
`sessionTimeS`	Seconds since the engine was created

EngineCallbacks

public class EngineCallbacks {
  public OnFaceLandmarksCallback onFaceLandmarks;
  public OnEngineEventCallback onEngineEvent;

  public interface OnFaceLandmarksCallback {
    void onFaceLandmarks(List<FaceDetectionResult> results);
  }

  public interface OnEngineEventCallback {
    void onEngineEvent(int code, String message);
  }
}

Leave a field null to skip that callback.

EngineEventCode

public final class EngineEventCode {
  public static final int LICENSE_VALIDATION_SUCCESS = 0;
  public static final int LICENSE_VALIDATION_FAILED = 1;
  public static final int INITIALIZATION_COMPLETE = 100;
  public static final int INITIALIZATION_FAILED = 101;
}

Code	Meaning
`0`	License accepted
`1`	License rejected; `message` has detail
`100`	Engine ready to process frames
`101`	Engine init failed; `message` has detail

FaceDetectionResult

Normalized coordinates are in [0, 1] relative to the processed frame.

Field	Type	Description
`rect`	`Rect`	Face box
`keyPoints`	`List<Point2d>`	111 landmarks
`visibility`	`List<Float>`	Per-point visibility `[0, 1]`
`faceId`	`int`	Tracking id
`score`	`float`	Detection confidence `[0, 1]`
`pitch` / `roll` / `yaw`	`float`	Head pose in radians, range `[-π, π]`

Point2d has float x, y. Rect has float x, y, width, height (top-left origin).

ErrorCode

Numeric values are the same on all platforms.

public final class ErrorCode {
  public static final int SUCCESS = 0;
  public static final int INVALID_ARGUMENT = -1;
  public static final int NOT_INITIALIZED = -2;
  public static final int LICENSE = -3;
  public static final int UNSUPPORTED = -4;
  public static final int IO = -5;
  public static final int NO_SLOT = -6;
  public static final int PROCESS = -7;
  public static final int OUT_OF_MEMORY = -8;
}

Value	Constant	Meaning
`0`	`SUCCESS`	OK
`-1`	`INVALID_ARGUMENT`	Null, empty, or out-of-range argument
`-2`	`NOT_INITIALIZED`	Engine not initialized, or already released
`-3`	`LICENSE`	License / auth failure
`-4`	`UNSUPPORTED`	Feature or format not supported
`-5`	`IO`	File or resource I/O failure
`-6`	`NO_SLOT`	Resource slot exhausted
`-7`	`PROCESS`	Frame processing failed
`-8`	`OUT_OF_MEMORY`	Allocation failed

-1 is invalid argument. -2 is not initialized.

ImageFrame

Wraps native pixel buffers. Always call release() when finished.

Create

public static ImageFrame createWithFile(String filePath);
public static ImageFrame createWithRGBA(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithBGRA(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithRGB(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithBGR(ByteBuffer data, int width, int height, int stride);
public static ImageFrame createWithI420(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer uBuffer, int strideU,
    ByteBuffer vBuffer, int strideV);
public static ImageFrame createWithNV12(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer uvBuffer, int strideUV);
public static ImageFrame createWithNV21(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer vuBuffer, int strideVU);
public static ImageFrame createWithAndroid420(int width, int height,
    ByteBuffer yBuffer, int strideY, ByteBuffer uBuffer, int strideU,
    ByteBuffer vBuffer, int strideV, int pixelStrideUV);
public static ImageFrame createWithTexture(int texture, int width, int height, int stride);
public static ImageFrame createWithBitmap(Bitmap bitmap);

Factory	Notes
`createWithFile`	PNG / JPG path
`createWithAndroid420`	Camera2 `YUV_420_888`
`createWithTexture`	`GL_TEXTURE_2D` in the current GL context; `stride` is usually `width * 4`
`createWithBitmap`	Copies `ARGB_8888` pixels into an RGBA frame

Returns null on failure (invalid bitmap, native alloc failed, …). Prefer ByteBuffer.allocateDirect for packed / planar factories.

Fields and operations

public FrameType type = FrameType.VIDEO;

public int rotate(Rotation rotation);
public int mirror(String mode);
public void setMirror(String mode);
public ImageFrame convert(Format format);
public int toFile(String path, int quality);
public int toFile(String path);
public Bitmap toBitmap();
public boolean isValid();
public void release();

Method	Description
`rotate`	Rotate in place. Returns `0` on success
`mirror`	Immediate mirror. `mode`: `"horizontal"`, `"vertical"`, `"both"` (case-insensitive)
`setMirror`	Flag applied inside `processImage` (avoids an extra convert). `""` / `null` clears
`convert`	Returns a new frame in `format`; caller must `release()` it
`toFile`	Write PNG/JPG. Quality `1`–`100`; overload defaults to `90`
`toBitmap`	`ARGB_8888` `Bitmap` (converts to RGBA first if needed)

Accessors

public int getWidth();
public int getHeight();
public int getStride();
public int getSize();
public ByteBuffer getData();
public Format getFormat();
public int getTexture();

public ByteBuffer getDataY();
public ByteBuffer getDataU();
public ByteBuffer getDataV();
public ByteBuffer getDataUV();
public int getStrideY();
public int getStrideU();
public int getStrideV();
public int getStrideUV();

getTexture() returns 0 if the frame is not bound to a GPU texture.

Format

public enum Format {
  I420(0),     // YUV 4:2:0 planar Y, U, V
  NV12(1),     // YUV 4:2:0 Y + UV
  NV21(2),     // YUV 4:2:0 Y + VU (Android camera default)
  BGRA(3),
  RGBA(4),
  BGR(5),
  RGB(6),
  Texture(7);
}

Rotation

Clockwise.

public enum Rotation {
  ROTATION_0(0),
  ROTATION_90(1),
  ROTATION_180(2),
  ROTATION_270(3);
}

Introduction

Android

iOS

macOS

Windows

Linux

Web

Flutter

Logging

LogLevel

LogConfig

Engine

EngineConfig

BeautyEffectEngine

FrameType

Beauty

Reshape

Makeup

Virtual background and chroma key

Filters and stickers

Stats and callbacks

EngineStats

EngineCallbacks

EngineEventCode

FaceDetectionResult

ErrorCode

ImageFrame

Create

Fields and operations

Accessors

Format

Rotation

​Logging

​LogLevel

​LogConfig

​Engine

​EngineConfig

​BeautyEffectEngine

​FrameType

​Beauty

​Reshape

​Makeup

​Virtual background and chroma key

​Filters and stickers

​Stats and callbacks

​EngineStats

​EngineCallbacks

​EngineEventCode

​FaceDetectionResult

​ErrorCode

​ImageFrame

​Create

​Fields and operations

​Accessors

​Format

​Rotation

Logging

LogLevel

LogConfig

Engine

EngineConfig

BeautyEffectEngine

FrameType

Beauty

Reshape

Makeup

Virtual background and chroma key

Filters and stickers

Stats and callbacks

EngineStats

EngineCallbacks

EngineEventCode

FaceDetectionResult

ErrorCode

ImageFrame

Create

Fields and operations

Accessors

Format

Rotation