Configuration

Every option below is passed to FaceCaptureSession — directly in core, or through MeeeetUpCamProvider on web and useFaceCaptureSession on React Native. Each one defaults to the behaviour the SDK has always had, so an integration that sets nothing keeps working exactly as before.

Capture gates

Two more options matter less often:

Detector confidence is not pose

minDetectionScore answers is there a face here. minFrontalness answers is this face looking at me. They are deliberately separate: ML Kit pins its confidence at 1.0 while MediaPipe reports 0.70–0.95, so folding one into the other would silently tighten your quality threshold on web only.

The best-shot window

Without captureWindowMs, the SDK captures a face when its pose score stops improving — it smooths the score, waits for the peak to hold for ten frames, and commits. That is right for a camera watching a corridor, where faces arrive and leave on their own schedule.

It is wrong for a kiosk. Somebody standing in front of a screen produces a stream that never settles, and the ten-frame wait plus a ten-second cooldown means the frame chosen at half a second can never be replaced by the better one at a second and a half.

Set captureWindowMs and each face gets a bounded search instead:

1. The window opens on the first frame of that face worth capturing — tracked for 300 ms, three frames at or above minFrontalness.
2. While it is open, every frame that beats the held one replaces it immediately and is published with final: false.
3. When the window expires the held frame is published once more with final: true, and that face is decided.

const session = new FaceCaptureSession({
  sessionType: "interactive",
  captureWindowMs: 2_000,
  minFrontalness: 55,
  onSelect: (face) => {
    setPreview(face.dataUrl);        // updates live as the subject improves
    if (face.final) commit(face);    // the photo
  },
});

The window is per face, which is what lets one mechanism serve both modes: an interactive session has a single subject and therefore a single window, while a passive session runs an independent window for every face in the room.

The clock only runs while the face is there

Window time accrues on frames the face actually appears in. A subject who steps out of shot and returns does not lose their window, and a tab that gets throttled in the background does not spend it either — a single gap longer than 250 ms counts as 250 ms. “Search for two seconds” means two seconds of the subject being present.

Re-arming

A closed window stays closed, so a kiosk does not keep re-photographing the person still standing there.

• Passive: the face re-arms itself once cooldownMs has elapsed since the window closed.
• Interactive: call session.rearm() — or cam.rearm() from useMeeeetUpCam() — when you want the next capture. This is the “retake” button.

A face that goes out of frame mid-window is finalised with whatever it had: leaving with the best available frame beats leaving with nothing.

Choosing thresholds

The numbers depend on lens, lighting and how far away people stand, so measure rather than guess — the live demo puts all four gates on sliders with the current readings next to them, and the frame it captures is the frame this configuration would have sent.

Sensible starting points:

What you receive

Every selection arrives as a SelectedFace:

Identity is not the SDK’s job: two trackIds are two tracks, not necessarily two people. Deduplication and recognition belong to whatever receives the images.