This page matches SDK 2.0.0. Makeup / reshape enums: Parameter enums.
Choose the right frame type
SetFBImageFrame.type before processImage:. There is no process-mode argument on the engine.
FBFrameTypeVideo(1): camera preview, live, calls — lower latency.FBFrameTypeImage(0): still photos /NSImage— higher quality.
Large stills (preview vs export)
Do not feed full-resolution pixels intoprocessImage: on every slider change, and do not throw the original away after scaling.
When the photo opens, keep the full NSImage and build one preview frame (long edge about 1280–1440, createWithNSImage:). Slider changes process the preview (FBFrameTypeImage). Export processes a full-resolution frame with the same setters. Output size matches the input. Camera preview stays capture resolution + FBFrameTypeVideo.
Parameter ranges
- Skin / makeup / filter intensity:
[0.0, 1.0].0turns that effect off. - Reshape (
setReshape:intensity:):[-1.0, 1.0].0is off. Positive and negative are opposite directions.
One engine, one serial queue
createEngineWithConfig: returns an instance, not a process-wide singleton. Keep one engine per session and call it from a serial queue (or the GL thread when externalContext = YES).
Memory
- Prefer ARC. Drop
FBImageFramereferences when a frame is done. - Reuse camera pixel buffers (NV12 / BGRA) instead of converting every frame to RGBA.
- Call
setFilter:/setSticker:once; textures load on the nextprocessImage:. - Use
clearFilter,clearSticker,clearVirtualBackground, andclearChromaKeyinstead of creating a second engine.
External OpenGL
When the AppKit view already owns a desktop OpenGL 3.2 Core context (NSOpenGLContext / CGL):
- Set
config.externalContext = YES. - Create the engine on that GL thread (reuse the caller’s current context; do not create a second one).
- Wrap a
GL_TEXTURE_2DwithcreateWithTexture:width:height:stride:. - Read the output with
[output texture].
CVPixelBuffer on the same engine.
Monitor with getStats
avgProcessTimeMs under ~33 ms at 30 fps. Desktop GPUs can run higher resolutions; still drop effects if the UI hitchs.
Lifecycle (AppKit)
Hold the engine on theNSViewController (or a session object). Stop capture in viewWillDisappear. Pause when the window miniaturizes. Nil the engine in dealloc / applicationWillTerminate.
__weak in FBEngineCallbacks blocks.
macOS capture and display
- Build frames with
createWithNV12:...,createWithBGRA:..., orcreateWithNSImage:. - Front camera / user-facing preview:
setMirror:@"horizontal". - Retina: process in pixel size (
backingScaleFactor), not point size. - Camera:
NSCameraUsageDescription. Sandboxed apps need Outgoing Connections for online auth. - User-picked
.fbd/ background images: security-scoped URLs.
Testing
- Bind the Mac app Bundle ID (or process name for CLI tools).
- Use a real
appId/appKeyorlicenseToken. - Cover
FBFrameTypeImage+createWithNSImage:andFBFrameTypeVideo. - Assert setter codes are
FBErrorCode_Success. Universal Binary: test Intel and Apple Silicon.

