实现美颜

本文档对应 SDK 2.0.0。授权见授权与许可。美妆 / 美型枚举见参数枚举。

添加 SDK 依赖

方法 A：CocoaPods（推荐）

target 'YourTargetName' do
  pod 'Facebetter', '2.0.0'
end

pod install

Xcode 15+ 编译错误使用 Xcode 15 或更高版本时，编译可能出现 Sandbox: rsync.samba deny(1)。这是 User Script Sandboxing 导致的。解决方法：

在 Xcode 中选择 Project。
打开 Build Settings。
搜索 ENABLE_USER_SCRIPT_SANDBOXING。
将值从 Yes 改为 No。

方法 B：手动集成 Framework

前往下载获取 SDK，将 Facebetter.framework 拷入工程，并按嵌入动态库将 Embed 设为 Embed & Sign。

权限

使用在线 appId / appKey 的沙盒 Mac 应用必须允许出站网络：

相机（可选）：在 Info.plist 中添加 NSCameraUsageDescription。

导入头文件

#import <Facebetter/FBBeautyEffectEngine.h>

AppKit 类型（NSImage）需要 #import <AppKit/AppKit.h>（macOS 上通常已由引擎头文件或前缀头引入）。

日志配置

默认关闭日志。必须在创建引擎之前调用 setLogConfig:。

FBLogConfig *logConfig = [[FBLogConfig alloc] init];
logConfig.level = FBLogLevel_Info;
logConfig.consoleEnabled = YES;
logConfig.fileEnabled = YES;
logConfig.fileName = @"/path/in/container/facebetter.log";
[FBBeautyEffectEngine setLogConfig:logConfig];

创建引擎

绑定 macOS Bundle ID，然后传入 licenseToken 或 appId + appKey。见获取 AppID 和 AppKey 与授权与许可。 优先级： licenseToken 非空（许可证 token、{token} JSON 或 .lic 内容）时本地校验；否则用 appId + appKey 请求 /facebetter/v2/auth。

FBEngineConfig *engineConfig = [[FBEngineConfig alloc] init];
engineConfig.appId = @"your appId";
engineConfig.appKey = @"your appKey";
// engineConfig.licenseToken = @"your license token";
engineConfig.externalContext = NO;

self.beautyEffectEngine = [FBBeautyEffectEngine createEngineWithConfig:engineConfig];
if (self.beautyEffectEngine == nil) {
  NSLog(@"创建美颜引擎失败");
  return;
}

createEngineWithConfig: 返回的是实例，不是单例。没有 Bundle ID 的命令行工具请在控制台绑定进程名。

美肤

强度一般为 [0.0, 1.0]。风格枚举见参数枚举。

[self.beautyEffectEngine setSmoothing:0.5f];
[self.beautyEffectEngine setSmoothingStyle:FBSmoothingStyle_Natural];
[self.beautyEffectEngine setWhitening:0.3f];
[self.beautyEffectEngine setWhiteningStyle:FBWhiteningStyle_ColdWhite];
[self.beautyEffectEngine setSharpening:0.2f];
[self.beautyEffectEngine setRosiness:0.15f];
[self.beautyEffectEngine setBeautySkinOnly:YES];

美型

setReshape:intensity: 范围为 [-1.0, 1.0]。0 关闭。参数：FBReshape_FaceThin … FBReshape_BrowThickness（0–25）。含义见参数枚举。

[self.beautyEffectEngine setReshape:FBReshape_FaceThin intensity:0.4f];
[self.beautyEffectEngine setReshape:FBReshape_EyeSize intensity:0.2f];

美体

setBodyReshape:intensity: 范围为 [0.0, 1.0]。0 关闭。先用 addResourcePack: 登记 resource_body.fbd。参数：FBBodyReshape_BodySlim … FBBodyReshape_TorsoLong（0–8）。见参数枚举与可选资源包。

NSString *bodyPack = [[NSBundle mainBundle] pathForResource:@"resource_body" ofType:@"fbd"];
[self.beautyEffectEngine addResourcePack:bodyPack];
[self.beautyEffectEngine setBodyReshape:FBBodyReshape_WaistSlim intensity:0.4f];
[self.beautyEffectEngine setBodyReshape:FBBodyReshape_LegStretch intensity:0.3f];
[self.beautyEffectEngine setBodyReshape:FBBodyReshape_TorsoLong intensity:0.3f];

美妆

强度、形状、色号分开设置。完整预设见参数枚举。

[self.beautyEffectEngine setLipstick:0.5f];
[self.beautyEffectEngine setLipstickColor:FBLipstickColor_Rouge];

[self.beautyEffectEngine setBlush:0.4f];
[self.beautyEffectEngine setBlushStyle:FBBlushStyle_SunKissed];
[self.beautyEffectEngine setBlushColor:FBBlushColor_CoralPink];

[self.beautyEffectEngine setContour:0.35f];
[self.beautyEffectEngine setContourStyle:FBContourStyle_Natural];

[self.beautyEffectEngine setEyeShadow:0.4f];
[self.beautyEffectEngine setEyeShadowStyle:FBEyeShadowStyle_Soft];
[self.beautyEffectEngine setEyeShadowColor:FBEyeShadowColor_Plum];

[self.beautyEffectEngine setEyeLiner:0.4f];
[self.beautyEffectEngine setEyeLinerStyle:FBEyeLinerStyle_Classic];
[self.beautyEffectEngine setEyeLinerColor:FBEyeLinerColor_Coffee];

[self.beautyEffectEngine setEyebrow:0.4f];
[self.beautyEffectEngine setEyebrowStyle:FBEyebrowStyle_Natural];
[self.beautyEffectEngine setEyebrowColor:FBEyebrowColor_DarkBrown];

[self.beautyEffectEngine setEyelash:0.4f];
[self.beautyEffectEngine setEyelashStyle:FBEyelashStyle_Classic];
[self.beautyEffectEngine setEyelashColor:FBEyelashColor_Black];

[self.beautyEffectEngine setPupil:0.4f];
[self.beautyEffectEngine setPupilColor:FBPupilColor_Hazel];

虚拟背景

[self.beautyEffectEngine setVirtualBackgroundBlur:0.6f];
[self.beautyEffectEngine setVirtualBackground:imagePath];
[self.beautyEffectEngine setVirtualBackgroundWithData:pngOrJpegData];
[self.beautyEffectEngine clearVirtualBackground];

色键只替换遮罩。填充仍是模糊或替换图。

[self.beautyEffectEngine setChromaKey:FBChromaKeyColor_Green];
[self.beautyEffectEngine setChromaKeySimilarity:0.4f];
[self.beautyEffectEngine setChromaKeySmoothness:0.3f];
[self.beautyEffectEngine setChromaKeyDesaturation:0.2f];
[self.beautyEffectEngine clearChromaKey];

滤镜与贴纸

传入 .fbd 文件路径或内存字节。没有按 ID 注册的接口。

NSString *filterPath = [[NSBundle mainBundle] pathForResource:@"chuxin" ofType:@"fbd"];
[self.beautyEffectEngine setFilter:filterPath];
[self.beautyEffectEngine setFilterIntensity:0.8f];
[self.beautyEffectEngine clearFilter];
[self.beautyEffectEngine setFilterWithData:filterData];

NSString *stickerPath = [[NSBundle mainBundle] pathForResource:@"cherry" ofType:@"fbd"];
[self.beautyEffectEngine setSticker:stickerPath];
[self.beautyEffectEngine clearSticker];
[self.beautyEffectEngine setStickerWithData:stickerData];

3D 贴纸需要可选包 resource_3d.fbd（不在 framework 内）。见可选资源包：

NSString *packPath = [[NSBundle mainBundle] pathForResource:@"resource_3d" ofType:@"fbd"];
[self.beautyEffectEngine addResourcePack:packPath];
NSString *sticker3dPath = [[NSBundle mainBundle] pathForResource:@"oculos" ofType:@"fbd"];
[self.beautyEffectEngine set3DSticker:sticker3dPath];
[self.beautyEffectEngine clear3DSticker];

回调与统计

FBEngineCallbacks *callbacks = [[FBEngineCallbacks alloc] init];
callbacks.onEngineEvent = ^(FBEngineEventCode code, NSString * _Nullable message) {
  // 0 授权成功，1 授权失败，100 初始化完成，101 初始化失败
  NSLog(@"engine event %ld %@", (long)code, message);
};
callbacks.onFaceLandmarks = ^(NSArray<FBFaceDetectionResult *> * _Nullable results) {
  NSLog(@"faces %lu", (unsigned long)results.count);
};
[self.beautyEffectEngine setCallbacks:callbacks];

FBEngineStats *stats = [self.beautyEffectEngine getStats];
NSLog(@"fps=%.1f avg=%.2fms session=%.1fs",
      stats.fps, stats.avgProcessTimeMs, stats.sessionTimeS);

处理图像

FBImageFrame 支持 I420、NV12、NV21、RGB、RGBA、BGR、BGRA、文件、纹理和 NSImage。

FBImageFrame *fromFile = [FBImageFrame createWithFile:@"/path/photo.png"];
FBImageFrame *fromRGBA = [FBImageFrame createWithRGBA:data width:width height:height stride:stride];
FBImageFrame *fromNSImage = [FBImageFrame createWithNSImage:nsImage];

先设 type，再调用 processImage:（没有额外的模式参数）。输出格式与输入一致。

input.type = FBFrameTypeVideo;  // 或 FBFrameTypeImage
FBImageFrame *output = [self.beautyEffectEngine processImage:input];

FBFrameTypeVideo 用于实时流，FBFrameTypeImage 用于静图和 NSImage。

[input rotate:FBImageRotation90];
[input setMirror:@"horizontal"];
FBImageFrame *rgba = [output convert:FBImageFormatRGBA];
const uint8_t *bytes = [rgba data];
[output toFile:@"/path/out.jpg" quality:90];

YUV 平面：dataY、dataU、dataV、dataUV 及对应 stride。

外部纹理

在 OpenGL 线程创建引擎，并设置 externalContext = YES。输入输出纹理必须共享该上下文。macOS 为桌面 OpenGL 3.2 Core（NSOpenGLContext / CGL），不是 OpenGL ES。

FBEngineConfig *config = [[FBEngineConfig alloc] init];
config.appId = @"your appId";
config.appKey = @"your appKey";
config.externalContext = YES;
self.engine = [FBBeautyEffectEngine createEngineWithConfig:config];

FBImageFrame *inputFrame = [FBImageFrame createWithTexture:textureId
                                                     width:width
                                                    height:height
                                                    stride:width * 4];
inputFrame.type = FBFrameTypeVideo;
FBImageFrame *outputFrame = [self.engine processImage:inputFrame];
GLuint outputTexture = [outputFrame texture];

接入 TRTC / 声网 / LiveKit：见第三方对接。

生命周期

用 NSViewController 的 strong 引用持有引擎。视图消失或窗口最小化时停止采集。会话结束时将引擎置 nil。

- (void)dealloc {
  self.beautyEffectEngine = nil;
}

产品介绍

Android

iOS

macOS

Windows

Linux

Web

添加 SDK 依赖

方法 A：CocoaPods（推荐）

方法 B：手动集成 Framework

权限

导入头文件

日志配置

创建引擎

美肤

美型

美体

美妆

虚拟背景

滤镜与贴纸

回调与统计

处理图像

外部纹理

生命周期

相关文档

​添加 SDK 依赖

​方法 A：CocoaPods（推荐）

​方法 B：手动集成 Framework

​权限

​导入头文件

​日志配置

​创建引擎

​美肤

​美型

​美体

​美妆

​虚拟背景

​滤镜与贴纸

​回调与统计

​处理图像

​外部纹理

​生命周期

​相关文档

添加 SDK 依赖

方法 A：CocoaPods（推荐）

方法 B：手动集成 Framework

权限

导入头文件

日志配置

创建引擎

美肤

美型

美体

美妆

虚拟背景

滤镜与贴纸

回调与统计

处理图像

外部纹理

生命周期

相关文档