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.
- LanguagePython 3.11
- DetectionYOLOv8 nano
- APIFastAPI, 19 endpoints
- Phone appFlutter
- Runs onLaptop CPU, no GPU
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
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.
| Method | Path | What it does |
|---|---|---|
| GET | /api/cameras | List cameras |
| GET | /api/cameras/{id}/status | FPS, frame count, active tracks, errors |
| GET | /api/cameras/{id}/stream | Live MJPEG video |
| GET | /api/events | Search event history |
| GET | /api/events/{id} | One event |
| GET | /api/events/stream | Live event feed (server-sent events) |
| GET | /api/alerts | List alerts |
| POST | /api/alerts/{id}/acknowledge | Mark an alert as seen |
| GET | /api/stats | Totals for the dashboard |
| GET | /api/faces | List enrolled people |
| GET | /api/faces/{id} | One person |
| POST | /api/faces | Enroll a new person from a photo |
| DELETE | /api/faces/{id} | Remove a person |
| GET | /api/faces/{id}/image | Enrollment photo |
| GET | /api/export/events.csv | Download events as CSV |
| GET | /api/export/alerts.csv | Download alerts as CSV |
| GET | /api/system/status | Is the AI running? |
| POST | /api/system/start | Start AI detection |
| POST | /api/system/stop | Stop 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.