lightweight-expression-detector

A lightweight facial emotion detection module using MediaPipe Face Landmarker blendshapes.
It supports both vanilla JavaScript/TypeScript projects and React-based applications.

This package is optimized for browser-based applications and is significantly lighter and faster compared to alternatives like TensorFlow.js or face-api.js. It leverages the power of MediaPipe Tasks to extract blendshape data from facial landmarks and classify emotions using a baseline comparison strategy.

Features

• Blendshape-based emotion classification using MediaPipe
• Very lightweight and fast — ideal for frontend / client-side apps
• Supports both React and non-React environments
• Can be used in real-time applications (e.g., emotion tracking via webcam)
• No dependencies on TensorFlow or heavy ML models

Installation

npm install lightweight-expression-detector

Note:- This will also automatically install @mediapipe/tasks-vision, as it is listed as a dependency.

Usage

1. Non-React Projects (Vanilla JS / TS)

Use the classifyBlendshapes function from the package:

import { classifyBlendshapes } from 'lightweight-expression-detector';

const emotion = classifyBlendshapes(blendshapesArray, baselineBlendshapeData);

• blendshapesArray: Category[] from FaceLandmarkerResult

• baselineBlendshapeData: A Record<string, number> of neutral face scores, calculated from initial frames

2. React Projects

Use the useEmotionDetector React Hook to handle everything internally:

import { useEmotionDetector } from 'lightweight-expression-detector';

const { videoRef, emotion, blendshapes, baseline, isCalibrating } = useEmotionDetector();

• Attach videoRef to a element and the hook will handle MediaPipe, loop detection, and emotion updates for you.

Example Projects

Test Project with Live Implementation/Demo

https://github.com/Anant-404/Demo_lightweight-expression-detector

When to Use This

This module is ideal for:

• Lightweight browser-based emotion detection • Projects where performance and bundle size matter • Realtime webcam analysis in web apps • Client-side-only use cases (no server dependencies)

It is not intended for:

• Backend use • High-accuracy emotion analytics at clinical or scientific levels

License

MIT © 2025 Anant Mishra