I built SmartAttendanceSystem as a lightweight, face-recognition based event logging system. A live camera or pre-recorded video stream detects and recognizes faces, logging sightings (both known individuals and unknown visitors) directly into a shared SQLite database tagged by location (Entrance, Exit, Room 101, Hallway).
This project isn’t fully complete yet. The backend architecture and core recognition pipeline are almost done, but I still need to run more stress tests and edge-case testing under varying lighting and multiple camera streams before it is fully finished. I wanted to log it here in my projects to track its ongoing progress.
Each logged event captures metadata and saves a short .mp4 video clip around the trigger timestamp for visual audit trails.
Performance benchmarks
| Metric | SmartAttendanceSystem | Traditional Cloud Vision APIs |
|---|---|---|
| Inference latency | < 28ms / frame (GPU) / ~85ms (CPU) | 300 to 800ms HTTP roundtrip |
| Model accuracy | High cosine precision via ArcFace (buffalo_l) |
Variable per vendor |
| Event storage write | Sub-millisecond SQLite WAL transactions | Network dependent |
| Bandwidth usage | Local processing (zero cloud video upload) | Continuous high bitrate video stream |
| Clip recording | Ring buffer with configurable pre/post-roll | Full continuous recording storage |
Technical details
| Item | Details |
|---|---|
| Detection model | SCRFD (Sample and Computation Redistribution Face Detection) |
| Recognition model | ArcFace via InsightFace buffalo_l embedding pipeline |
| Backend API | FastAPI, Uvicorn, and Python 3.11+ via uv |
| Database | SQLite with Write-Ahead Logging (WAL) and schema migrations |
| Dashboard | Static vanilla JavaScript dashboard served directly from FastAPI |
| Hardware support | Automatic GPU acceleration (CUDA) with seamless CPU fallback |
Architecture & subsystems
- Enrollment pipeline: Processes images from a local dataset (
Person_Name/*.jpg), generates normalized embeddings with ArcFace, and writes averaged person vectors toembeddings_per_person.json. - Live recognizer (
face_recognition.py): Real-time OpenCV loop with on-screen HUD, cosine similarity matching, automatic heartbeats, and per-event clip recording. - Backend-authoritative settings: Match thresholds, cooldown durations, and liveness checks are stored per-location in the database and can be hot-reloaded via API or keyboard shortcuts without restarting the camera process.
- Backlog processor (
process_recording.py): Ingests pre-recorded surveillance clips, logging historical sightings with exact video-timeline timestamps and an interactive scrubber. - Basic liveness verification: Motion-heuristic check analyzing micro-movements across pre-roll frames to reject static photo spoofing.
- Data retention manager (
cleanup.py): Automated retention job pruning event records and associated.mp4video clips older than a configured threshold.
FAQ
How does the system handle unknown visitors?
When an unrecognized face is detected, it logs an event as Unknown, saves a short .mp4 video clip to snapshots/<location>/<date>/, and enforces a shared per-location cooldown to prevent database flooding.
Can multiple cameras log to the same database?
Yes. Multiple instances can run concurrently across different locations (e.g. --location "Entrance", --location "Room 101"). All instances share the SQLite database and send heartbeats visible in the web dashboard.
Why use local embeddings over cloud APIs?
Processing locally with InsightFace keeps video streams private, eliminates recurring API costs, and allows the system to operate offline on local networks.