@face-auth/face-detector

Lightweight face detection for browser video streams. Current package version: 0.0.5.

Installation

npm install @face-auth/face-detector

License

Proprietary runtime-only license. You may execute unmodified copies of the package, but modification, redistribution, sublicensing, and other reuse are not permitted. See LICENSE.

Support

• Homepage: https://www.face-auth.me/
• Support: [email protected]

Package format

• import resolves to the package ESM bundle.
• require resolves to the package CommonJS bundle.
• Deep imports are not part of the supported public contract; consume the package root entrypoint only.

Public API

Classes

• FaceVideoDetector
• FaceImageDetector

Enums and helpers

• FaceAdjustment
• getInscribedCircle(...)
• isEllipseInside(...)

Exported types

• BoundingBox
• Detection
• DetectionParams
• DetectionResult
• ImageDetectionResult
• FaceKeypoint
• FacePoseMetrics
• FaceQualityMetrics
• FaceQualityGateResult
• FaceQualityWarning
• FaceQualityWarningMetric
• QualityGateConfig

FaceVideoDetector

Creates a detector over an HTMLVideoElement and emits detection results.

import { FaceVideoDetector } from '@face-auth/face-detector';

const videoElement = document.getElementById('video') as HTMLVideoElement;
const detector = new FaceVideoDetector(videoElement);

Methods

• startDetecting(params?: DetectionParams): Promise<void>
• stopDetecting(): Promise<void>
• onDetection(callback): void
• offDetection(callback): void

onDetection callbacks receive a DetectionResult:

{
  tick: number;
  detections: Detection[];
}

FaceImageDetector

Runs face detection on a single image source.

import { FaceImageDetector } from '@face-auth/face-detector';

const imageDetector = new FaceImageDetector();
const result = await imageDetector.detect(fileOrCanvasOrImageBitmap, {
  qualityGateConfig: {
    strictShouldPass: true,
  },
});

Methods

• detect(image: ImageBitmapSource, options?): Promise<ImageDetectionResult>

Detection output (summary)

{
  detections: Array<{
    boundingBox: {
      x: number;
      y: number;
      width: number;
      height: number;
    };
    score: number;
    keypoints: Array<{
      x: number;
      y: number;
      normalizedX: number;
      normalizedY: number;
      label?: string;
      score?: number;
    }>;
    quality: {
      shouldPass: boolean;
      faceAdjustment: 'none' | 'move_closer' | 'move_farther' | 'show_full_face' | 'turn_face_left' | 'turn_face_right' | 'tilt_head_left' | 'tilt_head_right' | 'lower_chin' | 'raise_chin' | 'improve_lighting' | 'improve_focus';
      warning: {
        metric?: string;
        measuredValue?: number;
        threshold?: number;
      } | null;
      metrics: {
        faceAreaRatio: number;
        blurVariance: number | null;
        blackClippingRatio: number | null;
        brightnessMean: number | null;
        pose: {
          rollDeg: number | null;
          yawRatio: number | null;
          pitchRatio: number | null;
        };
      };
    };
  }>;
}

For video detection, the callback payload also includes tick, the performance.now() timestamp for that processed frame.

Directional adjustments:

• turn_face_left / turn_face_right are corrective turn hints from the current detected pose.
• tilt_head_left / tilt_head_right are corrective roll (ear-to-shoulder) hints.

FaceAdjustment reference

faceAdjustment always returns one primary correction target.

| Value | What correction is requested | | --- | --- | | none | No correction needed. Capture quality is currently acceptable. | | move_closer | Move the face closer to the camera (face appears too small in frame). | | move_farther | Move the face farther from the camera (face appears too large in frame). | | show_full_face | Keep the full face visible and frontal enough so pose can be measured reliably. | | turn_face_left | Turn the face slightly to the user's left to improve frontal alignment. | | turn_face_right | Turn the face slightly to the user's right to improve frontal alignment. | | tilt_head_left | Correct roll by tilting the head slightly to the user's left. | | tilt_head_right | Correct roll by tilting the head slightly to the user's right. | | lower_chin | Lower the chin slightly. | | raise_chin | Raise the chin slightly. | | improve_lighting | Improve lighting/exposure conditions on the face. | | improve_focus | Improve image sharpness/focus (reduce blur). |

FaceQualityWarningMetric reference

When quality.warning is present, metric can be:

| Value | Metric meaning | | --- | --- | | faceAreaRatio | Relative face size in frame (face bounding box area / frame area). | | blurVariance | Sharpness proxy (Laplacian variance); low values indicate blur. | | brightnessMean | Average brightness in the sampled face region. | | blackClippingRatio | Ratio of near-black pixels in the face region. | | rollDeg | Lateral head tilt angle in degrees (ear-to-shoulder). | | yawRatio | Horizontal turn/off-center pose ratio. | | pitchRatio | Vertical chin pose ratio (up/down). |

Example (video)

detector.startDetecting({ minIntervalMs: 120 });

detector.onDetection((result) => {
  const face = result.detections[0];
  if (!face) return;

  console.log(face.boundingBox);
  console.log(face.quality.shouldPass);
  console.log(face.quality.faceAdjustment);
  console.log(face.quality.warning);
  console.log(face.quality.metrics);
});

Browser support

• Browser runtime only.
• Requires HTMLVideoElement / ImageBitmapSource input.
• DetectionParams.minIntervalMs defaults to 100 when omitted.