vigilar/docs/architecture/subsystems/camera.md

camera

Purpose

Owns all per-camera capture, motion detection, recording, and live streaming. One worker process per configured camera pulls RTSP frames with OpenCV, runs MOG2 background-subtraction motion detection plus optional YOLO object detection, writes H.264 segments via FFmpeg, and exposes HLS for the web grid.

Key files

• vigilar/camera/manager.py — CameraManager, spawns and supervises one multiprocessing.Process per camera; polled by main supervisor via check_and_restart()
• vigilar/camera/worker.py — per-camera capture loop: RTSP read, ring buffer push, motion detect, adaptive-FPS record, YOLO classification, MQTT publish
• vigilar/camera/motion.py — MOG2-based MotionDetector
• vigilar/camera/recorder.py — FFmpeg-subprocess recorder with idle and motion modes; calls vigilar.storage.encryption.encrypt_file to produce .vge output
• vigilar/camera/ring_buffer.py — 5-second pre-motion frame buffer
• vigilar/camera/hls.py — HLS segment writer for the web grid view

MQTT topics

Subscribes: vigilar/camera/{id}/config (runtime threshold updates) Publishes:

• vigilar/camera/{id}/motion/start (MOG2 trigger, and YOLO person/vehicle detections)
• vigilar/camera/{id}/motion/end
• vigilar/camera/{id}/heartbeat
• vigilar/camera/{id}/error
• vigilar/camera/{id}/pet/detected
• vigilar/camera/{id}/wildlife/detected
• vigilar/pets/{pet_name}/location (when a known pet is identified)

Database tables

The camera subsystem does not write to SQLite directly; recording metadata and events are persisted by the events subsystem after consuming motion topics. Encrypted clips are written to disk by recorder.py.

Depends on

• storage — uses vigilar.storage.encryption.encrypt_file to seal recordings as .vge
• detection — optional YOLO detector, pet classifier, and wildlife threat classifier are loaded into the worker process

Consumed by

• events — subscribes to the whole bus and classifies motion/heartbeat/error topics into rows in events and recordings
• web — reads HLS segments for the camera grid and decrypts recordings for playback

Notes

CameraManager is the one subsystem NOT wrapped in SubsystemProcess; it owns its own child processes and is polled directly from the main supervisor loop. Adaptive FPS runs at 2 FPS idle and 30 FPS while motion is active, with a 5-second ring buffer flushed into the front of each motion clip for pre-event context. YOLO person/vehicle detections are published as extra motion/start messages with an additional detection field rather than on dedicated topics.