Implement macOS Beauty

Integrate SDK

Download SDK

Go to the Download page to get the latest SDK, then extract it.

Add Framework

Copy the Facebetter.framework library from the SDK package to your project path.

Open Xcode and refer to this guide to add the Facebetter.framework dynamic library. Make sure the Embed property of the added dynamic library is set to Embed & Sign.

Permission Configuration

Ensure network permissions are enabled for appkey validation

Permission Descriptions:

• Network Permission: Required. SDK needs network connection to verify appId and appKey to ensure the app runs normally.

Import Header Files

#import <Facebetter/FBBeautyEffectEngine.h>

Log Configuration

Logging is disabled by default and can be enabled as needed. Both console logging and file logging switches are supported. Logging should be enabled before creating the beauty engine.

FBLogConfig* logConfig = [[FBLogConfig alloc] init];
// Log level
logConfig.level = FBLogLevel_Info;
// Console logging
logConfig.consoleEnabled = YES;
// File logging
logConfig.fileEnabled = YES;
logConfig.fileName = @"log path: xx/xx/facebetter.log";

Create Configuration Engine

Follow the instructions on this page to get your appid and appkey.

FBEngineConfig *engineConfig = [[FBEngineConfig alloc] init];
engineConfig.appId = @"your appId";     // Configure your appid
engineConfig.appKey = @"your appkey";   // Configure your appkey
self.beautyEffectEngine = [FBBeautyEffectEngine createEngineWithConfig:engineConfig];

Error Handling

After creating the engine, it's recommended to check if it was successful:

if (self.beautyEffectEngine == nil) {
    NSLog(@"Failed to create beauty engine");
    return;
}

Enable Effect Types

Beauty features can be enabled or disabled by type. Enable corresponding beauty types according to your subscription version. Each type also has corresponding parameters that can be adjusted.

// Supported by all subscription versions
[self.beautyEffectEngine setBeautyTypeEnabled:FBBeautyType_Basic enabled:TRUE];
// Supported by Pro, Pro+ versions
[self.beautyEffectEngine setBeautyTypeEnabled:FBBeautyType_Reshape enabled:TRUE];
// Supported by Pro, Pro+ versions
[self.beautyEffectEngine setBeautyTypeEnabled:FBBeautyType_Makeup enabled:TRUE];
// Only supported by Pro+ version
[self.beautyEffectEngine setBeautyTypeEnabled:FBBeautyType_VirtualBackground enabled:TRUE];

Check Operation Results

All API calls should check return values:

int ret = [self.beautyEffectEngine setBeautyTypeEnabled:FBBeautyType_Basic enabled:TRUE];
if (ret == 0) {
    NSLog(@"Successfully enabled basic beauty");
} else {
    NSLog(@"Failed to enable basic beauty, error code: %d", ret);
}

Adjust Beauty Parameters

Set Skin Beauty Parameters

Use the setBasicParam interface to set skin beauty parameters. Parameter range [0.0, 1.0].

[self.beautyEffectEngine setBasicParam:FBBasicParam_Smoothing floatValue:0.5f];

Supported skin beauty parameters:

typedef NS_ENUM(NSInteger, FBBasicParam) {
  FBBasicParam_Smoothing = 0,  // Smoothing
  FBBasicParam_Sharpening,     // Sharpening
  FBBasicParam_Whitening,      // Whitening
  FBBasicParam_Rosiness,       // Rosiness
};

Set Face Reshape Parameters

Use the setReshapeParam interface to set face reshape parameters. Parameter range [0.0, 1.0].

[self.beautyEffectEngine setReshapeParam:FBReshapeParam_FaceThin floatValue:0.5f];

Supported face reshape parameters:

typedef NS_ENUM(NSInteger, FBReshapeParam) {
  FBReshapeParam_FaceThin = 0,  // Face thinning
  FBReshapeParam_FaceVShape,    // V-shaped face
  FBReshapeParam_FaceNarrow,    // Narrow face
  FBReshapeParam_FaceShort,     // Short face
  FBReshapeParam_Cheekbone,     // Cheekbone
  FBReshapeParam_Jawbone,       // Jawbone
  FBReshapeParam_Chin,          // Chin
  FBReshapeParam_NoseSlim,      // Nose slimming
  FBReshapeParam_EyeSize,       // Eye enlargement
  FBReshapeParam_EyeDistance,   // Eye distance
};

Set Makeup Parameters

[self.beautyEffectEngine setMakeupParam:FBMakeupParam_Lipstick floatValue:0.5f];

Supported makeup parameters:

typedef NS_ENUM(NSInteger, FBMakeupParam) {
  FBMakeupParam_Lipstick = 0,  // Lipstick
  FBMakeupParam_Blush,         // Blush
};

Set Virtual Background

Enable virtual background through the setBeautyTypeEnabled interface:

[self.beautyEffectEngine setBeautyTypeEnabled:FBBeautyType_VirtualBackground enabled:TRUE];

Set virtual background through the setVirtualBackground interface:

// Set background mode
FBVirtualBackgroundOptions *options = [[FBVirtualBackgroundOptions alloc] initWithMode:FBBackgroundModeBlur];
[self.beautyEffectEngine setVirtualBackground:options];

// Set background image (need to set to Image mode first)
FBVirtualBackgroundOptions *imageOptions = [[FBVirtualBackgroundOptions alloc] initWithMode:FBBackgroundModeImage];
imageOptions.backgroundImage = backgroundImageFrame;  // FBImageFrame object
[self.beautyEffectEngine setVirtualBackground:imageOptions];

Process Images

Create Images

Image data is encapsulated through FBImageFrame, supporting formats: YUVI420, NV12, NV21, RGB, RGBA, BGR, BGRA.

Create FBImageFrame with RGBA

FBImageFrame *input_image = [FBImageFrame createWithRGBA:data width:width height:height stride:stride];

Create FBImageFrame with image file

FBImageFrame *input_image = [FBImageFrame createWithFile:@"xxx.png"];

Rotate Images

FBImageFrame has built-in image rotation methods that can be used as needed.

- (int)rotate:(FBImageRotation)rotation;

Rotation angles

typedef NS_ENUM(NSInteger, FBImageRotation) {
  FBImageRotation0,    // 0 degrees
  FBImageRotation90,   // Clockwise 90 degrees
  FBImageRotation180,  // Clockwise 180 degrees
  FBImageRotation270,  // Clockwise 270 degrees
};

Process Images

processMode includes Video and Image modes. Video mode is suitable for live streaming and video scenarios with higher efficiency. Image mode is suitable for image processing scenarios.

FBImageFrame *output_image = [self.beautyEffectEngine processImage:input_image processMode:FBProcessModeVideo];

Get Processed Image Data

FBImageFrame can get processed image data through FBImageBuffer, such as RGBA.

FBImageBuffer* buffer = [output_image toRGBA];
uint8_t* data = [buffer data];
int data_size = buffer.size;

int width = buffer.width;
int height = buffer.width;
int stride = buffer.stride;

Get I420 data

FBImageBuffer* buffer = [output_image toI420];
// Get continuous I420 memory data
uint8_t* data = [buffer data];
// Get I420 data length
int data_size = buffer.size;
// Get Y, U, V component data separately
uint8_t* dataY = [buffer dataY];
uint8_t* dataU = [buffer dataU];
uint8_t* dataV = [buffer dataV];

int strideY = buffer.strideY;
int strideU = buffer.strideU;
int strideV = buffer.strideV;

FBImageFrame can be converted to various formats through built-in toXXX methods: YUVI420, NV12, NV21, RGB, RGBA, BGR, BGRA. These methods can be used for format conversion.

Lifecycle Management

Release Resources

When ViewController is destroyed, be sure to release engine resources:

- (void)dealloc {
    if (self.beautyEffectEngine) {
        // Note: FBBeautyEffectEngine is a singleton, usually doesn't need manual release
        // But if there are custom cleanup logic, it can be handled here
        self.beautyEffectEngine = nil;
    }
}

Memory Management

• Release FBImageFrame and FBImageBuffer objects timely
• Avoid repeatedly creating large numbers of image objects in loops
• Recommend reusing FBImageFrame objects

// Release resources after use
if (inputImage) {
    inputImage = nil; // ARC will automatically release
}
if (outputImage) {
    outputImage = nil; // ARC will automatically release
}
if (buffer) {
    buffer = nil; // ARC will automatically release
}

Related Documentation

• Best Practices - Performance optimization and architecture design recommendations
• Common Issues - Common questions and troubleshooting
• API Reference - Complete API documentation