Best Practices

SDK 2.0.0. Enums: Parameter enums.

Point `resource_path` at `resource.fbd`

Desktop engines open the pack with fopen. Pass the file, not a folder:

cfg.resource_path = "C:/app/assets/resource.fbd";

Ship resource.fbd next to the app (or under an assets dir) and resolve an absolute path at startup.

One engine, serial `ProcessImage`

BeautyEffectEngine is created with Create and is not a singleton. Keep one instance for the session. ImageFrame and the engine are not thread-safe — serialize ProcessImage on a single worker (or the GL thread when external_context = true).

// good: one engine, one processing thread
std::shared_ptr<BeautyEffectEngine> engine = BeautyEffectEngine::Create(cfg);

Drop the shared_ptr when the camera session ends. Recreating the engine every frame is expensive (license + init).

`FrameType` on the frame

Set frame->type before ProcessImage.

Value	Use
`FrameType::Video` (default)	Camera, capture, live preview
`FrameType::Image`	Single photo / export

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 buffer and build one preview frame (long edge about 1280–1440). Slider changes process the preview (FrameType::Image). Export processes a full-resolution frame with the same setters. Output size matches the input. Camera preview stays capture resolution + FrameType::Video.

preview->type = FrameType::Image;
auto preview_out = engine->ProcessImage(preview);

full->type = FrameType::Image;
auto export_out = engine->ProcessImage(full);

Intensities

Start low for realtime. Reshape is [-1.0, 1.0]; other intensities are [0.0, 1.0].

engine->SetSmoothing(0.25f);
engine->SetWhitening(0.15f);
engine->SetReshape(Reshape::FaceThin, 0.15f);
engine->SetBeautySkinOnly(true);

Enable SetBeautySkinOnly(true) so smoothing / whitening stay on skin.

Filters and stickers

Pass .fbd paths or bytes. Changes take effect on the next ProcessImage. Avoid swapping filter/sticker every frame.

engine->SetFilter(filter_path);
engine->SetFilterIntensity(0.7f);

Monitor with `GetStats`

EngineStats s = engine->GetStats();
if (s.avg_process_time_ms > 33.0) {
    // drop resolution, lower intensities, or skip stickers
}

Aim for avg_process_time_ms under your frame budget (about 33 ms at 30 fps). Prefer 720p for preview; use FrameType::Image for still export.

OpenGL context

`external_context`	When
`false` (default)	SDK manages OpenGL
`true`	You already have a current GL context; call `ProcessImage` on that thread

Place facebetter.dll beside the .exe (or on PATH). Link facebetter.lib at build time.

Pause when idle

When the window is minimized or the camera stops, skip ProcessImage and optionally engine.reset() if the session is over. Do not process on the UI thread if it blocks input.

Auth

Prefer license_token for offline / locked-down networks. Otherwise app_id + app_key online v2. Do not hard-code production keys in public repos — load from config. See Auth & License.

Introduction

Android

iOS

macOS

Windows

Linux

Web

Point `resource_path` at `resource.fbd`

One engine, serial `ProcessImage`

`FrameType` on the frame

Large stills (preview vs export)

Intensities

Filters and stickers

Monitor with `GetStats`

OpenGL context

Pause when idle

Auth

​Point resource_path at resource.fbd

​One engine, serial ProcessImage

​FrameType on the frame

​Large stills (preview vs export)

​Intensities

​Filters and stickers

​Monitor with GetStats

​OpenGL context

​Pause when idle

​Auth

Point `resource_path` at `resource.fbd`

One engine, serial `ProcessImage`

`FrameType` on the frame

Large stills (preview vs export)

Intensities

Filters and stickers

Monitor with `GetStats`

OpenGL context

Pause when idle

Auth