FAQ

​

Integration

​

Engine creation returns nil

• Confirm licenseToken or appId + appKey is set. Token wins if both are present.
• Bind the app Bundle ID in the dashboard.
• Online auth needs network to /facebetter/v2/auth.
• Enable logs before createEngineWithConfig: and watch events 1 (license fail) and 101 (init fail).
• CocoaPods: pod 'Facebetter', '2.0.0'. Open the .xcworkspace, not the .xcodeproj.

​

Missing headers or classes

• Import #import <Facebetter/FBBeautyEffectEngine.h>.
• For a manual .framework, set Embed & Sign.
• Clean Build Folder and rebuild.
• If CocoaPods scripts fail on Xcode 15+, set ENABLE_USER_SCRIPT_SANDBOXING to No.

​

Runtime link / dyld errors

• Architecture must be arm64.
• Deployment target iOS 12.0+.
• Confirm Facebetter.framework is in Embed Frameworks.

​

Auth

​

licenseToken vs appId / appKey

​

Event 1 or 101

​

Beauty

​

Effect is too weak or too strong

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

​

Makeup / reshape enum values

​

Filters, stickers, virtual background

​

Filter or sticker does nothing

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

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

​

Virtual background

[engine setVirtualBackgroundBlur:0.6f];           // 0 clears blur
[engine setVirtualBackground:imagePath];          // png/jpg
[engine setVirtualBackgroundWithData:imageData];
[engine clearVirtualBackground];

[engine setChromaKey:FBChromaKeyColor_Green];
[engine setChromaKeySimilarity:0.4f];
[engine clearChromaKey];  // back to portrait segmentation; fill stays

​

Processing

​

processImage: returns nil

• Engine is nil or init failed (-2 / event 101).
• Invalid frame (zero size, unsupported format).
• externalContext = YES but the current thread has no GL context.
• Treat as process failure (FBErrorCode_Process).

​

Frame type

​

Format conversion

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

​

Camera preview

1. Read CVPixelBuffer from AVCaptureVideoDataOutput.
2. Build FBImageFrame with createWithNV12:... or createWithBGRA:....
3. Set type = FBFrameTypeVideo, optional setMirror:@"horizontal".
4. processImage: then display [output data] or [output texture].

​

Performance and memory

• Use FBFrameTypeVideo for live; lower resolution if getStats.avgProcessTimeMs is high.
• One engine, serial queue; do not process on the main thread.
• Release frames with ARC (frame = nil). Reuse capture buffers.
• Avoid setFilter: / setSticker: every frame.

​

Logging

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

​

Version

• iOS 12.0+, arm64.
• CocoaPods: pod 'Facebetter', '2.0.0'.
• After upgrade: pod install, Clean Build Folder, re-test auth and processImage:.

​

Threading

• Default engine: serial queue for all processImage: and setters that touch GL resources.
• externalContext = YES: create + process on the GL thread.
• Update UI on the main queue only.