MentalHealth: A Browser-Based Emotion Detector with a Server-Side Ambiguity

What MentalHealth Actually Solves

MentalHealth targets a specific niche: turning a webcam feed into an emotion label without a heavy ML backend. The README describes an application that analyzes facial expressions, identifies emotions like happiness, sadness, anger, and surprise, and then offers personalized recommendations. It also mentions notifications to contact mental health professionals when needed. The intended user is a developer building a mental health monitoring tool, likely a prototype or a research demo, who wants a simple JavaScript API rather than a full service. The project is not a clinical device. It is a face analysis utility with a thin layer of recommendation logic on top. For engineers, the core deliverable is the EmotionDetection module, which you can install from npm and call with a local image path or a live camera stream.

The Geometric Core: How Emotion Detection Works

The detection mechanism is refreshingly explicit. Instead of a black-box neural network, the README gives seven formulas. The djb2Hash function converts facial landmark strings into a unique FaceID, an unsigned 32-bit integer. Happiness is measured by lip stretch, the Euclidean distance between lip corners, and cheek raise, the vertical distance between cheek and eye landmarks. Sadness uses lip depression, the vertical gap between the lip corner and the bottom lip. Anger is brow lowering, the vertical distance between inner and outer brow landmarks. Surprise combines eye openness and jaw drop, both vertical distances. Neutral is the sum of Euclidean distances between key landmarks, a deviation score. This approach is transparent and testable. You can replicate each formula in a few lines of code. The trade-off is that these geometric heuristics are sensitive to camera angle, lighting, and facial proportions. A person with naturally low brows might trigger the anger threshold without being angry. The README does not specify how landmarks are extracted, so the accuracy depends entirely on the underlying face detection library, which is not named.

Getting It Running: The npm Package and Two Call Styles

The README provides a clear path to installation. You run npm install -g @galihridhoutomo/mentalhealth to install globally, then import the module. For CommonJS, you use const EmotionDetection = require('@galihridhoutomo/mentalhealth');. For ES modules, you use import EmotionDetection from '@galihridhoutomo/mentalhealth';. The primary function is detectEmotion(imagePath), which returns a Promise. The sample output is a JSON object with an emotion string and a confidence score, like { "emotion": "happy", "confidence": 0.92 }. For real-time use, detectEmotionLive() opens the camera and returns a promise with the detected emotion. There are optional configuration options: model can be 'basic' or 'advanced', and threshold sets the minimum confidence, with 0.8 as the example. The global install is a red flag for a library. Global packages are meant for CLI tools, not for importable modules. You would likely want to install it locally with --save-dev. The README does not mention a peer dependency for face landmark detection, which is a gap you must fill yourself.

The IoT and Voice Analysis Claims Are Undocumented

The Technologies section lists IoT with health sensors, including GSR, MAX30102, BH1750, and ESP32, plus voice analysis and machine learning. The README gives no code, no schematics, no API endpoints, and no data flow for any of these. The formulas cover only facial landmarks. There is no mention of how sensor data would be ingested, how voice features are extracted, or how the ESP32 connects to the browser app. This is a significant mismatch between the scope described and the material provided. If you adopt this project expecting a full multimodal monitoring system, you will be disappointed. The repository appears to be primarily a face emotion detector. The IoT and voice components are either aspirational or live in undocumented parts of the codebase. For an engineer, this means you should treat those features as nonexistent until you inspect the repository source directly. The release history, with versions v574 through v576, suggests active development, but the README does not explain what changed.

A Real Limitation: Confidence Thresholds and Neutral Bias

The optional threshold parameter, defaulting to 0.8 in the example, controls the minimum confidence for a detection. That sounds reasonable, but the README does not say what happens when confidence falls below the threshold. Does the function return 'neutral'? Does it throw an error? Does it return a null emotion? The sample output shows a confidence of 0.92, but there is no failure-mode documentation. The geometric formulas also have a built-in bias toward neutral. The deviation-from-neutral calculation sums distances across landmarks. If a face is perfectly still, the sum is near zero, so neutral is the default. But if the camera has slight jitter, the deviation increases, potentially misclassifying neutral as surprise or anger. The README does not discuss calibration or normalization. This is a genuine weakness for real-world use, where webcams produce noisy landmarks. You would need to test the threshold value against your own user population to avoid false positives. The project gives you the tools to do that, but it does not hand you a working configuration.

The Alternative: A Dedicated Emotion Recognition Library

The closest alternative is a library like face-api.js, which provides pre-trained models for face detection and expression recognition directly in the browser. The difference in approach is fundamental. face-api.js uses convolutional neural networks to classify expressions from a set of training images, giving you a probability distribution across multiple emotions. MentalHealth uses hand-crafted geometric distances, which are deterministic and explainable but less robust to variation. If you need a quick prototype with minimal dependencies, MentalHealth's npm package might suffice. If you need accuracy across diverse faces and lighting conditions, a neural approach is likely to perform better. The README does not compare itself to any alternative, so you must make that judgment yourself. The geometric formulas are a strength if you want to debug why a detection failed, because you can compute each distance manually. The neural approach gives you a black box that you cannot easily inspect.

Maintenance, Licensing, and Upgrade Cost

The project is licensed under MIT, which means you can use, modify, and distribute it freely, including in commercial products, as long as you preserve the copyright notice. The README includes a BibTeX citation entry, which is a nice touch for academic use. The repository is not archived, and the last push was June 28, 2025, with a release tagged v576 on the same day. That suggests active maintenance, but the release notes are not provided, so you cannot know what changed between versions. The upgrade cost is low if you install via npm: you can update the package and re-run your tests. However, the global installation instruction is a trap. If you follow it, you will have a single version on your machine, and your project will not pin a dependency. That makes upgrades unpredictable. You should install locally and specify a version in your package.json. The project's documentation is sparse, so upgrading may require reading the source code to understand breaking changes. The formulas are stable, but the API surface may change without notice.

Editorial conclusion

Adopt MentalHealth if you need a lightweight, MIT-licensed emotion detection library that runs in a browser or Node.js and you are comfortable deriving your own deployment pipeline. Do not adopt it if you require documented server-side integration, a maintained roadmap, or evidence of production use. Before committing, verify that the npm package version matches the repository state, test the detectEmotion and detectEmotionLive functions against your own images, and confirm the threshold and model options behave as documented. The project's value lies in its explicit geometric formulas, not in its operational completeness.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes