Skip to content

README.md

Latest commit

 

History

History
215 lines (160 loc) · 8.33 KB

README.md

File metadata and controls

215 lines (160 loc) · 8.33 KB
Raw

🎓 ClassSense — AI-Powered Attendance System

Revolutionizing classroom attendance with Face Recognition and Voice Authentication

Live App Landing Page License Python

📌 Overview

ClassSense is an AI-powered attendance system that uses face recognition and voice biometrics to automate classroom attendance. Teachers can snap a photo of their classroom or record audio, and the system automatically identifies enrolled students using trained ML models.

Why ClassSense?

Traditional attendance methods are slow, error-prone, and easy to game. ClassSense solves this with:

  • Face Recognition — Upload classroom photos, AI identifies every student instantly
  • Voice Authentication — Students say "I am present," and the system matches their voice
  • QR-Based Enrollment — Students scan a QR code to join a class in seconds
  • Dual Portals — Separate dashboards for teachers and students

🧠 How It Works

Face Recognition Pipeline

Classroom Photo → dlib Face Detector → 128-D Face Embeddings → SVM Classifier → Student Identity
  1. Detection: dlib's HOG-based frontal face detector locates all faces in the image
  2. Embedding: Each face is converted to a 128-dimensional descriptor using dlib's ResNet-based face recognition model
  3. Classification: A Linear SVM (with class balancing) trained on enrolled students' embeddings predicts identity
  4. Thresholding: L2 distance threshold of 0.6 rejects unknown faces to minimize false positives

Voice Authentication Pipeline

Audio Recording → 16kHz Resampling → VAD Segmentation → Resemblyzer Embeddings → Cosine Similarity → Speaker Match
  1. Preprocessing: Audio is resampled to 16kHz using librosa
  2. Segmentation: Voice Activity Detection (VAD) with top_db=30 splits audio into individual speech segments
  3. Embedding: Each segment is encoded into a speaker embedding using Resemblyzer's pretrained encoder
  4. Matching: Cosine similarity against stored embeddings with a threshold of 0.65 identifies the speaker

✨ Features

👨‍🏫 Teacher Portal

  • AI Face Attendance — Upload/capture multiple classroom photos, run face analysis across all images
  • Voice Roll-Call — Record classroom audio for voice-based attendance
  • Subject Management — Create subjects with unique codes and sections
  • QR Code Sharing — Generate QR codes and shareable links for student enrollment
  • Attendance Records — View historical attendance with per-session statistics

👨‍🎓 Student Portal

  • FaceID Login — No passwords needed; students log in with their face
  • Voice Enrollment — Optional voice profile registration for voice-based attendance
  • Subject Enrollment — Join classes via subject code or QR scan
  • Attendance Tracking — View personal attendance stats per subject

🔐 Authentication

  • Students: Biometric login via face recognition (camera-based)
  • Teachers: Traditional username/password with bcrypt hashing

🛠️ Tech Stack

Component Technology
Frontend Streamlit
Backend/Database Supabase (PostgreSQL)
Face Detection dlib (HOG + CNN)
Face Embeddings dlib ResNet (128-D descriptors)
Face Classification scikit-learn SVM (Linear, class-balanced)
Voice Embeddings Resemblyzer (GE2E pretrained encoder)
Audio Processing librosa (resampling, VAD, segmentation)
QR Code Generation segno
Password Hashing bcrypt
Deployment Streamlit Cloud

📁 Project Structure

ClassSense/
├── app.py                          # Main entry point
├── requirements.txt                # Python dependencies
├── .gitignore
│
└── src/
    ├── components/                 # UI Components
    │   ├── header.py               # App header with logo
    │   ├── footer.py               # App footer
    │   ├── subject_card.py         # Subject display card
    │   ├── dialog_add_photo.py     # Camera/upload dialog
    │   ├── dialog_attendance_results.py  # Results review dialog
    │   ├── dialog_create_subject.py     # New subject dialog
    │   ├── dialog_enroll.py        # Student enrollment dialog
    │   ├── dialog_auto_enroll.py   # QR-based auto enrollment
    │   ├── dialog_share_subject.py # QR code sharing dialog
    │   └── dialog_voice_attendance.py   # Voice attendance dialog
    │
    ├── database/                   # Database layer
    │   ├── config.py               # Supabase client setup
    │   └── db.py                   # All CRUD operations
    │
    ├── pipelines/                  # ML Pipelines
    │   ├── face_pipeline.py        # Face detection, embedding, SVM training & prediction
    │   └── voice_pipeline.py       # Voice embedding, speaker identification
    │
    ├── screens/                    # App screens
    │   ├── home_screen.py          # Landing/role selection
    │   ├── teacher_screen.py       # Teacher dashboard & auth
    │   └── student_screen.py       # Student dashboard & FaceID login
    │
    └── ui/                         # Styling
        └── base_layout.py          # Global CSS and theming

🚀 Getting Started

Prerequisites

  • Python 3.11
  • A Supabase project with the required tables

Installation

  1. Clone the repository

    git clone https://github.com/iam-teju/ClassSense.git
cd ClassSense

  2. Create a virtual environment

    conda create -n attendance python=3.11
conda activate attendance

  3. Install dependencies

    pip install -r requirements.txt

  4. Set up secrets

    Create .streamlit/secrets.toml:

    SUPABASE_URL = "your-supabase-url"
SUPABASE_KEY = "your-supabase-anon-key"

  5. Run the app

    streamlit run app.py

🗄️ Database Schema

The app uses the following Supabase tables:

  • teachers — teacher_id, username, password (hashed), name
  • students — student_id, name, face_embedding (128-D vector), voice_embedding
  • subjects — subject_id, subject_code, name, section, teacher_id
  • subject_students — student_id, subject_id (enrollment junction table)
  • attendance_logs — student_id, subject_id, timestamp, is_present

📊 Key Technical Decisions

Decision Rationale
SVM over KNN/deep learning Works well with small per-class samples (1 embedding per student); linear kernel is fast and interpretable
L2 distance threshold (0.6) Balances false acceptance vs false rejection for face matching
Cosine similarity for voice (0.65) Standard metric for speaker verification with embedding models
librosa VAD (top_db=30) Effectively segments individual speakers in classroom audio
Streamlit over Flask/React Rapid prototyping with built-in camera, audio, and data display widgets
Supabase over Firebase PostgreSQL with real-time capabilities; better for relational data like attendance logs

🔗 Links

👤 Author

Tejas Manoj

Built as an AI/ML portfolio project demonstrating end-to-end machine learning system design — from biometric data capture to real-time inference and deployment.

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.