Skip to main content

​
Quickstart Guide

Get EmoChat emotion recognition AI running in just a few steps. This guide will take you from installation to your first real-time emotion detection session.

​
Prerequisites

Before starting, ensure you have:
  • Python 3.8 or higher installed
  • A webcam or camera device
  • Basic familiarity with command line
  • Windows, macOS, or Linux operating system

​
Quick Start Steps

1

Install Dependencies

Clone the repository and install required Python packages:
git clone https://github.com/Dani-zm/emotion-recognition-ai.git
cd emotion-recognition-ai
pip install -r requirements.txt
Make sure to install opencv-contrib-python (not just opencv-python) as it includes the required cv2.face module for facial landmark detection.
The key dependencies include:
  • Flask 3.1.3 - Web server
  • opencv-contrib-python 4.13.0.92 - Computer vision
  • scikit-learn 1.8.0 - Machine learning
  • numpy 2.4.2 - Numerical computing
2

Prepare Training Data

Create a data directory with emotion folders:
mkdir -p ../data/happy ../data/sad
Add training images to each folder:
  • Place happy facial expression images in ../data/happy/
  • Place sad facial expression images in ../data/sad/
Use at least 50-100 images per emotion for best results. Images should show clear facial expressions with good lighting.
Generate the training data file:
python prepare_data.py
This creates data.txt with normalized facial landmarks for each image.
3

Train the Model

Train the Random Forest classifier:
python train_model.py
You’ll see output like:
Accuracy: 87.50%
[[45  5]
 [ 3 47]]
The model is saved as the model file in your project directory.
Training typically takes 10-30 seconds depending on your dataset size. Aim for accuracy above 80% for reliable predictions.
4

Launch Flask Server

Start the web application server:
python app.py
You should see:
Iniciando servidor Flask de EmoChat en http://127.0.0.1:5000/
 * Running on http://127.0.0.1:5000
 * Debug mode: on
The server is now running and ready to process webcam frames!
5

Access Web Interface

Open your web browser and navigate to:
http://127.0.0.1:5000/
You’ll see the EmoChat web interface with:
  • Activate Camera button to enable your webcam
  • Real-time emotion detection display
  • Session recording controls
  • Context input for AI analysis
6

Use Real-Time Emotion Recognition

In the web interface:
  1. Click Activate Camera to start your webcam
  2. Grant camera permissions when prompted
  3. Your emotion will be detected and displayed in real-time
  4. See “HAPPY” or “SAD” based on your facial expression
For best results, ensure good lighting and face the camera directly. The system detects 68 facial landmark points to classify your emotion.
Optional: Record a Session
  1. Enter a context in the text field (e.g., “Talking about my day”)
  2. Click Start Recording (30s)
  3. Express yourself for 30 seconds
  4. Get empathetic AI feedback from Google Gemini
7

Optional: Configure Gemini AI

To enable AI-powered emotional analysis:
  1. Get a Google Gemini API key from Google AI Studio
  2. Set the API key in app.py:
app.py
client = genai.Client(api_key="YOUR_API_KEY_HERE")
Or use an environment variable:
export GEMINI_API_KEY="your-api-key"
Without a Gemini API key, the session analysis feature will return an error. The basic emotion detection will still work.

​
What’s Next?

Installation Details

Learn about system requirements, troubleshooting, and advanced setup

API Reference

Explore the Flask API endpoints and integrate with your own applications

Model Training

Deep dive into the machine learning pipeline and improve accuracy

Web Application

Learn about the Flask server and frontend integration

​
Troubleshooting

If the browser denies camera access:
  • Click the camera icon in the address bar
  • Allow camera permissions for localhost
  • Refresh the page and try again
  • Make sure no other application is using the camera
This means opencv-contrib-python is not installed:
pip uninstall opencv-python
pip install opencv-contrib-python==4.13.0.92
If you see “No se encontró el modelo entrenado”:
  1. Make sure you ran train_model.py successfully
  2. Check that the model file exists in your project directory
  3. Verify the training completed without errors
If emotions are detected incorrectly:
  • Ensure good lighting on your face
  • Face the camera directly
  • Use more diverse training images
  • Retrain with a larger dataset (100+ images per emotion)
  • Check that training accuracy was above 80%

​
Understanding the Detection Flow

Here’s what happens when you use EmoChat:
  1. Webcam Capture: JavaScript captures frames from your webcam every second
  2. Base64 Encoding: Images are encoded and sent to the Flask server via /predict
  3. Face Detection: OpenCV Haar Cascade detects faces in the image
  4. Landmark Extraction: 68 facial landmark points are identified using LBF model
  5. Normalization: Coordinates are normalized relative to face boundaries
  6. ML Prediction: Random Forest classifier predicts emotion (0=Happy, 1=Sad)
  7. Real-time Display: Emotion is shown in the web interface

​
Advanced Usage

​
Testing Without Web Interface

Test the model directly with your webcam: 
python test_model.py
Press q to quit the OpenCV window.

​
Session Analysis

The session recording feature:
  • Captures emotions every second for 30 seconds
  • Sends the emotion sequence to Google Gemini AI
  • Receives empathetic feedback based on patterns
  • Helps understand emotional fluctuations over time
All facial data is processed locally and never stored. Session analysis only sends emotion labels (not images) to Gemini AI.

​
Next Steps

Now that you have EmoChat running, explore: Ready to dive deeper? Check out the Installation Guide for advanced configuration options.

Build docs developers (and LLMs) love

Get started for freeTalk to us