Web API Reference

Error Classes

FacebetterError

Facebetter error class, extends Error.

Properties:

• message: Error message
• code: Error code (default -1)
• name: Error name (fixed as 'FacebetterError')

class FacebetterError extends Error {
    constructor(message, code = -1)
}

Example:

try {
    // Some operation
} catch (error) {
    if (error instanceof FacebetterError) {
        console.error('Facebetter error:', error.message);
        console.error('Error code:', error.code);
    }
}

Configuration Classes

EngineConfig

Engine configuration class, used to initialize the beauty engine.

Constructor:

new EngineConfig(config)

Parameters:

• config.appId (string, optional): Application ID (required if licenseJson is not provided)
• config.appKey (string, optional): Application key (required if licenseJson is not provided)
• config.licenseJson (string, optional): License JSON string (if provided, appId and appKey are not needed)

Methods:

• isValid(): Validate if configuration is valid
• toString(): Return string representation of configuration

Example:

const config = new EngineConfig({
    appId: 'your-app-id',
    appKey: 'your-app-key'
});

// Or use licenseJson
const config = new EngineConfig({
    licenseJson: '{"license": "..."}'
});

Enumeration Types

BeautyType

Beauty type enumeration.

BeautyType = {
    Basic: 0,          // Basic beauty
    Reshape: 1,        // Face reshaping
    Makeup: 2,         // Makeup effects
    VirtualBackground: 3    // Virtual background
};

BasicParam

Basic beauty parameter enumeration.

BasicParam = {
    Smoothing: 0,   // Skin smoothing
    Sharpening: 1,  // Sharpening
    Whitening: 2,   // Whitening
    Rosiness: 3     // Rosiness
};

ReshapeParam

Face reshape parameter enumeration.

ReshapeParam = {
    FaceThin: 0,      // Face thinning
    FaceVShape: 1,    // V-face
    FaceNarrow: 2,    // Narrow face
    FaceShort: 3,     // Short face
    Cheekbone: 4,     // Cheekbone
    Jawbone: 5,       // Jawbone
    Chin: 6,          // Chin
    NoseSlim: 7,      // Nose slimming
    EyeSize: 8,       // Eye enlargement
    EyeDistance: 9    // Eye distance
};

MakeupParam

Makeup parameter enumeration.

MakeupParam = {
    Lipstick: 0,  // Lipstick
    Blush: 1      // Blush
};

ProcessMode

Processing mode enumeration.

ProcessMode = {
    Image: 0,   // Image mode, suitable for single image processing
    Video: 1    // Video mode, suitable for video streams and live scenarios, better performance
};

BackgroundMode

Background mode enumeration.

BackgroundMode = {
    None: 0,   // No background processing
    Blur: 1,   // Blur background
    Image: 2   // Background image replacement
};

VirtualBackgroundOptions

Virtual background options class, used to set virtual background parameters.

Constructor:

new VirtualBackgroundOptions(options)

Parameters:

• options (Object, optional): Options object
  • mode (BackgroundMode, optional): Background mode, defaults to BackgroundMode.None
  • backgroundImage (ImageData|HTMLImageElement|HTMLCanvasElement, optional): Background image, required when mode is Image

Methods:

• isValid(): Validate if options are valid
  • Returns: boolean
  • When mode is Image, checks if backgroundImage exists

Example:

import { VirtualBackgroundOptions, BackgroundMode } from 'facebetter';

// Create blur background options
const blurOptions = new VirtualBackgroundOptions({
  mode: BackgroundMode.Blur
});

// Create image background options
const bgImage = new Image();
bgImage.src = 'background.jpg';
const imageOptions = new VirtualBackgroundOptions({
  mode: BackgroundMode.Image,
  backgroundImage: bgImage
});

// Validate options
if (imageOptions.isValid()) {
  engine.setVirtualBackground(imageOptions);
}

Engine Classes

BeautyEffectEngine

Main beauty effect engine class, provides entry point for beauty functionality.

Constructor:

new BeautyEffectEngine(config)

Parameters:

• config (EngineConfig): Engine configuration object

Instance Methods:

Initialization

• init(options): Initialize engine

  • Parameters:
    • options (Object, optional): Initialization options
      • timeout (number, optional): WASM module loading timeout in milliseconds, default 30000
      • authTimeout (number, optional): Online authentication timeout in milliseconds, default 10000
  • Returns: Promise<void>
  • Example:

    await engine.init();
    // Or specify timeout
    await engine.init({
      timeout: 60000,      // WASM loading timeout 60 seconds
      authTimeout: 15000   // Authentication timeout 15 seconds
    });

• setLogConfig(config): Set log configuration

  • Parameters:
    • config.consoleEnabled (boolean, optional): Enable console logging, default false
    • config.fileEnabled (boolean, optional): Enable file logging, default false (not supported in browser environment)
    • config.level (number, optional): Log level (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR), default 0
    • config.fileName (string, optional): Log file name, default empty string
  • Returns: Promise<void>
  • Note: Can be called before or after init(), but recommended to call before init()

Beauty Type Control

• setBeautyTypeEnabled(beautyType, enabled): Enable or disable beauty type

  • Parameters:
    • beautyType (BeautyType): Beauty type
    • enabled (boolean): Whether to enable
  • Returns: void
  • Example: engine.setBeautyTypeEnabled(BeautyType.Basic, true);

• isBeautyTypeEnabled(beautyType): Check if beauty type is enabled

  • Parameter: beautyType (BeautyType)
  • Returns: boolean
  • Example: const enabled = engine.isBeautyTypeEnabled(BeautyType.Basic);

• disableAllBeautyTypes(): Disable all beauty types

  • Returns: void
  • Example: engine.disableAllBeautyTypes();

Parameter Settings

• setBasicParam(param, value): Set basic beauty parameter

  • Parameters:
    • param (BasicParam): Parameter type
    • value (number): Parameter value, range [0.0, 1.0] (float)
  • Returns: void
  • Example: engine.setBasicParam(BasicParam.Whitening, 0.5);

• setReshapeParam(param, value): Set face reshape parameter

  • Parameters:
    • param (ReshapeParam): Parameter type
    • value (number): Parameter value, range [0.0, 1.0] (float)
  • Returns: void
  • Example: engine.setReshapeParam(ReshapeParam.FaceThin, 0.5);

• setMakeupParam(param, value): Set makeup parameter

  • Parameters:
    • param (MakeupParam): Parameter type
    • value (number): Parameter value, range [0.0, 1.0] (float)
  • Returns: void
  • Example: engine.setMakeupParam(MakeupParam.Lipstick, 0.5);

• setVirtualBackground(options): Set virtual background (unified API, consistent with other platforms)

  • Parameters:
    • options (VirtualBackgroundOptions|Object): Virtual background options
      • mode (BackgroundMode): Background mode (None, Blur, Image)
      • backgroundImage (ImageData|HTMLImageElement|HTMLCanvasElement, optional): Background image (required when mode is Image)
  • Returns: void
  • Example:

    import { VirtualBackgroundOptions, BackgroundMode } from 'facebetter';
    
    // Set blur background
    const blurOptions = new VirtualBackgroundOptions({
      mode: BackgroundMode.Blur
    });
    engine.setVirtualBackground(blurOptions);
    
    // Set image background
    const bgImage = new Image();
    bgImage.onload = () => {
      const imageOptions = new VirtualBackgroundOptions({
        mode: BackgroundMode.Image,
        backgroundImage: bgImage
      });
      engine.setVirtualBackground(imageOptions);
    };
    bgImage.src = 'background.jpg';
    
    // Simplified syntax
    engine.setVirtualBackground({
      mode: BackgroundMode.Blur
    });

Image Processing

• processImage(input, width, height, processMode): Process image
  • Parameters:
    • input (ImageData | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | Uint8ClampedArray): Input image
    • width (number, optional): Image width (required when input is Uint8ClampedArray)
    • height (number, optional): Image height (required when input is Uint8ClampedArray)
    • processMode (ProcessMode, optional): Processing mode, defaults to ProcessMode.Image
  • Returns: ImageData (synchronous return, not Promise)
  • Example:

    // Using ImageData
    const result = engine.processImage(
        imageData, 
        640, 
        480, 
        ProcessMode.Video
    );

Resource Management

• destroy(): Destroy engine and release resources
  • Returns: void
  • Note: Call when engine is no longer needed to free memory and WASM resources
  • Example: engine.destroy();

Utility Functions

loadWasmModule

Load WASM module (usually not needed to call directly, engine handles automatically).

import { loadWasmModule } from 'facebetter';
const module = await loadWasmModule();

Usage Examples

Complete Example

import { 
    BeautyEffectEngine, 
    EngineConfig, 
    BeautyType, 
    BasicParam,
    ProcessMode 
} from 'facebetter';

// Create configuration
const config = new EngineConfig({
    appId: 'your-app-id',
    appKey: 'your-app-key'
});

// Create engine
const engine = new BeautyEffectEngine(config);

// Set logging
await engine.setLogConfig({
    consoleEnabled: true,
    level: 1
});

// Initialize
await engine.init();

// Enable beauty types
engine.setBeautyTypeEnabled(BeautyType.Basic, true);
engine.setBeautyTypeEnabled(BeautyType.Reshape, true);

// Set parameters
engine.setBasicParam(BasicParam.Whitening, 0.5);
engine.setBasicParam(BasicParam.Smoothing, 0.5);

// Process image
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');
const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);

const result = engine.processImage(
    imageData, 
    canvas.width, 
    canvas.height, 
    ProcessMode.Video
);

// Draw result
ctx.putImageData(result, 0, 0);

// Release resources
engine.destroy();