facerecognitionlib

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) => {
    // 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)	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) => {
  try {
    const res = await axios.post('/api/mark_attendance', {
      payloads
    });

    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.