快速开始

本文对应 SDK 2.0.0。Linux 与 Windows 共用同一套 C++ API（facebetter 命名空间，头文件 facebetter/*.h）。

本文说明如何在 Linux 上构建 Facebetter C++ 桌面 Demo。Demo 使用 GLFW + Dear ImGui + OpenGL 3：左侧实时预览，右侧调节美颜参数。

环境要求

工具	版本
系统（官方预编译 zip）	官方支持 Ubuntu 22.04+（glibc ≥ 2.35；CI 在 Ubuntu 22.04 构建）。其它发行版未保证。
GCC 或 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）或 `mesa-libGL-devel`（Fedora/RHEL）
X11 / Wayland	GLFW 依赖（见下方）

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

第一步：克隆仓库

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

第二步：放置 SDK 文件

将 Linux SDK 放入 demo/cpp/sdk/：

demo/cpp/sdk/
├── include/
│   └── facebetter/
│       ├── beauty_effect_engine.h
│       ├── beauty_params.h
│       ├── image_frame.h
│       └── type_defines.h
├── lib/
│   └── libfacebetter.so    ← 动态库
└── resource/
    ├── resource.fbd        ← 模型与资源包（必需）
    ├── resource_3d.fbd     ← 可选；3D 贴纸。与 `resource.fbd` 同目录或调用 `AddResourcePack`
    └── resource_body.fbd   ← 可选；美体。与 `resource.fbd` 同目录或调用 `AddResourcePack`

桌面端 EngineConfig::resource_path 必须指向 resource.fbd 文件本身，不能填目录。例如：demo/cpp/sdk/resource/resource.fbd。

SDK 包见下载页或控制台。

若要从源码编译 SDK（而不是使用预编译包）：

./scripts/build_linux.sh

产物安装到 build/linux/release。可将 include/、lib/libfacebetter.so 和 resource.fbd 按上面的结构拷入 demo/cpp/sdk/。

第三步：配置授权

运行前设置 app_id / app_key（在线 v2），或设置 license_token。license_token 非空时优先（许可证 token、{token} JSON 或离线 .lic）。详见授权与许可。

第四步：构建 Demo

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

CMake 通常会把 resource/resource.fbd（以及存在的 demo.png）复制到 build/resource/。

第五步：准备预览图（可选）

demo/cpp/demo.png

第六步：运行

cd demo/cpp/build

# 方式 A：运行时库路径
LD_LIBRARY_PATH=../sdk/lib ./facebetter_demo

# 方式 B：把 .so 拷到可执行文件旁
cp ../sdk/lib/libfacebetter.so .
./facebetter_demo

窗口为实时预览 + 控制面板（皮肤、26 项美型、7 项美体、美妆、滤镜、贴纸、虚拟背景）。Reset All 可将强度归零。

常见问题

Q：libfacebetter.so: cannot open shared object file
A：使用 LD_LIBRARY_PATH=../sdk/lib ./facebetter_demo，或把 .so 拷到可执行文件旁，或用 ldconfig 加入路径。 Q：Create 返回空指针 / 授权失败
A：resource_path 必须指向 resource.fbd，并配置 license_token 或有效的 app_id + app_key。见授权与许可。 Q：CMake 找不到 OpenGL
A：安装 libgl1-mesa-dev（Ubuntu）或 mesa-libGL-devel（Fedora）后重新配置。 Q：GLFW: X11: Display variable not set
A：在图形会话中运行，或设置 DISPLAY（X11）/ WAYLAND_DISPLAY（Wayland）。

产品介绍

Android

iOS

macOS

Windows

Linux

Web

环境要求

Ubuntu / Debian

Fedora / RHEL

第一步：克隆仓库

第二步：放置 SDK 文件

第三步：配置授权

第四步：构建 Demo

第五步：准备预览图（可选）

第六步：运行

常见问题

下一步

实现美颜

API 参考

​环境要求

​Ubuntu / Debian

​Fedora / RHEL

​第一步：克隆仓库

​第二步：放置 SDK 文件

​第三步：配置授权

​第四步：构建 Demo

​第五步：准备预览图（可选）

​第六步：运行

​常见问题

​下一步

实现美颜

API 参考

环境要求

Ubuntu / Debian

Fedora / RHEL

第一步：克隆仓库

第二步：放置 SDK 文件

第三步：配置授权

第四步：构建 Demo

第五步：准备预览图（可选）

第六步：运行

常见问题

下一步