API Reference

SDK 2.0.0. Namespace facebetter. Same public C++ API as Windows. Headers: facebetter/*.h. Enums: Parameter enums. Auth: Auth & License.

Linux notes

Ship libfacebetter.so. Set LD_LIBRARY_PATH, rpath, or ldconfig.
Build the SDK with ./scripts/build_linux.sh (output build/linux/release) or CMake.
resource_path must be the resource.fbd file.
SetRenderView is not available.
external_context = true uses the calling thread’s current GL context (GLFW / EGL / OSMesa).

target_include_directories(app PRIVATE /path/to/sdk/include)
target_link_libraries(app PRIVATE /path/to/sdk/lib/libfacebetter.so GL)

Logging

enum class LogLevel { Trace = 0, Debug, Info, Warn, Error, Critical };

struct LogConfig {
  bool console_enabled = false;
  bool file_enabled = false;
  LogLevel level = LogLevel::Info;
  std::string file_name = "";
};

static int BeautyEffectEngine::SetLogConfig(const LogConfig& config);

Call SetLogConfig before Create.

Engine

`EngineConfig`

Field	Description
`app_id` / `app_key`	Native online v2 auth
`resource_path`	Path to `resource.fbd` (file, not directory)
`license_token`	token / `{token}` JSON / `.lic` — non-empty takes priority
`external_context`	`false`: SDK-managed OpenGL; `true`: caller context

struct EngineConfig {
  std::string app_id;
  std::string app_key;
  std::string resource_path;
  std::string license_token;
  bool external_context = false;
};

static std::shared_ptr<BeautyEffectEngine> BeautyEffectEngine::Create(
    const EngineConfig& config);

Skin

int SetSmoothing(float intensity);          // [0, 1]
int SetSmoothingStyle(SmoothingStyle style);
int SetWhitening(float intensity);
int SetWhiteningStyle(WhiteningStyle style);
int SetSharpening(float intensity);
int SetRosiness(float intensity);
int SetBeautySkinOnly(bool enabled);

Reshape

int SetReshape(Reshape param, float intensity);  // [-1, 1]

Full Reshape list: Parameter enums.

Body reshape

int SetBodyReshape(BodyReshape param, float intensity);  // [0, 1]

Full BodyReshape list: Parameter enums. Requires resource_body.fbd. See Optional resource packs.

Makeup

int SetLipstick(float);        int SetLipstickColor(LipstickColor);
int SetBlush(float);           int SetBlushStyle(BlushStyle); int SetBlushColor(BlushColor);
int SetContour(float);         int SetContourStyle(ContourStyle);
int SetEyeShadow(float);       int SetEyeShadowStyle(...); int SetEyeShadowColor(...);
int SetEyeLiner(float);        int SetEyeLinerStyle(...);  int SetEyeLinerColor(...);
int SetEyebrow(float);         int SetEyebrowStyle(...);   int SetEyebrowColor(...);
int SetEyelash(float);         int SetEyelashStyle(...);   int SetEyelashColor(...);
int SetPupil(float);           int SetPupilColor(PupilColor);

Lipstick is Color only; pupil is Color only; contour is Style only. Values: Parameter enums.

Chroma key and virtual background

int SetChromaKey(ChromaKeyColor color);  // Green, Blue, Red
int ClearChromaKey();
int SetChromaKeySimilarity(float);
int SetChromaKeySmoothness(float);
int SetChromaKeyDesaturation(float);

int SetVirtualBackgroundBlur(float level);  // [0, 1]; 0 clears fill
int SetVirtualBackground(const std::string& image_path);
int SetVirtualBackground(const std::vector<uint8_t>& image_data);
int ClearVirtualBackground();

Filter and sticker

Path or encoded .fbd bytes. No register / ID API. Takes effect on the next ProcessImage.

int SetFilter(const std::string& fbd_file_path);
int SetFilter(const std::vector<uint8_t>& fbd_data);
int ClearFilter();
int SetFilterIntensity(float intensity);

int SetSticker(const std::string& fbd_file_path);
int SetSticker(const std::vector<uint8_t>& fbd_data);
int ClearSticker();
int AddResourcePack(const std::string& fbd_file_path);
int AddResourcePack(const std::vector<uint8_t>& fbd_data);
int Set3DSticker(const std::string& resource);
int Set3DSticker(const std::vector<uint8_t>& fbd_data);
int Clear3DSticker();

Load optional packs first (resource_3d.fbd before 3D stickers, resource_body.fbd before body reshape). See Optional resource packs.

Stats, callbacks, process

EngineStats GetStats() const;
int SetCallbacks(const EngineCallbacks& callbacks);
const std::shared_ptr<ImageFrame> ProcessImage(
    const std::shared_ptr<ImageFrame> image_frame);

Set frame->type to FrameType::Image or FrameType::Video.

struct EngineStats {
  double fps = 0.0;
  double avg_process_time_ms = 0.0;
  double session_time_s = 0.0;
};

Events

Code	Meaning
`0`	License success
`1`	License failed
`100`	Init complete
`101`	Init failed

struct EngineCallbacks {
  std::function<void(const std::vector<FaceDetectionResult>&)> on_face_landmarks;
  std::function<void(int code, const std::string& message)> on_engine_event;
};

Image

enum class Format { I420, NV12, NV21, BGRA, RGBA, BGR, RGB, Texture };
enum class Rotation { Rotation_0, Rotation_90, Rotation_180, Rotation_270 };
enum class FrameType { Image = 0, Video = 1 };

Factories: CreateWithFile, Create, CreateWithRGBA/BGRA/RGB/BGR, CreateWithI420/NV12/NV21, CreateWithTexture. Ops: Rotate, Mirror("horizontal"|"vertical"|"both"), SetMirror, Convert, ToFile. Accessors: Width/Height/Stride/Size/GetFormat/Data, YUV planes, Texture(), Buffer(). Field: FrameType type.

struct FaceDetectionResult {
  Rect rect;
  std::vector<Point2d> key_points;  // 111
  std::vector<float> visibility;
  int face_id = -1;
  float score = 0.0f;
  float pitch, roll, yaw;
};

Error codes

Code	Meaning
`0`	OK
`-1`	Invalid argument
`-2`	Not initialized
`-3`	License
`-4`	Unsupported
`-5`	I/O
`-6`	No slot
`-7`	Process
`-8`	Out of memory

Serialize ProcessImage on one thread. Pixel Data() pointers are read-only.

Introduction

Android

iOS

macOS

Windows

Linux

Web

Linux notes

Logging

Engine

`EngineConfig`

Skin

Reshape

Body reshape

Makeup

Chroma key and virtual background

Filter and sticker

Stats, callbacks, process

Events

Image

Error codes

​Linux notes

​Logging

​Engine

​EngineConfig

​Skin

​Reshape

​Body reshape

​Makeup

​Chroma key and virtual background

​Filter and sticker

​Stats, callbacks, process

​Events

​Image

​Error codes

Linux notes

Logging

Engine

`EngineConfig`

Skin

Reshape

Body reshape

Makeup

Chroma key and virtual background

Filter and sticker

Stats, callbacks, process

Events

Image

Error codes