@face-auth/face-detector

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

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.

FaceQualityWarningMetric reference

When quality.warning is present, metric can be:

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.