Leo Thakur
Back to projects

AI camera system

Watches live camera feeds, detects people, cars, and animals, recognizes faces I've enrolled, and sends alerts. It has a desktop app, a web dashboard, and a phone app.

Follow a frame

Every frame goes through the same steps. Most stop at the motion check, since there's no point running YOLO on a frame where nothing moved. Click a step for details.

Camera

The actual loop, trimmed a bit. Face recognition runs every frame until it identifies someone, then every fifth frame.

src/camera/manager.py

has_motion = (
    not self._app_cfg.motion.enabled
    or self._motion.detect(frame)
    or frames_since_detection >= max_skip
)
if has_motion:
    detections = self._detector.detect(frame)
    tracks = self._tracker.update(detections)

    # Eager mode: run every frame until a face is confirmed,
    # then throttle to every N frames for updates.
    for track in tracks:
        if track.class_id != 0:
            continue
        unconfirmed = track.face_id is None
        due = cnt % interval == 0
        if unconfirmed or due:
            self._run_face_recognition(frame, track)

    event_ids = self._persist_tracks(frame, tracks)

Numbers

~3,900lines of Python
~1,800lines of Dart in the Flutter app
19REST API endpoints
9object classes it watches for
~3 msper frame for YOLOv8n on the laptop's CPU
0.62minimum confidence to count a detection
0.55face-match tolerance (lower is stricter)
60 scooldown before re-alerting on the same person

Per-frame speed is from my detector notes, on an Intel i5-1135G7.

The API

Everything goes through a FastAPI server on port 8000. FastAPI generates docs at /docs where you can try each endpoint.

MethodPathWhat it does
GET/api/camerasList cameras
GET/api/cameras/{id}/statusFPS, frame count, active tracks, errors
GET/api/cameras/{id}/streamLive MJPEG video
GET/api/eventsSearch event history
GET/api/events/{id}One event
GET/api/events/streamLive event feed (server-sent events)
GET/api/alertsList alerts
POST/api/alerts/{id}/acknowledgeMark an alert as seen
GET/api/statsTotals for the dashboard
GET/api/facesList enrolled people
GET/api/faces/{id}One person
POST/api/facesEnroll a new person from a photo
DELETE/api/faces/{id}Remove a person
GET/api/faces/{id}/imageEnrollment photo
GET/api/export/events.csvDownload events as CSV
GET/api/export/alerts.csvDownload alerts as CSV
GET/api/system/statusIs the AI running?
POST/api/system/startStart AI detection
POST/api/system/stopStop AI detection

Design decisions

Speed

Skip frames where nothing moves

Running YOLO on an empty hallway 15 times a second is a waste. A cheap motion check goes first. It's set to be oversensitive, since missing something real is worse than one wasted inference.

Accuracy

Look for faces inside people

Face recognition only looks inside a detected person's box, shrunk to about 300 pixels. Faster, and no false matches on posters or TVs.

Hardware

No GPU required

It runs on a normal laptop: YOLOv8 nano, the HOG face detector, and CPU-only PyTorch.

Control

AI starts off

Cameras connect at launch, but detection stays off until you press Start in the desktop app or the phone app calls POST /api/system/start.