Implement Beauty

SDK 2.0.0. Auth: Auth & License. Enum values: Parameter enums.

Install

npm install facebetter

import {
  BeautyEffectEngine,
  EngineConfig,
  FrameType,
  MirrorMode,
  Reshape,
  SmoothingStyle,
  WhiteningStyle,
  LipstickColor,
  ChromaKeyColor,
  EngineEventCode,
  FacebetterError,
} from 'facebetter';

Create the engine

EngineConfig on Web has only these fields. There is no appId / appKey on the config object.

Field	Purpose
`licenseToken`	License token string, or `{token}` JSON. Required. Fetch it before `init()`.

The SDK loads runtime files during init(). You do not host a site-root resource.fbd for the engine. Optional download progress: init({ onProgress }). The engine does not fetch tokens. Web does not support offline .lic.

const licenseToken = await fetch('/api/facebetter/auth', { method: 'POST' }).then((r) => r.text());
const engine = new BeautyEffectEngine(new EngineConfig({ licenseToken }));

await engine.setLogConfig({
  consoleEnabled: true,
  fileEnabled: false,
  level: 2, // TRACE=0 … CRITICAL=5
});

await engine.init();

Call setLogConfig before init() if you want to see load / auth logs. File logging is not supported in the browser (fileEnabled is ignored).

try {
  await engine.init();
} catch (error) {
  if (error instanceof FacebetterError) {
    console.error(error.code, error.message);
  }
  throw error;
}

Skin beauty

Intensity range [0.0, 1.0]. 0 turns the effect off.

engine.setSmoothing(0.8);
engine.setSmoothingStyle(SmoothingStyle.Natural);
engine.setWhitening(0.5);
engine.setWhiteningStyle(WhiteningStyle.ColdWhite);
engine.setSharpening(0.3);
engine.setRosiness(0.2);
engine.setBeautySkinOnly(true);

setBeautySkinOnly(true) limits smoothing / whitening / sharpening / rosiness to detected skin. Clothing and background stay unchanged.

Style enums: Parameter enums.

Face reshape

engine.setReshape(Reshape.FaceThin, 0.3);
engine.setReshape(Reshape.EyeSize, 0.2);

Range is [-1.0, 1.0]. 0 is off. Positive and negative are opposite directions (for example FaceThin: slim / fuller cheeks). Full list: Parameter enums.

Body reshape

const bodyPack = new Uint8Array(
  await (await fetch('/resource_body.fbd')).arrayBuffer()
);
engine.addResourcePack(bodyPack);
engine.setBodyReshape(BodyReshape.WaistSlim, 0.4);
engine.setBodyReshape(BodyReshape.LegStretch, 0.3);
engine.setBodyReshape(BodyReshape.TorsoLong, 0.3);

Range is [0.0, 1.0]. 0 is off. Fetch resource_body.fbd and call addResourcePack after init() first. Full list: Parameter enums. Packs: Optional resource packs.

Makeup

Intensity, shape, and color are separate setters. Intensity is [0.0, 1.0]. Presets: Parameter enums.

engine.setLipstick(0.4);
engine.setLipstickColor(LipstickColor.Rouge);

engine.setBlush(0.3);
engine.setBlushStyle(/* BlushStyle.SunKissed */);
engine.setBlushColor(/* BlushColor.CoralPink */);

engine.setContour(0.4);
engine.setContourStyle(/* ContourStyle.Natural */);

engine.setEyeShadow(0.35);
engine.setEyeShadowStyle(/* EyeShadowStyle.Soft */);
engine.setEyeShadowColor(/* EyeShadowColor.Plum */);

engine.setEyeLiner(0.3);
engine.setEyeLinerStyle(/* ... */);
engine.setEyeLinerColor(/* ... */);

engine.setEyebrow(0.3);
engine.setEyebrowStyle(/* ... */);
engine.setEyebrowColor(/* ... */);

engine.setEyelash(0.3);
engine.setEyelashStyle(/* ... */);
engine.setEyelashColor(/* ... */);

engine.setPupil(0.4);
engine.setPupilColor(/* PupilColor.Hazel */);

Filters and stickers

Pass a .fbd URL or in-memory Uint8Array directly to the setter.

engine.setFilter('/assets/filters/portrait/natural/natural.fbd');
engine.setFilterIntensity(0.8);
engine.clearFilter();

engine.setSticker('/stickers/face/fox.fbd');
engine.clearSticker();

3D stickers need the optional resource_3d.fbd pack (not in the Web SDK). See Optional resource packs. Fetch bytes and register them after init():

const pack = new Uint8Array(
  await (await fetch('/resource_3d.fbd')).arrayBuffer()
);
engine.addResourcePack(pack);
engine.set3DSticker('/stickers/3d/oculos.fbd');
engine.clear3DSticker();

const bytes = new Uint8Array(await (await fetch('/filters/chuxin.fbd')).arrayBuffer());
engine.setFilter(bytes);

Virtual background and chroma key

engine.setVirtualBackgroundBlur(0.6);          // [0, 1]; 0 clears blur
engine.setVirtualBackground('/background.jpg'); // path or Uint8Array (png/jpg)
engine.clearVirtualBackground();

engine.setChromaKey(ChromaKeyColor.Green);
engine.setChromaKeySimilarity(0.4);
engine.setChromaKeySmoothness(0.2);
engine.setChromaKeyDesaturation(0.3);
engine.clearChromaKey();

Chroma key only replaces the mask. Fill is still setVirtualBackgroundBlur or setVirtualBackground. Blur and image replacement are mutually exclusive.

Callbacks

engine.setCallbacks({
  onEngineEvent: (code, message) => {
    if (code === EngineEventCode.LicenseValidationSuccess) {
      console.log('license ok');
    } else if (code === EngineEventCode.LicenseValidationFailed) {
      console.error('license failed', message);
    } else if (code === EngineEventCode.InitializationComplete) {
      console.log('engine ready');
    } else if (code === EngineEventCode.InitializationFailed) {
      console.error('init failed', message);
    }
  },
  onFaceLandmarks: (faces) => {
    // faces[].rect, key_points, visibility, face_id, score, pitch, roll, yaw
  },
  maxFaces: 10,
});

Code	Name
`0`	`EngineEventCode.LicenseValidationSuccess`
`1`	`EngineEventCode.LicenseValidationFailed`
`100`	`EngineEventCode.InitializationComplete`
`101`	`EngineEventCode.InitializationFailed`

Omit onFaceLandmarks unless you need landmarks. Enabling it runs face detection every frame.

Process frames

Prefer processImage. It returns ImageData synchronously.

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
const video = document.querySelector('video');

function loop() {
  if (engine.initialized && video.readyState >= 2) {
    const result = engine.processImage(
      video,
      video.videoWidth,
      video.videoHeight,
      FrameType.Video,
      MirrorMode.Horizontal, // front camera
    );
    if (result) {
      if (canvas.width !== result.width) canvas.width = result.width;
      if (canvas.height !== result.height) canvas.height = result.height;
      ctx.putImageData(result, 0, 0);
    }
  }
  requestAnimationFrame(loop);
}
loop();

input may be ImageData, HTMLImageElement, HTMLCanvasElement, HTMLVideoElement, or Uint8ClampedArray (then width / height are required).

FrameType.Video — live camera / streaming (temporal smoothing)
FrameType.Image — still photos

processTexture(textureHandle, width, height, stride, frameType, mirrorMode) is for custom GPU texture input. Mirror is not applied on this path. Typical web apps should use processImage.

Stats

const { fps, avgProcessTimeMs, sessionTimeS } = engine.getStats();

Destroy

engine.destroy();

Call this on page unload or when a React/Vue component unmounts. For TRTC / Agora / LiveKit: Third-party Integration.

Introduction

Android

iOS

macOS

Windows

Linux

Web

Install

Create the engine

Skin beauty

Face reshape

Body reshape

Makeup

Filters and stickers

Virtual background and chroma key

Callbacks

Process frames

Stats

Destroy

​Install

​Create the engine

​Skin beauty

​Face reshape

​Body reshape

​Makeup

​Filters and stickers

​Virtual background and chroma key

​Callbacks

​Process frames

​Stats

​Destroy

​Related

Install

Create the engine

Skin beauty

Face reshape

Body reshape

Makeup

Filters and stickers

Virtual background and chroma key

Callbacks

Process frames

Stats

Destroy

Related