Distracted-Gaming Alert System for Overnight Gamers

A production-quality web application that monitors gamer fatigue in real-time using behavioral tracking, eye fatigue detection, and machine learning to compute a Cognitive Drift Score (CDS).

Features

• Behavioral Tracking: Monitor keyboard and mouse activity plus reaction time
• Eye Fatigue Detection: Track blink rate and Eye Aspect Ratio (EAR)
• Cognitive Drift Score (CDS): ML-powered real-time fatigue scoring (0-100)
• State Classification: FOCUS, MILD_DRIFT, HIGH_DRIFT, FATIGUE
• Professional Dashboard: Modern UI with real-time charts and gauges
• Session Management: Track and review past sessions
• Smart Alerts: Notifications when fatigue levels are concerning

Tech Stack

Backend

• Python 3.x
• FastAPI
• scikit-learn (RandomForest classifier)
• NumPy, Pandas
• Uvicorn

Frontend

• React 18 + TypeScript
• Vite
• Tailwind CSS
• Recharts
• Axios
• Lucide React (icons)

Project Structure

ml/
├── backend/
│   ├── main.py              # FastAPI application
│   ├── models.py            # Pydantic models
│   ├── train_model.py       # ML training script
│   ├── ml_service.py        # ML prediction service
│   ├── requirements.txt     # Python dependencies
│   └── ml_models/           # Trained model storage (auto-created)
│
└── frontend/
    ├── src/
    │   ├── components/      # React components
    │   ├── pages/           # Page components
    │   ├── services/        # API service layer
    │   ├── utils/           # Helper functions
    │   ├── types.ts         # TypeScript interfaces
    │   ├── App.tsx          # Main app component
    │   └── main.tsx         # Entry point
    ├── package.json
    ├── vite.config.ts
    └── tailwind.config.js

Installation & Setup

Prerequisites

• Python 3.8 or higher
• Node.js 18+ and npm
• Modern web browser with webcam support

Backend Setup

1. Navigate to the backend directory:

cd backend

2. Install Python dependencies:

pip install -r requirements.txt

3. Train the ML model (optional - will auto-train on first run):

python train_model.py

4. Start the FastAPI server:

python main.py

Or using uvicorn directly:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

The backend API will be available at http://localhost:8000

Frontend Setup

1. Navigate to the frontend directory:

cd frontend

2. Install dependencies:

npm install

3. Start the development server:

npm run dev

The frontend will be available at http://localhost:5173

Usage

Starting a Monitoring Session

1. Open http://localhost:5173 in your browser
2. Click "Start Monitoring Session" on the landing page
3. Allow webcam access when prompted
4. The system will begin tracking:
   • Keyboard activity (keys per minute)
   • Mouse movement (events per minute)
   • Eye metrics (blink rate, EAR)
   • Real-time CDS calculation

Understanding the Dashboard

• CDS Gauge: Shows your current Cognitive Drift Score (0-100)

  • 0-30: FOCUS (green)
  • 30-55: MILD_DRIFT (yellow)
  • 55-80: HIGH_DRIFT (orange)
  • 80-100: FATIGUE (red)

• Real-time Charts: Visualize metrics over time

• Alert Banner: Appears when HIGH_DRIFT or FATIGUE detected

• Current Metrics: Live display of all tracked values

Viewing Session History

1. Navigate to "Sessions" in the navigation menu
2. View all past sessions with statistics
3. Click "View Details" to see detailed charts and metrics

API Endpoints

Session Management

• POST /api/session/start - Start new session
• POST /api/session/metrics - Send metrics and get CDS
• POST /api/session/end - End session
• GET /api/sessions - Get all sessions
• GET /api/sessions/{session_id} - Get session details

ML Model

• GET /api/model/info - Get model information
• POST /api/model/train - Retrain the model

Machine Learning

The system uses a RandomForest classifier trained on synthetic data with the following features:

• reaction_time_ms: Response time in milliseconds
• key_rate: Keyboard activity per minute
• mouse_rate: Mouse events per minute
• blink_rate: Blinks per minute
• ear: Eye Aspect Ratio (0.15-0.35)

The model outputs:

• Predicted state: FOCUS, MILD_DRIFT, HIGH_DRIFT, or FATIGUE
• CDS score: Weighted probability score (0-100)

Development

Build for Production

Frontend:

cd frontend
npm run build

The built files will be in frontend/dist/

Running Tests

Backend:

cd backend
python train_model.py  # Verify ML pipeline

Customization

Adjusting Alert Thresholds

Edit backend/ml_service.py to modify the CDS-to-state mapping:

if cds < 30:
    state = "FOCUS"
elif cds < 55:
    state = "MILD_DRIFT"
# ... etc

Changing UI Theme

Edit frontend/tailwind.config.js to customize colors:

colors: {
  'gaming-dark': '#0a0e27',
  'gaming-purple': '#8b5cf6',
  // ... add your colors
}

Troubleshooting

Webcam not working

• Ensure browser has camera permissions
• Use HTTPS or localhost (required for getUserMedia)
• Check if another application is using the camera

Backend connection errors

• Verify backend is running on port 8000
• Check CORS settings in backend/main.py
• Ensure frontend API URL matches in frontend/src/services/api.ts

Model not loading

• Run python train_model.py to generate model files
• Check ml_models/ directory exists
• Verify sklearn version compatibility

Future Enhancements

• Integrate actual eye-tracking library (e.g., WebGazer.js)
• Add WebSocket support for lower latency
• Persistent database (SQLite/PostgreSQL)
• User authentication and profiles
• Exportable session reports (PDF)
• Mobile app support
• Customizable alert sounds

License

This project is provided as-is for educational and personal use.

Credits

Built with ❤️ for gamers who need to stay sharp during overnight sessions.