facerecognitionlib

A modular and customizable face recognition camera utility for the web. Easily integrate webcam face detection and recognition with detector model, API calls, toast notifications, and custom UI.

✨ Features

• Plug-and-play webcam integration
• Works with any face detector (here used detection-lib)
• Customizable recognition API payload
• UI overlay with camera, face box, and status
• Supports toast feedback (e.g., with react-hot-toast)
• Easily extendable and styled via uiOptions

Installation

npm install facerecognitionlib

Usage

import { opencam } from 'facerecognitionlib';

opencam({
  detector: detectorInstance,              // Required
  onRecognized: async (data, stopCamera,base64Image) => {
    // Called on successful recognition
    console.log("Recognized user:", data);
    await markAttendance(data.user_id);    // Your backend API call
    stopCamera();                          // Call this to stop webcam (optional)
  },
  recognitionUrl: 'http://your-server/recognize_face', // Required
  recognitionPayloadBuilder: (base64Image) => ({
    image: base64Image,
  }),

});

Parameters

| Name | Type | Required | Description | | ---------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------------------------ | | detector | object | ✅ | Your face detection model instance (must have a .detect(canvas) method) | | onRecognized(data, stopCamera,base64Image) | function | ✅ | Called when a face is recognized successfully. You can make API calls and manually call stopCamera() to end detection. | | recognitionUrl | string | ✅ | Endpoint to send base64 face image to for recognition | | recognitionPayloadBuilder() | function | ✅ | Function that returns payload for recognition API | | uiOptions | object | ❌ | Optional styling for video, canvas, status bar, and close button |

CustomUi(via uiOptions)

Pass a uiOptions object to override default styles.

uiOptions: {
 videoStyles: {
   width: "80vw",
   height: "80vh",
   borderRadius: "12px",
   zIndex: 2000,
 },
 statusStyles: {
   background: "rgba(0,0,0,0.7)",
   fontSize: "1rem",
   color: "#eee",
 },
 closeButtonStyles: {
   top: "10px",
   right: "10px",
   backgroundColor: "red",
 },
}

All uiOptions support inline styles (like style={{...}} in React).

Custom Recognition Callback

You can handle success or failure of recognition and API calls via your own logic in onRecognized:

const onRecognized = async (data, stopCamera,base64Image) => {
  try {
    const res = await axios.post('/api/mark_attendance', {
      payloads,
      base64Image   //optional :depend on your route if you want you can pass it
    });

    toast.success("Attendance marked!");
    stopCamera(); // Optional — stop camera after success

  } catch (err) {
    toast.error("Failed to mark attendance.");
    // Do not stop camera if you want to retry
  }
};

Recognition Flow

• Webcam starts
• Face is detected by your detector
• Every 3 seconds, a snapshot is taken and sent to your API
• If recognition is successful:
• onRecognized(data, stopCamera) is called
• You can manually stop or continue webcam
• If not, error is shown and next cycle starts

Stop the Camera

Call stopCamera() from within your onRecognized callback to manually stop and clean up the camera view.