常见问题

​

集成

​

创建引擎返回 nil

• 确认已设置 licenseToken 或 appId + appKey。两者都有时以 token 为准。
• 绑定 Mac Bundle ID（命令行工具：进程名）。
• 在线授权需要 App Sandbox 的 Outgoing Connections，并能访问 /facebetter/v2/auth。
• 在 createEngineWithConfig: 之前打开日志，关注事件 1 / 101。
• CocoaPods：pod 'Facebetter', '2.0.0'。打开 .xcworkspace。

​

编译找不到头文件或类

• 导入 #import <Facebetter/FBBeautyEffectEngine.h>。
• 手动 .framework：Embed & Sign。
• Xcode 15+ CocoaPods 沙盒：将 ENABLE_USER_SCRIPT_SANDBOXING 设为 No。

​

运行时链接 / dyld 错误

• 架构：x86_64 与 arm64。
• 部署目标 macOS 10.15+。

​

授权

​

licenseToken 与 appId / appKey

​

事件 1 或 101

​

美颜

​

效果太弱或太强

• 美肤 / 美妆 / 滤镜：[0.0, 1.0]。
• 美型：通过 setReshape:intensity: 使用 [-1.0, 1.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];
[engine setVirtualBackground:imagePath];
[engine setVirtualBackgroundWithData:imageData];
[engine clearVirtualBackground];
[engine setChromaKey:FBChromaKeyColor_Green];
[engine clearChromaKey];

​

处理

​

processImage: 返回 nil

​

帧类型

​

格式转换

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

​

NSImage

FBImageFrame *frame = [FBImageFrame createWithNSImage:nsImage];
frame.type = FBFrameTypeImage;
FBImageFrame *out = [engine processImage:frame];

​

相机

1. AVCaptureVideoDataOutput → CVPixelBuffer。
2. createWithNV12:... 或 createWithBGRA:...。
3. type = FBFrameTypeVideo，可选 setMirror:@"horizontal"。
4. 在 AppKit / OpenGL 视图中显示 [output data] 或 [output texture]。

​

性能

• 实时用 FBFrameTypeVideo；关注 getStats。
• 一个引擎、串行队列。
• 窗口最小化时暂停采集。

​

日志

[FBBeautyEffectEngine setLogConfig:logConfig];  // 在 createEngineWithConfig: 之前

​

版本

• macOS 10.15+，x86_64 + arm64。
• CocoaPods：pod 'Facebetter', '2.0.0'。
• Universal Binary：确认 xcframework 含两个切片（lipo -info）。

​

沙盒与 App Store

• 在线授权需要出站网络。
• 相机需要 NSCameraUsageDescription。
• 用户选择的文件使用 security-scoped bookmark。
• 不要使用私有 API；实时视频不要在主线程跑引擎。