常见问题

​

集成

​

创建引擎返回 nil

• 确认已设置 licenseToken 或 appId + appKey。两者都有时以 token 为准。
• 在控制台绑定应用 Bundle ID。
• 在线授权需要能访问 /facebetter/v2/auth。
• 在 createEngineWithConfig: 之前打开日志，关注事件 1（授权失败）和 101（初始化失败）。
• CocoaPods：pod 'Facebetter', '2.0.0'。打开 .xcworkspace，不要打开 .xcodeproj。

​

编译找不到头文件或类

• 导入 #import <Facebetter/FBBeautyEffectEngine.h>。
• 手动集成 .framework 时设置为 Embed & Sign。
• Clean Build Folder 后重建。
• Xcode 15+ CocoaPods 脚本失败时，将 ENABLE_USER_SCRIPT_SANDBOXING 设为 No。

​

运行时链接 / dyld 错误

• 架构必须是 arm64。
• 部署目标 iOS 12.0+。
• 确认 Facebetter.framework 已加入 Embed Frameworks。

​

授权

​

licenseToken 与 appId / appKey

​

事件 1 或 101

​

美颜

​

效果太弱或太强

• 美肤 / 美妆 / 滤镜：[0.0, 1.0]。
• 美型：通过 setReshape:intensity: 使用 [-1.0, 1.0]（0 关闭）。
• 美体：通过 setBodyReshape:intensity: 使用 [0.0, 1.0]。先登记 resource_body.fbd。
• 强度为 0 即关闭该项。
• 仅皮肤区域：setBeautySkinOnly:。

​

滤镜、贴纸、虚拟背景

​

滤镜或贴纸没有效果

[engine setFilter:fbdPath];
[engine setFilterIntensity:0.8f];
[engine clearFilter];

[engine setSticker:fbdPath];
[engine clearSticker];

​

虚拟背景

[engine setVirtualBackgroundBlur:0.6f];           // 0 清除模糊
[engine setVirtualBackground:imagePath];          // png/jpg
[engine setVirtualBackgroundWithData:imageData];
[engine clearVirtualBackground];

[engine setChromaKey:FBChromaKeyColor_Green];
[engine setChromaKeySimilarity:0.4f];
[engine clearChromaKey];  // 回到人像分割；填充保留

​

处理

​

processImage: 返回 nil

• 引擎为 nil 或初始化失败（-2 / 事件 101）。
• 帧无效（尺寸为 0、格式不支持）。
• externalContext = YES 但当前线程没有 GL 上下文。
• 按处理失败（FBErrorCode_Process）处理。

​

帧类型

​

格式转换

FBImageFrame *rgba = [frame convert:FBImageFormatRGBA];
const uint8_t *data = [rgba data];

​

UIImage

FBImageFrame *frame = [FBImageFrame createWithUIImage:image];
frame.type = FBFrameTypeImage;
FBImageFrame *out = [engine processImage:frame];

​

相机预览

1. 从 AVCaptureVideoDataOutput 取 CVPixelBuffer。
2. 用 createWithNV12:... 或 createWithBGRA:... 创建 FBImageFrame。
3. 设置 type = FBFrameTypeVideo，可选 setMirror:@"horizontal"。
4. processImage: 后显示 [output data] 或 [output texture]。

​

性能与内存

• 实时用 FBFrameTypeVideo；若 getStats.avgProcessTimeMs 偏高则降分辨率。
• 一个引擎、串行队列；不要在主线程处理。
• 用 ARC 释放帧（frame = nil），复用采集 buffer。
• 避免每帧 setFilter: / setSticker:。

​

日志

FBLogConfig *logConfig = [[FBLogConfig alloc] init];
logConfig.consoleEnabled = YES;
logConfig.fileEnabled = YES;
logConfig.level = FBLogLevel_Debug;
logConfig.fileName = logPath;
[FBBeautyEffectEngine setLogConfig:logConfig];  // 在 createEngineWithConfig: 之前

​

版本

• iOS 12.0+，arm64。
• CocoaPods：pod 'Facebetter', '2.0.0'。
• 升级后执行 pod install、Clean Build Folder，再验证授权和 processImage:。

​

线程

• 默认引擎：所有 processImage: 以及触及 GL 资源的 setter 走串行队列。
• externalContext = YES：在 GL 线程创建并处理。
• 仅在主队列更新 UI。