Quick Start

This page matches SDK 2.0.0. Linux and Windows share the same C++ API in the facebetter namespace (facebetter/*.h).

This guide builds the Facebetter C++ desktop demo on Linux. The demo uses GLFW + Dear ImGui + OpenGL 3: live preview on the left, beauty controls on the right.

Requirements

Tool	Version
OS (prebuilt SDK zip)	Officially Ubuntu 22.04+ (glibc ≥ 2.35; CI builds on Ubuntu 22.04). Other distros are not guaranteed.
GCC or Clang	C++17 (GCC 7+ / Clang 5+)
CMake	3.16+
Ninja	`apt install ninja-build` / `dnf install ninja-build`
OpenGL	`libgl1-mesa-dev` (Ubuntu/Debian) or `mesa-libGL-devel` (Fedora/RHEL)
X11 / Wayland	GLFW dependencies (see below)

Ubuntu / Debian

sudo apt update
sudo apt install -y build-essential cmake ninja-build \
    libgl1-mesa-dev libglu1-mesa-dev \
    libx11-dev libxrandr-dev libxinerama-dev \
    libxcursor-dev libxi-dev

Fedora / RHEL

sudo dnf install -y gcc-c++ cmake ninja-build \
    mesa-libGL-devel mesa-libGLU-devel \
    libX11-devel libXrandr-devel libXinerama-devel \
    libXcursor-devel libXi-devel

Step 1: Clone the repository

git clone https://github.com/pixpark/facebetter-sdk.git
cd facebetter-sdk

Step 2: Place the SDK files

Put the Linux SDK under demo/cpp/sdk/:

demo/cpp/sdk/
├── include/
│   └── facebetter/
│       ├── beauty_effect_engine.h
│       ├── beauty_params.h
│       ├── image_frame.h
│       └── type_defines.h
├── lib/
│   └── libfacebetter.so    ← shared library
└── resource/
    ├── resource.fbd        ← models and assets (required)
    ├── resource_3d.fbd     ← optional; 3D stickers. Place next to `resource.fbd` or call `AddResourcePack`
    └── resource_body.fbd   ← optional; body reshape. Place next to `resource.fbd` or call `AddResourcePack`

On desktop, EngineConfig::resource_path must point to the resource.fbd file, not a directory. Example: demo/cpp/sdk/resource/resource.fbd.

SDK packages are on the Download page and in the Dashboard.

To build the SDK from source instead of a prebuilt package:

./scripts/build_linux.sh

Output installs under build/linux/release. You can copy include/, lib/libfacebetter.so, and resource.fbd into demo/cpp/sdk/ as above.

Step 3: Configure license

Set app_id / app_key (online v2 auth) or license_token before you run. If license_token is non-empty, it takes priority (license token string, {token} JSON, or offline .lic contents). Details: Auth & License.

Step 4: Build the demo

cd demo/cpp
cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release
cmake --build build

CMake typically copies resource/resource.fbd (and demo.png if present) into build/resource/.

Step 5: Prepare a preview image (optional)

demo/cpp/demo.png

Step 6: Run

cd demo/cpp/build

# Option A: runtime library path
LD_LIBRARY_PATH=../sdk/lib ./facebetter_demo

# Option B: copy the .so next to the binary
cp ../sdk/lib/libfacebetter.so .
./facebetter_demo

The window shows a live preview and a control panel (skin, 26 face-reshape params, 7 body-reshape params, makeup, filter, sticker, virtual background). Click Reset All to zero intensities.

Troubleshooting

Q: libfacebetter.so: cannot open shared object file
A: Use LD_LIBRARY_PATH=../sdk/lib ./facebetter_demo, copy the .so next to the binary, or add the path with ldconfig. Q: Engine create returns nullptr / license failed
A: Point resource_path at resource.fbd, and set license_token or valid app_id + app_key. See Auth & License. Q: CMake cannot find OpenGL
A: Install libgl1-mesa-dev (Ubuntu) or mesa-libGL-devel (Fedora), then re-run CMake. Q: GLFW: X11: Display variable not set
A: Run inside a graphical session, or set DISPLAY (X11) / WAYLAND_DISPLAY (Wayland).

Introduction

Android

iOS

macOS

Windows

Linux

Web

Requirements

Ubuntu / Debian

Fedora / RHEL

Step 1: Clone the repository

Step 2: Place the SDK files

Step 3: Configure license

Step 4: Build the demo

Step 5: Prepare a preview image (optional)

Step 6: Run

Troubleshooting

Next steps

Implement beauty

API reference

​Requirements

​Ubuntu / Debian

​Fedora / RHEL

​Step 1: Clone the repository

​Step 2: Place the SDK files

​Step 3: Configure license

​Step 4: Build the demo

​Step 5: Prepare a preview image (optional)

​Step 6: Run

​Troubleshooting

​Next steps

Implement beauty

API reference

Requirements

Ubuntu / Debian

Fedora / RHEL

Step 1: Clone the repository

Step 2: Place the SDK files

Step 3: Configure license

Step 4: Build the demo

Step 5: Prepare a preview image (optional)

Step 6: Run

Troubleshooting

Next steps