API Reference

This page matches SDK 2.0.0. Makeup / reshape / style enums: Parameter enums. Auth: Auth & License.

Package: facebetter. Typical import:

import {
  BeautyEffectEngine,
  EngineConfig,
  FrameType,
  MirrorMode,
  Reshape,
} from 'facebetter';

EngineConfig

new EngineConfig({
  licenseToken,      // string — required. License token string, or `{token}` JSON
})

Web does not accept appId / appKey on this object. Web does not support offline .lic. isValid() is true when licenseToken is a non-empty string. Fetch the token from your server before init(). See Auth & License.

BeautyEffectEngine

const engine = new BeautyEffectEngine(config);
await engine.init({
  onProgress: ({ percent }) => {
    // 0–100 while runtime files download
  },
});

Lifecycle

Method	Description
`init(options?)`	Initialize the engine (auth and resources). `options.timeout` (default `120000`) is the init timeout in ms. `options.onProgress({ loaded, total, percent })` reports download progress of the runtime files.
`setLogConfig({ consoleEnabled, fileEnabled, level, fileName })`	Global log config. Call before `init()`. `level`: `0` TRACE … `5` CRITICAL. File logging is not supported in the browser. Returns `Promise<void>`.
`destroy()`	Release the engine and its resources.

engine.initialized is true after a successful init().

Skin

Method	Range
`setSmoothing(value)`	`[0, 1]`
`setSmoothingStyle(style)`	`SmoothingStyle`
`setWhitening(value)`	`[0, 1]`
`setWhiteningStyle(style)`	`WhiteningStyle`
`setSharpening(value)`	`[0, 1]`
`setRosiness(value)`	`[0, 1]`
`setBeautySkinOnly(enabled)`	`boolean`

Reshape

setReshape(param, value) — param is Reshape.*, value in [-1.0, 1.0]. See Parameter enums.

Body reshape

setBodyReshape(param, value) — param is BodyReshape.*, value in [0.0, 1.0]. Requires resource_body.fbd via addResourcePack first. See Parameter enums and Optional resource packs.

Makeup

Intensity [0, 1]. Style / color enums: Parameter enums.

Intensity	Style / color
`setLipstick`	`setLipstickColor`
`setBlush`	`setBlushStyle`, `setBlushColor`
`setContour`	`setContourStyle`
`setEyeShadow`	`setEyeShadowStyle`, `setEyeShadowColor`
`setEyeLiner`	`setEyeLinerStyle`, `setEyeLinerColor`
`setEyebrow`	`setEyebrowStyle`, `setEyebrowColor`
`setEyelash`	`setEyelashStyle`, `setEyelashColor`
`setPupil`	`setPupilColor`

Filter / sticker

Method	Description
`setFilter(path \| Uint8Array)`	Apply a LUT `.fbd` from URL or bytes
`clearFilter()`	Remove the current filter
`setFilterIntensity(intensity)`	`[0, 1]`
`setSticker(path \| Uint8Array)`	Apply a 2D sticker `.fbd`
`clearSticker()`	Remove the sticker
`addResourcePack(path \| Uint8Array)`	Register an extra capability pack (`resource_3d.fbd` before `set3DSticker`, or `resource_body.fbd` before `setBodyReshape`)
`set3DSticker(path \| Uint8Array)`	Apply a 3D sticker `.fbd`
`clear3DSticker()`	Remove the 3D sticker

Virtual background / chroma key

Method	Description
`setVirtualBackgroundBlur(level)`	Continuous blur `[0, 1]`. `0` clears it
`setVirtualBackground(path \| Uint8Array)`	png/jpg path or encoded bytes
`clearVirtualBackground()`	Turn off blur / image
`setChromaKey(color)`	`ChromaKeyColor.Green` / `Blue` / `Red`
`clearChromaKey()`	Back to portrait-segmentation mask
`setChromaKeySimilarity(value)`	`[0, 1]`
`setChromaKeySmoothness(value)`	`[0, 1]`
`setChromaKeyDesaturation(value)`	`[0, 1]`

Callbacks

engine.setCallbacks({
  onFaceLandmarks, // (faces) => void
  onEngineEvent,   // (code, message) => void
  maxFaces,        // optional, default 10
});

Processing

processImage(input, width, height, frameType = FrameType.Video, mirrorMode = MirrorMode.None) → ImageData

input: ImageData | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | Uint8ClampedArray
width / height required only for Uint8ClampedArray

processTexture(textureHandle, width, height, stride, frameType, mirrorMode) → number

Returns an output GL_TEXTURE_2D handle. Mirror is not applied on this path. Prefer processImage.

Stats

engine.getStats() → { fps, avgProcessTimeMs, sessionTimeS }

Enums (JS)

Values match native. Full makeup / reshape tables: Parameter enums.

FrameType = { Image: 0, Video: 1 }

MirrorMode = { None: 0, Horizontal: 1, Vertical: 2, Both: 3 }

EngineEventCode = {
  LicenseValidationSuccess: 0,
  LicenseValidationFailed: 1,
  InitializationComplete: 100,
  InitializationFailed: 101,
}

ChromaKeyColor = { Green: 0, Blue: 1, Red: 2 }

Reshape = { FaceThin: 0, FaceVShape: 1, /* … BrowThickness: 25 */ }

Also exported: SmoothingStyle, WhiteningStyle, LipstickColor, BlushStyle, BlushColor, ContourStyle, EyeShadowStyle, EyeShadowColor, EyeLinerStyle, EyeLinerColor, EyebrowStyle, EyebrowColor, EyelashStyle, EyelashColor, PupilColor.

FacebetterError

class FacebetterError extends Error {
  constructor(message, code = -1)
  // name === 'FacebetterError'
  // code: number or string
}

Numeric codes: 0, -1 … -8. See Error handling.

Introduction

Android

iOS

macOS

Windows

Linux

Web

EngineConfig

BeautyEffectEngine

Lifecycle

Skin

Reshape

Body reshape

Makeup

Filter / sticker

Virtual background / chroma key

Callbacks

Processing

Stats

Enums (JS)

FacebetterError

​EngineConfig

​BeautyEffectEngine

​Lifecycle

​Skin

​Reshape

​Body reshape

​Makeup

​Filter / sticker

​Virtual background / chroma key

​Callbacks

​Processing

​Stats

​Enums (JS)

​FacebetterError

EngineConfig

BeautyEffectEngine

Lifecycle

Skin

Reshape

Body reshape

Makeup

Filter / sticker

Virtual background / chroma key

Callbacks

Processing

Stats

Enums (JS)

FacebetterError