OpenFace Liveness

open-face-liveness is a browser library for local face-liveness, anti-spoofing, and light-response signals.

It runs verification signals locally from an HTMLVideoElement using browser-loadable ONNX models, giving web apps fast face/liveness checks without streaming every video frame to a server.

Use it before ID uploads, sensitive account actions, backend risk checks, or manual review. It is not a standalone KYC or regulated identity-proofing system.

Try the demo

Highlights

• Browser ONNX stack: MediaPipe BlazeFace short-range detector, 478-landmark Face Mesh, Blendshape V2 expressions, and MiniFASNet V1SE/V2 spoof classifiers
• Face geometry: OneEuro smoothing, weighted Procrustes alignment, yaw/pitch/roll pose, fit boxes, and stable anchors
• Liveness challenges: head pan, head pitch, mouth-open, neutral-pose capture, dwell timers, hysteresis, recentering, and telemetry
• Passive RGB anti-spoofing: multi-model MiniFASNet fusion for screen-replay and presentation attack, with Fourier-spectrum supervision upstream
• Active screen-light checks: landmark skin regions, OpenCV HSV sampling, sequence correlation, and response magnitude
• XState verification flow: camera, models, face acquisition, stabilization, liveness, light challenge, completion, and failure

Ready to wire it up? Jump to Quick Start.

Accessibility Warning

The optional light challenge changes screen colors and may flash bright light. Applications using it should warn users first, avoid it for people with photosensitive epilepsy, migraine, or similar concerns, and provide a non-light verification path when appropriate.

Demos

Run the local browser demo:

bun install
bun run demo

Open:

http://127.0.0.1:5173/

The demo shows camera flow, live status, debug diagnostics, and local module results from face, liveness, light, and spoof checks.

Quick Start

Install once the package is published:

bun add open-face-liveness
npm install open-face-liveness

Create a client and run a verification session:

import { createOpenFaceLivenessClient } from 'open-face-liveness';

const verifier = createOpenFaceLivenessClient();

const result = await verifier.start({
  video,
  checks: {
    face: true,
    liveness: true,
    light: true,
    spoof: true,
  },
  models: {
    manifestUrl: '/open-face-liveness/models/manifest.json',
  },
});

The application provides the video element. open-face-liveness loads browser models, runs the enabled checks, and returns a typed VerificationResult.

Results

VerificationResult is exported from the package. Import the canonical type instead of recreating the shape in app or demo code:

import type { VerificationResult } from 'open-face-liveness';

const result: VerificationResult = await verifier.verify(video);

Face output includes detector score, mesh landmarks, fit checks, and stability. Liveness output includes the requested sequence, completed challenges, records, and motion telemetry. Light output includes baseline sampling, per-color steps, sequence score, correlation, and response magnitude. Spoof output summarizes sample counts, model count, real frame ratio, and median scores.

Learn More

• Model capabilities and sources
• Runtime dependencies, assets, and package notes
• Face geometry, landmark smoothing, fit, anchor, and liveness math
• Diagnostics overlay legend
• Third-party model and runtime notices

License

MIT

Bundled models and OpenCV runtime assets retain their upstream licenses. See THIRD_PARTY_NOTICES.md for npm package attribution and license details.