@cutos/ai-face-detector

CUTOS 4.0 browser-side face detector powered by MediaPipe Tasks Vision. It detects and crops faces locally inside an LWA and does not require a CUTOS Device Provider or Gateway service.

This package does not perform identity recognition. Face registration, search, comparison, and removal belong to a separate Face Service.

Installation

npm install @cutos/ai-face-detector

Copy the version-matched model and WASM assets into the LWA before development or build:

npx cutos-ai-face-detector-assets public/cutos-ai-face-detector

The command copies the packaged assets explicitly; installing the SDK does not modify the consuming project.

Usage

import { FaceDetector } from '@cutos/ai-face-detector'

const detector = await FaceDetector.create({
  assetBaseUrl: './cutos-ai-face-detector',
  preferredDelegate: 'gpu',
  allowCpuFallback: true,
  minIntervalMs: 200,
  minDetectionConfidence: 0.9,
  minFaceSizeRatio: 0.12,
  maxCenterOffsetRatio: 0.38,
  maxHorizontalCenterOffsetRatio: 0.16,
  guideAspectRatio: 1
})

const result = await detector.detect(videoElement)
if (result.quality.accepted && result.primary) {
  console.log(result.primary.image, result.primary.score)
}

console.log(detector.getDiagnostics())
detector.dispose()

API

FaceDetector.create(options?)

Creates and initializes a detector. GPU is attempted first by default. If GPU initialization fails and allowCpuFallback is enabled, initialization is retried with CPU.

new FaceDetector(options?) / init()

Use these when construction and initialization must be separate. Calling init() again returns the current diagnostics.

detect(video, force?)

Detects faces in the current HTMLVideoElement frame. Unless force is true, repeated calls inside minIntervalMs return the latest result without starting another inference.

The largest detected face is exposed as primary. Quality is accepted only when:

• exactly one face is detected;
• confidence meets minDetectionConfidence;
• face size meets minFaceSizeRatio relative to the visible preview;
• the face centre is inside the circular guide;
• horizontal offset meets maxHorizontalCenterOffsetRatio.

getDiagnostics()

Returns initialization state, selected delegate, asset URL, and inference interval.

dispose()

Closes MediaPipe resources and clears cached inference state. Do not use the instance again without calling init().

Options

| Option | Default | Description | | --- | ---: | --- | | assetBaseUrl | ./cutos-ai-face-detector | Directory containing the WASM files and TFLite model. | | preferredDelegate | gpu | Preferred MediaPipe delegate: gpu or cpu. | | allowCpuFallback | true | Retry with CPU when GPU initialization fails. | | minIntervalMs | 200 | Minimum interval between video inferences. | | minDetectionConfidence | 0.9 | Minimum confidence accepted by the detector and quality gate. | | minSuppressionThreshold | 0.3 | MediaPipe non-maximum suppression threshold. | | minFaceSizeRatio | 0.12 | Minimum face width/height relative to the visible preview. | | maxCenterOffsetRatio | 0.38 | Circular guide radius relative to the visible preview's shortest side. | | maxHorizontalCenterOffsetRatio | 0.16 | Maximum horizontal offset from the visible preview centre. | | guideAspectRatio | source ratio | Visible preview ratio used for centre-crop calculations; use 1 for a square preview. | | cropPaddingRatio | 0.35 | Left/right padding around the cropped face. | | cropTopPaddingRatio | 0.65 | Top padding used to preserve hair and the full head. | | cropBottomPaddingRatio | 0.3 | Bottom padding around the cropped face. | | jpegQuality | 0.86 | JPEG quality used for face and optional full-frame data URLs. | | includeFullFrame | false | Include the full camera frame in each result. |

Result

interface FaceDetectionResult {
  timestamp: number
  frame: { width: number; height: number }
  faceCount: number
  primary: {
    score: number
    box: FaceBoundingBox
    image: string
  } | null
  quality: {
    accepted: boolean
    reasons: FaceQualityReason[]
    singleFace: boolean
    confident: boolean
    largeEnough: boolean
    centered: boolean
  }
  fullFrame?: string
}

primary.image and fullFrame are JPEG data URLs. fullFrame is present only when enabled.

detect() throws when the detector is not initialized or the video has no current frame. create()/init() throws when both the preferred delegate and fallback initialization fail.