ERML — Emotion Recognition ML

A pip-installable Python SDK for facial emotion recognition. Drop it into your own project, pass it a frame, get back structured emotion data — no camera or display logic included.

from erml import EmotionDetector, FacePrediction, format_results

detector = EmotionDetector()
results = detector.analyze("photo.jpg")

# Object access — full IDE autocomplete
print(results[0].emotion, results[0].confidence)

# Or export to plain dict
print(format_results(results))

Face 1  [x=85 y=67 w=259 h=259]
  Emotion    : Neutral
  Confidence : 42.9%
  All scores :
    neutral    42.9%  ████████
    sad        18.2%  ███
    fear       15.4%  ███
    angry      10.2%  ██
    happy       7.5%  █
    surprise    5.2%  █
    disgust     0.1%

Install

pip install erml

Or from source:

git clone https://github.com/sid-lakhani/erml
cd erml
uv venv --python 3.12
source .venv/bin/activate.fish   # or: source .venv/bin/activate (bash/zsh)
uv pip install -r requirements.txt -r requirements-dev.txt
uv pip install -e .

Requires Python 3.8–3.12. TensorFlow does not yet support Python 3.13+. To train, additionally install: uv pip install -r requirements-train.txt

Usage

Basic

from erml import EmotionDetector

detector = EmotionDetector()
results = detector.analyze("photo.jpg")

Input types

import cv2
import numpy as np
from PIL import Image

# File path
results = detector.analyze("photo.jpg")

# OpenCV BGR array
frame = cv2.imread("photo.jpg")
results = detector.analyze(frame)

# PIL Image
pil_img = Image.open("photo.jpg")
results = detector.analyze(pil_img)

Output

analyze() returns a list of dicts — one per detected face:

[
  FacePrediction(
    emotion="happy",        # top predicted emotion
    confidence=0.87,        # float 0–1
    all={                   # scores for all 7 emotions
      "angry": 0.01,
      "disgust": 0.00,
      "fear": 0.02,
      "happy": 0.87,
      "sad": 0.03,
      "surprise": 0.05,
      "neutral": 0.02
    },
    bbox=BoundingBox(x=120, y=80, w=64, h=64)
  )
]

Access fields directly with full IDE autocomplete:

result = results[0]
print(result.emotion)        # "happy"
print(result.bbox.x)         # 120

Or export to a plain dictionary (e.g. for JSON logging):

raw = results[0].model_dump()
raw_list = [r.model_dump() for r in results]

Returns [] if no face is detected. Never raises on empty input.

Human-readable output

from erml import EmotionDetector, format_results

detector = EmotionDetector()
print(format_results(detector.analyze("photo.jpg")))

Emotions

angry · disgust · fear · happy · sad · surprise · neutral

Trained on FER-2013.

Training

To retrain from scratch, download FER-2013 and place it at dataset/ organized by emotion subfolder, then:

python training/train.py

Trains for up to 20 epochs with early stopping, saves best weights to erml/assets/erml_v1.h5.

Quick inference script

python examples/test_inference.py photo.jpg

Webcam demo

python examples/webcam_demo.py
python examples/webcam_demo.py --camera 1  # alternate camera index

Press Q to quit. Draws bounding boxes and emotion labels in real time.

Tests

pytest tests/ -v

All tests run fully headless — no camera, no display, no trained model required.

Project structure

erml/
├── erml/
│   ├── __init__.py       # public API: EmotionDetector, FacePrediction, format_results
│   ├── constants.py      # EMOTION_LABELS and shared constants
│   ├── detector.py       # EmotionDetector class (ONNX & YuNet runtime)
│   ├── download.py       # atomic auto-downloader for ONNX weights
│   ├── preprocess.py     # face ROI preprocessing
│   ├── schemas.py        # Pydantic output models (FacePrediction, BoundingBox)
│   ├── utils.py          # format_results helper
│   └── assets/           # ONNX weights cached here automatically
├── training/
│   ├── model.py          # TF/Keras CNN architecture definition
│   └── train.py          # training script (requires: pip install erml[train])
├── tests/
├── scripts/
│   └── export_onnx.py    # utility to export trained Keras models to ONNX
├── examples/
└── pyproject.toml

Versioning

License

MIT