lightweight-expression-detector/ReadMe.md

A lightweight hybrid expression detection module using MediaPipe face blendshapes

# 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](https://github.com/googlesamples/mediapipe) 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

```bash
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 <video> 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