← Back to the blog
Plugins #deface

On-screen face blur with the Deface plugin

A privacy plugin: a Python worker detects faces with CenterFace and the player overlay blurs, mosaics or masks them client-side. Read the privacy caveat before you rely on it.

2 min read
Leer en español

Privacy at the presentation layer

The Deface plugin blurs faces on the player. A Python worker runs CenterFace over the app's live HLS stream, streams normalized face boxes into the plugin's live-data channel, and the player overlay obfuscates each region client-side — blur, mosaic or a solid mask.

It is modelled on the open-source ORB-HD/deface, adapted into StreamHub's worker framework so the process lifecycle is managed for you.

Read this caveat first

Deface anonymizes the player only. The masks are drawn by the viewer's browser on top of the video element, which means:

  • the raw stream (WebRTC, HLS segments, RTMP restreams) still contains the faces;
  • recordings, VODs and snapshots still contain the faces — the recording pipeline is untouched;
  • a viewer with DevTools can remove the overlay.

Treat it as a presentation-layer privacy feature — kiosk displays, public embeds, demo screens — not anonymization of the media itself. Server-side burn-in of the masks is not implemented.

Install and configure

curl -X POST $BASE/apps/live/plugins/deface/install \
  -H "Authorization: Bearer $TOKEN"

curl -X PATCH $BASE/apps/live/plugins/deface \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"enabled": true, "config": {"room": "lobby", "replacewith": "blur"}}'

room is the only required field. Useful config knobs:

  • replacewith — blur | mosaic | solid | none (detect only).
  • thresh — detection threshold (default 0.2).
  • maskScale — enlarge boxes to cover hair/chin (default 1.3).
  • fps — frames sampled per second (default 2).
  • boxes — rectangles instead of the default ellipses.

Why it does not flicker

The worker POSTs on every sampled frame — an empty face list actively clears the masks. That is deliberate: a lingering stale mask is a rendering bug, while a missing mask is a privacy bug. The overlay maps CenterFace's normalized boxes onto the actual video element (accounting for letterbox/pillarbox), and debounces empty payloads before clearing, so a flaky detection on a static scene does not blink.

CPU is usually enough

CenterFace is much lighter than YOLO. Keep fps low (1–4) and downscale HD sources with scale around 640x360, and CPU handles most rooms comfortably. CUDA only pays off above ~10fps or with many simultaneous rooms, and the worker never crash-loops over a missing GPU — it falls back to CPU with a log note. The ~7MB model downloads on first run and is shared across apps.