实现美颜

添加 SDK 依赖

方法 A：Maven 在线集成（推荐）

在项目根目录的 build.gradle 或 settings.gradle 中配置仓库：

repositories {
    mavenCentral()
}

模块 build.gradle：

dependencies {
    implementation 'net.pixpark:facebetter:2.0.0'
}

Version Catalog（gradle/libs.versions.toml）：

[versions]
facebetter = "2.0.0"

[libraries]
facebetter = { group = "net.pixpark", name = "facebetter", version.ref = "facebetter" }

dependencies {
    implementation libs.facebetter
}

方法 B：本地 AAR

前往下载获取 SDK，将 facebetter.aar 放到 libs/，然后：

dependencies {
    implementation files('libs/facebetter.aar')
    implementation libs.appcompat
    implementation libs.material
}

权限配置

AndroidManifest.xml：

<!-- 在线鉴权需要（appId + appKey → /facebetter/v2/auth） -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- 可选：仅在把 SDK 日志写到应用目录之外时需要 -->
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

<!-- 可选：相机预览 / 实时美颜 -->
<uses-permission android:name="android.permission.CAMERA" />

权限	何时需要
网络	在线 `appId` + `appKey` 鉴权。离线 `licenseToken` 校验不依赖网络
存储	仅当 `LogConfig.fileEnabled` 写到应用私有目录之外
相机	仅当采集实时画面

API 23+ 需在运行时申请 CAMERA。

导入类

import net.pixpark.facebetter.BeautyEffectEngine;
import net.pixpark.facebetter.BeautyParams.*;
import net.pixpark.facebetter.EngineCallbacks;
import net.pixpark.facebetter.EngineEventCode;
import net.pixpark.facebetter.EngineStats;
import net.pixpark.facebetter.ErrorCode;
import net.pixpark.facebetter.ImageFrame;

日志配置

默认关闭日志。必须在 new BeautyEffectEngine(...) 之前开启。

请在创建引擎之前调用 setLogConfig，否则看不到初始化日志。

BeautyEffectEngine.LogConfig logConfig = new BeautyEffectEngine.LogConfig();
logConfig.consoleEnabled = true;
logConfig.fileEnabled = true;
logConfig.level = BeautyEffectEngine.LogLevel.INFO;
logConfig.fileName = getFilesDir() + "/facebetter.log";
BeautyEffectEngine.setLogConfig(logConfig);

创建引擎

凭证获取见订阅服务。鉴权细节见授权与许可。 licenseToken 非空时使用该 token（许可证 token / {token} JSON / 离线 .lic）。否则用 appId + appKey 请求 /facebetter/v2/auth。

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId";
config.appKey = "your appKey";
// config.licenseToken = "/* 许可证 token、{token} JSON，或 .lic 全文 */";
// config.externalContext = false;

BeautyEffectEngine engine;
try {
    engine = new BeautyEffectEngine(this, config);
} catch (IllegalArgumentException e) {
    Log.e(TAG, "EngineConfig 无效", e);
    return;
}

构造函数不会返回 null；配置无效会抛异常。异步初始化结果通过 EngineEventCode.INITIALIZATION_COMPLETE / INITIALIZATION_FAILED 回调通知。

美颜

强度 [0.0, 1.0]。0 表示关闭。成功返回 ErrorCode.SUCCESS（0）。

engine.setSmoothing(0.5f);
engine.setSmoothingStyle(SmoothingStyle.NATURAL);
engine.setWhitening(0.3f);
engine.setWhiteningStyle(WhiteningStyle.COLD_WHITE);
engine.setSharpening(0.2f);
engine.setRosiness(0.15f);
engine.setBeautySkinOnly(true);

开启 setBeautySkinOnly(true) 后，磨皮 / 美白 / 锐化 / 红润只作用于检测到的皮肤，衣服和背景不受影响。

风格枚举见参数枚举。

整形

范围 [-1.0, 1.0]。0 为关闭。

engine.setReshape(Reshape.FACE_THIN, 0.4f);
engine.setReshape(Reshape.EYE_SIZE, 0.3f);
engine.setReshape(Reshape.CHIN, -0.2f);

全部 26 个参数（FACE_THIN … BROW_THICKNESS）及正负方向见参数枚举。

美体

范围 [0.0, 1.0]。0 关闭。先用 addResourcePack 登记 resource_body.fbd（不在 AAR 内）。见参数枚举与可选资源包。

engine.addResourcePack(loadAssetBytes("resource_body.fbd"));
engine.setBodyReshape(BodyReshape.WAIST_SLIM, 0.4f);
engine.setBodyReshape(BodyReshape.LEG_STRETCH, 0.3f);
engine.setBodyReshape(BodyReshape.TORSO_LONG, 0.3f);

美妆

先设强度，再设风格和/或颜色。

engine.setLipstick(0.6f);
engine.setLipstickColor(LipstickColor.ROUGE);

engine.setBlush(0.4f);
engine.setBlushStyle(BlushStyle.SUN_KISSED);
engine.setBlushColor(BlushColor.CORAL_PINK);

engine.setContour(0.35f);
engine.setContourStyle(ContourStyle.NATURAL);

engine.setEyeShadow(0.45f);
engine.setEyeShadowStyle(EyeShadowStyle.SOFT);
engine.setEyeShadowColor(EyeShadowColor.PLUM);

engine.setEyeLiner(0.4f);
engine.setEyeLinerStyle(EyeLinerStyle.CLASSIC);

engine.setEyebrow(0.35f);
engine.setEyebrowStyle(EyebrowStyle.NATURAL);

engine.setEyelash(0.4f);
engine.setEyelashStyle(EyelashStyle.CLASSIC);

engine.setPupil(0.3f);
engine.setPupilColor(PupilColor.HAZEL);

完整预设置见参数枚举。

虚拟背景与色度键

模糊（0 会清除）、静态图，或色度键遮罩 + 填充。

engine.setVirtualBackgroundBlur(0.6f);

int ret = engine.setVirtualBackground("/sdcard/bg.jpg");
if (ret != ErrorCode.SUCCESS) {
    Log.e(TAG, "setVirtualBackground 失败: " + ret);
}

byte[] png = loadAssetBytes("backgrounds/office.png");
engine.setVirtualBackground(png);

engine.setChromaKey(ChromaKeyColor.GREEN);
engine.setChromaKeySimilarity(0.4f);
engine.setChromaKeySmoothness(0.3f);
engine.setChromaKeyDesaturation(0.2f);

engine.clearChromaKey();
engine.clearVirtualBackground();

clearChromaKey() 会恢复肖像分割，不会去掉当前的模糊/图片填充。

滤镜与贴纸

从文件路径或 assets 加载 .fbd。无需注册步骤。

engine.setFilter(getFilesDir() + "/filters/vivid.fbd");
engine.setFilterIntensity(0.8f);

byte[] lut = loadAssetBytes("filters/vivid.fbd");
engine.setFilter(lut);

engine.clearFilter();

engine.setSticker(getFilesDir() + "/stickers/cherry.fbd");
byte[] sticker = loadAssetBytes("stickers/cherry.fbd");
engine.setSticker(sticker);
engine.clearSticker();

3D 贴纸需要可选包 resource_3d.fbd（不在 AAR 内）。见可选资源包。从应用 assets 登记后再设置 3D 贴纸 .fbd：

engine.addResourcePack(loadAssetBytes("resource_3d.fbd"));
engine.set3DSticker(loadAssetBytes("stickers/3d/oculos.fbd"));
engine.clear3DSticker();

滤镜 / 贴纸在下一帧处理后生效。

private byte[] loadAssetBytes(String path) throws IOException {
    try (InputStream in = getAssets().open(path);
         ByteArrayOutputStream out = new ByteArrayOutputStream()) {
        byte[] buf = new byte[4096];
        int n;
        while ((n = in.read(buf)) >= 0) {
            out.write(buf, 0, n);
        }
        return out.toByteArray();
    }
}

回调与统计

EngineCallbacks callbacks = new EngineCallbacks();
callbacks.onEngineEvent = (code, message) -> {
    switch (code) {
        case EngineEventCode.LICENSE_VALIDATION_SUCCESS:
            Log.d(TAG, "授权成功");
            break;
        case EngineEventCode.LICENSE_VALIDATION_FAILED:
            Log.e(TAG, "授权失败: " + message);
            break;
        case EngineEventCode.INITIALIZATION_COMPLETE:
            Log.d(TAG, "引擎就绪");
            break;
        case EngineEventCode.INITIALIZATION_FAILED:
            Log.e(TAG, "初始化失败: " + message);
            break;
        default:
            break;
    }
};
callbacks.onFaceLandmarks = results -> {
    Log.d(TAG, "人脸数=" + results.size());
};
engine.setCallbacks(callbacks);

EngineStats stats = engine.getStats();
Log.d(TAG, "fps=" + stats.fps + " avgMs=" + stats.avgProcessTimeMs
    + " sessionS=" + stats.sessionTimeS);

处理图像

你创建的每一帧以及 processImage 的输出都必须调用 ImageFrame.release()，否则会泄漏原生内存。

将 ImageFrame.type 设为 FrameType.IMAGE（静图）或 FrameType.VIDEO（相机 / 直播）。processImage 只接收帧，没有额外的模式参数。

ByteBuffer data = ByteBuffer.allocateDirect(width * height * 4);
ImageFrame input = ImageFrame.createWithRGBA(data, width, height, width * 4);
input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);

从文件或 Bitmap：

ImageFrame input = ImageFrame.createWithFile("/sdcard/photo.jpg");
input.type = ImageFrame.FrameType.IMAGE;
ImageFrame output = engine.processImage(input);
Bitmap preview = output.toBitmap();

相机传感器有旋转时，处理前先旋转 / 镜像：

input.rotate(ImageFrame.Rotation.ROTATION_90);
input.mirror("horizontal");

引擎会保持输入输出像素格式一致（NV21 进则 NV21 出，RGBA 进则 RGBA 出）。

用 getData() / 平面访问器读像素，或先转换：

ImageFrame rgba = output.convert(ImageFrame.Format.RGBA);
ByteBuffer pixels = rgba.getData();
int w = rgba.getWidth();
int h = rgba.getHeight();
int stride = rgba.getStride();
rgba.release();

ImageFrame i420 = output.convert(ImageFrame.Format.I420);
ByteBuffer y = i420.getDataY();
ByteBuffer u = i420.getDataU();
ByteBuffer v = i420.getDataV();
i420.release();

相机管线

Camera2 YUV_420_888 → 引擎 → 显示的典型流程：

Image.Plane[] planes = image.getPlanes();
ImageFrame input = ImageFrame.createWithAndroid420(
    image.getWidth(), image.getHeight(),
    planes[0].getBuffer(), planes[0].getRowStride(),
    planes[1].getBuffer(), planes[1].getRowStride(),
    planes[2].getBuffer(), planes[2].getRowStride(),
    planes[1].getPixelStride());
if (input == null) {
    image.close();
    return;
}
if (isFrontCamera) {
    input.rotate(ImageFrame.Rotation.ROTATION_270);
    input.mirror("horizontal");
} else {
    input.rotate(ImageFrame.Rotation.ROTATION_90);
}
input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);
image.close();

外部纹理（OpenGL ES）

必须在 GL 线程上以 externalContext = true 创建引擎。输入、输出纹理须属于同一上下文。

适合应用已用 OpenGL ES 渲染、希望避免 CPU 往返拷贝的场景。

BeautyEffectEngine.EngineConfig config = new BeautyEffectEngine.EngineConfig();
config.appId = "your appId";
config.appKey = "your appKey";
config.externalContext = true;
BeautyEffectEngine engine = new BeautyEffectEngine(context, config);
engine.setSmoothing(0.5f);

int stride = srcWidth * 4;
ImageFrame input = ImageFrame.createWithTexture(srcTextureId, srcWidth, srcHeight, stride);
if (input == null) {
    return;
}
input.type = ImageFrame.FrameType.VIDEO;
ImageFrame output = engine.processImage(input);
if (output == null) {
    input.release();
    return;
}
int dstTextureId = output.getTexture();
int dstWidth = output.getWidth();
int dstHeight = output.getHeight();
output.release();
input.release();

输入 GL_TEXTURE_2D 建议的采样参数：

GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_LINEAR);
GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR);
GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_S, GLES20.GL_CLAMP_TO_EDGE);
GLES20.glTexParameteri(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_WRAP_T, GLES20.GL_CLAMP_TO_EDGE);

注意：

输入纹理为 GL_TEXTURE_2D，一般为 RGBA；stride 通常为 width * 4
在第一次 GL 回调里惰性创建引擎，确保上下文已绑定
输出纹理由 SDK 持有，不要 glDeleteTextures；释放对应的 ImageFrame 即可
GL 上下文丢失后，先 release() 再在新上下文中重建引擎
实时 GL 管线使用 FrameType.VIDEO
接入 TRTC / 声网 / LiveKit 等推流或会议 SDK：见第三方对接

生命周期

在 onDestroy / onDetach 中调用 engine.release()。不释放会泄漏 GPU 与原生内存。

@Override
protected void onDestroy() {
    super.onDestroy();
    if (mBeautyEngine != null) {
        mBeautyEngine.release();
        mBeautyEngine = null;
    }
}

if (input != null) {
    input.release();
}
if (output != null) {
    output.release();
}

产品介绍

Android

iOS

macOS

Windows

Linux

Web

添加 SDK 依赖

方法 A：Maven 在线集成（推荐）

方法 B：本地 AAR

权限配置

导入类

日志配置

创建引擎

美颜

整形

美体

美妆

虚拟背景与色度键

滤镜与贴纸

回调与统计

处理图像

相机管线

外部纹理（OpenGL ES）

生命周期

相关文档

​添加 SDK 依赖

​方法 A：Maven 在线集成（推荐）

​方法 B：本地 AAR

​权限配置

​导入类

​日志配置

​创建引擎

​美颜

​整形

​美体

​美妆

​虚拟背景与色度键

​滤镜与贴纸

​回调与统计

​处理图像

​相机管线

​外部纹理（OpenGL ES）

​生命周期

​相关文档

添加 SDK 依赖

方法 A：Maven 在线集成（推荐）

方法 B：本地 AAR

权限配置

导入类

日志配置

创建引擎

美颜

整形

美体

美妆

虚拟背景与色度键

滤镜与贴纸

回调与统计

处理图像

相机管线

外部纹理（OpenGL ES）

生命周期

相关文档