🎯 SnapRoll | AI-Powered Attendance System

One photo. One voice clip. Zero roll calls.

SnapRoll is a production-grade, AI-driven classroom management system that automates attendance logging using facial recognition and voice biometric verification. It replaces tedious manual roll calls with automated photo and audio scanning, logging timestamped records in real time.

🚀 Live Demo · 📖 Quickstart · 🗄️ Database Setup · 🐛 Report Bug

---

📋 Table of Contents

• Key Features
• System Architecture
• Tech Stack
• Project Directory Structure
• Database Setup & Schema
• Quickstart & Installation
• Environment Configuration
• Production Deployment
• Troubleshooting & FAQ
• Future Roadmap
• Contributing
• License

---

✨ Key Features

📸 Multi-Angle AI Face Attendance

• Parallel Scanning: Processes single or multiple classroom photos simultaneously.
• Biometric Embeddings: Extracts 128-dimensional facial embeddings using dlib HOG face detection and 68-point shape landmark alignment.
• SVM Classifier: Uses a Support Vector Machine (SVM) classifier trained dynamically on enrolled student profiles for instant multi-face verification.

🎙️ Speaker Segmentation Voice Attendance

• Audio Processing: Captures classroom speech clips directly via browser microphone input.
• Speaker Diarization & Embeddings: Uses librosa for voice segment processing and Resemblyzer for generating 256-dimensional neural voice embeddings.
• Cosine Distance Matching: Matches audio signatures against enrolled voice profiles using cosine similarity metrics with automated thresholding.

📚 Subject & Auto-Enrollment System

• Instant Join Links & QR Codes: Auto-generates shareable links and downloadable QR codes (powered by segno) for seamless student self-enrollment.
• Role Routing: Role-aware interface for Teachers (class management, AI scans, logs) and Students (Face ID login, subject dashboard, personal attendance history).

📊 Interactive Analytics & Export

• Roster Inspection: Interactive summary table allowing teachers to click any session row to inspect complete student attendance rosters.
• CSV Export: One-click report download with formatted timestamps for administration compliance.

---

🏗 System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                            STREAMLIT FRONTEND LAYER                         │
│       Role-Aware UI (Home Router → Teacher Dashboard / Student Portal)      │
│         Browser Camera Capture · Audio Recorder · Interactive Tables        │
└───────────────────────┬─────────────────────────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            AI PIPELINE LAYER                                │
│                                                                             │
│   📷 Face Pipeline                       🎙️ Voice Pipeline                 │
│   ├── dlib HOG Face Detector             ├── librosa Audio Segmentation     │
│   ├── 68-Point Shape Predictor           ├── Resemblyzer Voice Embedder     │
│   ├── 128-d Embedding Extraction         ├── 256-d Vector Normalization     │
│   └── scikit-learn SVM Classification    └── Cosine Similarity Matcher      │
└───────────────────────┬─────────────────────────────────────────────────────┘
                        │ Supabase Client (REST / Realtime)
                        ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                             DATA LAYER (Supabase)                           │
│                PostgreSQL Relational DB (RLS Configured)                    │
│     teachers · students · subjects · subject_students · attendance_logs     │
└─────────────────────────────────────────────────────────────────────────────┘

---

🛠 Tech Stack

Domain	Technology	Description
Core Framework	Python 3.10+	Primary language runtime
Web UI	Streamlit	Responsive single-page web framework
Face Biometrics	dlib, face_recognition_models	HOG face detector & 128-d facial landmark extractors
Voice Biometrics	Resemblyzer, librosa, torch	Voice encoder & audio segmentation engine
Machine Learning	scikit-learn, numpy, pandas	SVM classification and tabular dataset manipulation
Authentication	bcrypt	Hashed password verification for instructor accounts
Database	Supabase (PostgreSQL)	Cloud database layer with REST endpoint access
QR Code Engine	segno	Vector QR code generator for subject join links

---

📁 Project Directory Structure

snaproll-ai-powered-attendance-system/
├── .streamlit/
│   └── secrets.toml                   # Streamlit credentials (SUPABASE_URL, SUPABASE_KEY)
├── src/
│   ├── components/                    # UI Components & Modal Dialogs
│   │   ├── dialog_add_photos.py       # Camera & image file uploader
│   │   ├── dialog_attendance_result.py# Attendance report preview modal
│   │   ├── dialog_auto_enroll.py      # QR / link quick enrollment handler
│   │   ├── dialog_create_subject.py   # Subject creation form
│   │   ├── dialog_enroll.py          # Manual subject code enrollment modal
│   │   ├── dialog_share_subject.py   # QR code generator & link launcher
│   │   ├── dialog_voice_attendance.py # Voice recording & recognition modal
│   │   ├── footer.py                  # Page footer layout
│   │   ├── header.py                  # Top banner header component
│   │   └── subject_card.py            # Subject statistics card widget
│   ├── database/
│   │   ├── config.py                  # Supabase client instantiation
│   │   └── db.py                      # Data access layer (CRUD queries & joins)
│   ├── pipelines/
│   │   ├── face_pipeline.py           # Face detection, 128-d embedding & SVM model
│   │   └── voice_pipeline.py          # Voice segmentation & Resemblyzer embedding match
│   ├── screens/
│   │   ├── home_screen.py             # Landing page / portal selection
│   │   ├── student_screen.py          # Student dashboard & Face ID login flow
│   │   └── teacher_screen.py          # Teacher dashboard, attendance session & records
│   └── ui/
│       └── base_layout.py             # CSS styling injection & typography config
├── assets/
│   └── SnapRoll_Logo.ico             # Application icon asset
├── app.py                             # Main entry point & session state router
├── requirements.txt                   # Dependency manifest
└── README.md                          # Production documentation

---

⚙️ Quickstart & Installation

Prerequisites

• Python: Version 3.10 or higher
• Git: Installed on system path
• Compiler Tools: C++ build tools (for dlib compilation if binary wheel is not available)

Step 1: Clone Repository

git clone https://github.com/Vaibhav1o1/snaproll-ai-powered-attendance-system.git
cd snaproll-ai-powered-attendance-system

Step 2: Set Up Virtual Environment

Windows (PowerShell):

python -m venv venv
.\venv\Scripts\Activate.ps1

macOS / Linux:

python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install --upgrade pip
pip install -r requirements.txt

---

🔑 Environment Configuration

Create a .streamlit/secrets.toml file inside the root folder:

# .streamlit/secrets.toml
SUPABASE_URL = "https://your-project-id.supabase.co"
SUPABASE_KEY = "your-supabase-anon-key"

(Alternatively, you can create a .env file with SUPABASE_URL and SUPABASE_KEY variables).

Launching Application

streamlit run app.py

The application will start locally at http://localhost:8501.

---

🚀 Production Deployment

Deploying to Streamlit Community Cloud

1. Push your latest codebase to GitHub (ensure .streamlit/secrets.toml is listed in .gitignore).
2. Log into share.streamlit.io with GitHub.
3. Select New App → Select your repository, set branch to main, and set main file path to app.py.
4. Open Advanced Settings → Secrets and paste your credentials:

   SUPABASE_URL = "https://your-project-id.supabase.co"
   SUPABASE_KEY = "your-supabase-anon-key"

5. Click Deploy!

---

🔭 Future Roadmap

• 📱 Native Mobile Interface: Responsive mobile-first view optimized for smartphone cameras.
• 📈 Defaulter Analytics: Automated risk indicator reports for students falling below minimum attendance thresholds.
• 🔔 Webhooks & Email Alerts: Real-time notification dispatch via SendGrid/Twilio.
• 🧠 Multi-Angle Face Alignment: Integration of RetinaFace for improved recognition under low lighting.

---

🤝 Contributing

Contributions are welcome! Follow these steps:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/amazing-feature.
3. Commit your changes: git commit -m 'Add amazing feature'.
4. Push to branch: git push origin feature/amazing-feature.
5. Open a Pull Request.

---

📜 License

Distributed under the MIT License. See LICENSE for more information.

** Built for Modern Educators**