Face Liveness SDK

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

Features

• Real-time face detection with position guidance
• Automatic image capture (optimized images)
• Cross-platform support (Web, React, mobile browsers)
• TypeScript support with full type definitions
• Lightweight (4KB gzipped)
• Production ready with optimized settings

Quick Start

Installation

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

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

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 and MediaPipe CDN integration.

⚛️ React → REACT_GUIDE.md

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

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!