实现美颜

本文档对应 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。

权限

仅在使用相机采集时，于 Info.plist 添加：

<key>NSCameraUsageDescription</key>
<string>需要相机权限进行美颜拍照</string>

导入头文件

#import <Facebetter/FBBeautyEffectEngine.h>

日志配置

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

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

创建引擎

绑定 iOS 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;  // 仅当由你持有 GL 上下文时设 YES

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

createEngineWithConfig: 返回的是实例，不是单例。

美肤

强度一般为 [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];

美妆

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

[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];

虚拟背景

默认遮罩为人像分割。模糊强度 [0.0, 1.0]，0 清除模糊。图片路径必须是非空 png/jpg。

[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 文件路径或内存字节。

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

NSData *filterData = [NSData dataWithContentsOfFile:filterPath];
[self.beautyEffectEngine setFilterWithData:filterData];

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

回调与统计

FBEngineCallbacks *callbacks = [[FBEngineCallbacks alloc] init];
__weak typeof(self) weakSelf = self;
callbacks.onEngineEvent = ^(FBEngineEventCode code, NSString * _Nullable message) {
  // 0 授权成功，1 授权失败，100 初始化完成，101 初始化失败
  NSLog(@"engine event %ld %@", (long)code, message);
};
callbacks.onFaceLandmarks = ^(NSArray<FBFaceDetectionResult *> * _Nullable results) {
  for (FBFaceDetectionResult *face in results) {
    NSLog(@"face %d keypoints %lu", face.faceId, (unsigned long)face.keyPoints.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、文件、纹理和 UIImage。

FBImageFrame *fromFile = [FBImageFrame createWithFile:@"/path/photo.png"];
FBImageFrame *fromRGBA = [FBImageFrame createWithRGBA:data width:width height:height stride:stride];
FBImageFrame *fromUIImage = [FBImageFrame createWithUIImage:uiImage];

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

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

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

旋转 / 镜像 / 转换 / 保存：

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

YUV 平面：dataY、dataU、dataV、dataUV 以及 strideY / strideU / strideV / strideUV。

外部纹理

在 OpenGL ES 线程创建引擎，并设置 externalContext = YES。输入输出纹理必须共享该上下文。

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];

建议纹理参数：GL_LINEAR、GL_CLAMP_TO_EDGE。引擎不会删除你的输入纹理。输出纹理由 SDK 持有。

生命周期

会话期间用 strong 引用持有引擎。ViewController 销毁时置 nil。离开页面时停止采集，从而停止调用 processImage:。

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

产品介绍

Android

iOS

macOS

Windows

Linux

Web

Flutter

添加 SDK 依赖

方法 A：CocoaPods（推荐）

方法 B：手动集成 Framework

权限

导入头文件

日志配置

创建引擎

美肤

仅皮肤区域

美型

美妆

虚拟背景

色键

滤镜与贴纸

回调与统计

处理图像

外部纹理

生命周期

相关文档

​添加 SDK 依赖

​方法 A：CocoaPods（推荐）

​方法 B：手动集成 Framework

​权限

​导入头文件

​日志配置

​创建引擎

​美肤

​仅皮肤区域

​美型

​美妆

​虚拟背景

​色键

​滤镜与贴纸

​回调与统计

​处理图像

​外部纹理

​生命周期

​相关文档

添加 SDK 依赖

方法 A：CocoaPods（推荐）

方法 B：手动集成 Framework

权限

导入头文件

日志配置

创建引擎

美肤

仅皮肤区域

美型

美妆

虚拟背景

色键

滤镜与贴纸

回调与统计

处理图像

外部纹理

生命周期

相关文档