@everventure/face-recognition-sdk

A React hook for face recognition using face-api.js with API integration support.

Installation

npm install everventure-face-recognition-sdk face-api.js

Quick Start

1. Setup Local Models

Copy models to your app's public folder:

cp -r node_modules/everventure-face-recognition-sdk/public/models ./public/

2. Configure API Key

Set your API key before using the hook:

import { setApiKey } from 'everventure-face-recognition-sdk';

// Set your API key
setApiKey('your-api-key-here');

3. Use the Hook

import { useFaceRecognition } from 'everventure-face-recognition-sdk';

function App() {
  const {
    videoRef,
    canvasRef,
    isLoading,
    isReady,
    status,
    register,
    recognize,
  } = useFaceRecognition({
    autoStart: true,        // Auto-start video (default: true)
    modelPath: '/models',   // Path to models (default: '/models')
  });

  const handleRegister = async () => {
    const result = await register('John Doe');
    
    if (result.success) {
      console.log('✅ Registered!', result.message);
    } else {
      console.error('❌ Error:', result.message);
    }
  };

  const handleRecognize = async () => {
    // With default threshold (0.6)
    const result = await recognize();
    
    // Or with custom threshold
    // const result = await recognize(0.8);
    
    if (result.success && result.match) {
      console.log('✅ Recognized:', result.name);
    } else {
      console.log('❌ No match:', result.message);
    }
  };

  return (
    <div>
      <video ref={videoRef} width={640} height={480} autoPlay muted />
      <canvas ref={canvasRef} width={640} height={480} />
      
      <button onClick={handleRegister} disabled={!isReady || isLoading}>
        Register Face
      </button>
      <button onClick={handleRecognize} disabled={!isReady || isLoading}>
        Recognize Face
      </button>
      
      <div>{status}</div>
    </div>
  );
}

API Reference

setApiKey(key: string)

Set the API key for all API requests. The key will be sent in the X-API-Key header.

import { setApiKey } from 'everventure-face-recognition-sdk';

setApiKey('your-api-key-here');

useFaceRecognition(options?)

React hook for face recognition functionality.

Options

interface UseFaceRecognitionOptions {
  autoStart?: boolean;  // Auto-start video stream (default: true)
  modelPath?: string;   // Path to local models (default: '/models')
}

Returns

{
  // Refs
  videoRef: RefObject<HTMLVideoElement>;
  canvasRef: RefObject<HTMLCanvasElement>;
  
  // State
  isLoading: boolean;   // Models are loading
  isReady: boolean;     // Ready to use
  error: string | null; // Error message
  status: string;       // Status message
  
  // Functions
  startVideo: () => Promise<boolean>;
  stopVideo: () => void;
  register: (name: string) => Promise<RegisterResult>;
  recognize: (threshold?: number) => Promise<RecognizeResult>;
  detectFace: () => Promise<number[] | null>;
  setStatus: (status: string) => void;
}

register(name: string)

Register a face with a name. Sends data to the API.

const result = await register('John Doe');

// Returns:
interface RegisterResult {
  success: boolean;
  message: string;
  userId?: string;
  error?: string;
}

recognize(threshold?: number)

Recognize a face from video stream. Sends data to the API.

// With default threshold (0.6)
const result = await recognize();

// With custom threshold
const result = await recognize(0.8);

// Returns:
interface RecognizeResult {
  success: boolean;
  match: boolean;
  name?: string;
  distance?: number;
  message?: string;
  error?: string;
}

Note: The threshold parameter controls the similarity threshold for face matching. Lower values (e.g., 0.4) are more lenient and may match less similar faces, while higher values (e.g., 0.8) are stricter and require more similar faces. The default value is 0.6 if not provided.

License

MIT