Skip to main content
SDK 2.0.0. Auth: Auth & License.

Auth in production

Keep app_id / app_key on the server. Fetch a short-lived licenseToken from your backend, then pass it to the engine.
Never put appKey in a frontend bundle.
Bind the exact production domain in the Dashboard. Web cannot use offline .lic.

One engine per page

Create one BeautyEffectEngine, call init() once, reuse it for the session. Do not construct a new engine every frame.

Frame loop

  • Drive video with requestAnimationFrame, not an unbounded while.
  • Use FrameType.Video for camera; FrameType.Image for stills.
  • Match canvas size to the processed ImageData to avoid extra scaling.
  • Skip frames until video.readyState >= 2 and videoWidth > 0.
  • Prefer processImage for camera and canvas. processTexture does not apply mirror.

Large stills (preview vs export)

For gallery photos and retouching apps, do not send full-resolution pixels into processImage on every slider change. When the file opens, keep two buffers:
  1. Preview frame — a downscaled ImageData (long edge about 1280–1440, or the display canvas CSS size × devicePixelRatio, whichever is smaller). Use this while the user adjusts effects.
  2. Original — the HTMLImageElement (or an unscaled bitmap). Run processImage on it once, when the user exports.
Use FrameType.Image for both. Same engine, same setters. Output size matches input size: preview output is small; export output is full resolution. Do not upscale the preview result to fake an export. Do not pass an unscaled <img> into the preview loop — processImage reads naturalWidth / naturalHeight.
Camera preview is a different path: capture resolution + FrameType.Video. Debounce slider-driven processImage. Show a busy state before export; full-resolution processing is synchronous and can hitch the page.

Parameters

Start low in real-time preview (smoothing ~ 0.2–0.5). Reshape is [-1, 1]; small values look more natural on camera. Do not register onFaceLandmarks unless the UI needs them — it forces per-frame detection. setBeautySkinOnly(true) avoids smearing backgrounds when smoothing is high.

Resources

  • Host filter / sticker .fbd and background jpg/png as static files; pass the URL into setFilter / setSticker / setVirtualBackground.
  • Runtime resources are loaded by the SDK during init(). Do not put a site-root resource.fbd for the engine.
  • Switch filter / sticker on user input, not every frame.

Memory

  • Call destroy() on unmount / beforeunload.
  • Reuse the display canvas; do not allocate a new canvas per frame.

HTTPS and CORS

Camera access needs HTTPS or localhost. If filter / sticker assets are on another origin, send CORS headers.