Face Liveness SDK

A lightweight TypeScript SDK for real-time face liveness detection using MediaPipe Tasks Vision. Capture multiple face images with automatic positioning guidance for anti-spoofing verification.

Features

• Real-time face detection with position guidance (MediaPipe @mediapipe/tasks-vision v0.10+)
• Automatic image capture (optimized images)
• Cross-platform support (Web, React, mobile browsers including Samsung)
• TypeScript support with full type definitions
• CPU delegate default for reliable mobile GPU compatibility
• Hybrid asset loading — CDN by default, self-hosted override supported

Quick Start

Installation

# Using yarn
yarn add @aigencorp/face-liveness-sdk

# Using npm
npm install @aigencorp/face-liveness-sdk

@mediapipe/tasks-vision is installed automatically as a dependency.

Basic Usage

import { createLivenessSDK } from '@aigencorp/face-liveness-sdk';

const video = document.getElementById('video');
const sdk = await createLivenessSDK(video);

// Handle captured images
sdk.on('capture:complete', (images) => {
  console.log('Captured images:', images);
  // Send to your verification API
});

// Start capture
sdk.captureImages();

Integration Guides

Choose your integration approach:

📱 HTML/JavaScript → HTML_GUIDE.md

Complete examples with vanilla JavaScript (no external MediaPipe scripts required).

⚛️ React → REACT_GUIDE.md

React components, hooks, and Next.js setup with TypeScript.

Requirements

• HTTPS for camera access
• Network access to CDN for WASM/models by default (jsdelivr + Google storage)
• Chrome 88+, Firefox 85+, Safari 14+, Edge 88+, modern mobile browsers

For offline or restricted networks, self-host assets via faceDetection config (see HTML_GUIDE.md).

Migration from 1.0.x

Version 1.1.0 migrates from legacy @mediapipe/face_detection to @mediapipe/tasks-vision. Public API (createLivenessSDK, events, image output) is unchanged. Remove any legacy MediaPipe <script> tags from your HTML — they are no longer needed.

How It Works

1. Initialize camera and face detection
2. Guide user to position face correctly
3. Capture images automatically when positioned well
4. Return base64 images for API verification

Browser Support

• Chrome 88+, Firefox 85+, Safari 14+, Edge 88+
• Requires HTTPS for camera access
• Mobile browsers supported

API Overview

// Create SDK instance
const sdk = await createLivenessSDK(videoElement);

// Event listeners
sdk.on('camera:ready', () => console.log('Ready'));
sdk.on('face:position', (pos) => console.log('Position:', pos));
sdk.on('capture:complete', (images) => console.log('Done:', images));

// Control methods
await sdk.captureImages();
sdk.destroy();

Configuration

const sdk = await createLivenessSDK(video, {
  ui: { enableLogging: true }
});

Note: Core settings (resolution, capture count, quality) are optimized and fixed for consistent performance across devices.

Image Output

Returns array of base64 strings:

// Example output
[
  "iVBORw0KGgoAAAANSUhEUgAA...",
  "iVBORw0KGgoAAAANSUhEUgAA...",
  // ... more images
]

Events

| Event | Description | Data | |-------|-------------|------| | camera:ready | Camera initialized | - | | face:position | Real-time face feedback | { isCentered, isGoodDistance, isTooClose, isTooFar } | | capture:started | Capture process began | - | | capture:success | Image captured successfully | - | | capture:complete | All images captured | string[] (base64 images) | | error | Error occurred | Error object |

Examples

Send to API

sdk.on('capture:complete', async (images) => {
  const response = await fetch('/api/verify-liveness', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ images })
  });
  const result = await response.json();
});

Position Feedback

sdk.on('face:position', (position) => {
  if (position.isCentered && position.isGoodDistance) {
    showMessage('Perfect! Stay still...');
  } else if (position.isTooClose) {
    showMessage('Move back');
  } else if (position.isTooFar) {
    showMessage('Move closer');
  } else {
    showMessage('Center your face');
  }
});

License

MIT License

Support

• 📖 Check the integration guides above
• 🐛 Report issues on GitHub
• 💬 Community support in discussions

Ready to integrate? Choose your platform above and follow the step-by-step guide!