FAQ

​

Integration

​

Engine creation returns nil

• Confirm licenseToken or appId + appKey is set. Token wins if both are present.
• Bind the Mac Bundle ID (CLI tools: process name).
• Online auth needs Outgoing Connections in the App Sandbox and a path to /facebetter/v2/auth.
• Enable logs before createEngineWithConfig: and watch events 1 / 101.
• CocoaPods: pod 'Facebetter', '2.0.0'. Open the .xcworkspace.

​

Missing headers or classes

• Import #import <Facebetter/FBBeautyEffectEngine.h>.
• Manual .framework: Embed & Sign.
• Xcode 15+ CocoaPods sandbox: set ENABLE_USER_SCRIPT_SANDBOXING to No.

​

Runtime link / dyld errors

• Architectures: x86_64 and arm64.
• Deployment target macOS 10.15+.

​

Auth

​

licenseToken vs appId / appKey

​

Event 1 or 101

​

Beauty

​

Effect is too weak or too strong

• Skin / makeup / filter: [0.0, 1.0].
• Reshape: [-1.0, 1.0] via setReshape:intensity:.
• Body reshape: [0.0, 1.0] via setBodyReshape:intensity:. Register resource_body.fbd first.
• Intensity 0 disables that effect.
• Skin-only: setBeautySkinOnly:.

​

Filters, stickers, virtual background

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

​

Processing

​

processImage: returns nil

​

Frame type

​

Format conversion

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

​

Camera

1. AVCaptureVideoDataOutput → CVPixelBuffer.
2. createWithNV12:... or createWithBGRA:....
3. type = FBFrameTypeVideo, optional setMirror:@"horizontal".
4. Display [output data] or [output texture] in an AppKit / OpenGL view.

​

Performance

• FBFrameTypeVideo for live; watch getStats.
• One engine, serial queue.
• Pause capture when the window is miniaturized.

​

Logging

[FBBeautyEffectEngine setLogConfig:logConfig];  // before createEngineWithConfig:

​

Version

• macOS 10.15+, x86_64 + arm64.
• CocoaPods: pod 'Facebetter', '2.0.0'.
• Universal Binary: confirm the xcframework contains both slices (lipo -info).

​

Sandbox and App Store

• Outgoing network for online auth.
• NSCameraUsageDescription for camera.
• Security-scoped bookmarks for user-selected files.
• Do not use private APIs; keep the engine off the main thread for live video.