CamReview

A private, local CLI for finding and reviewing motion in existing security-camera recordings.

Key Features • Installation • Usage • Documentation • Support • Contributing • License

CamReview retrospectively scans timestamped MKV, MP4, MOV, and AVI files, groups motion into events, and writes portable JSON, CSV, and text reports. Classification and clip extraction are opt-in. It is not an NVR, service, scheduler, web application, or database.

Footage and decoded frames remain on the local machine. CamReview has no telemetry and uses no cloud API; Ultralytics may download a model only when classification is requested and the configured model is not already cached.

Key Features

• Preserves motion continuity across short recording files without loading a day into memory.
• Uses filename wall-clock times and presentation timestamps to build an accurate timeline.
• Supports local disks, Windows mapped drives and UNC paths, and mounted SMB/CIFS shares.
• Produces atomic, deterministic JSON, CSV, and text reports with gaps and processing issues.
• Optionally classifies moving COCO objects with Ultralytics YOLO on CPU or NVIDIA CUDA.
• Copies source recordings or creates event-sized clips with FFmpeg without changing originals.
• Offers CPU-first decoding plus tested automatic or explicit hardware-decoder selection.

Installation

Python 3.11 or newer is required:

python -m pip install camreview

Activate the environment using the command for your shell. FFmpeg is additionally required for event-sized extraction. See Installation for platform-specific steps, optional classification dependencies, and verification.

Usage

Recordings must use <camera>_YYYY-MM-DD_HH-MM-SS.<ext> filenames. Inspect a directory, then scan one camera-day:

camreview inspect /path/to/recordings
camreview scan /path/to/recordings --time all

The current directory receives canonical CAMERA_DATE_motion.json plus CSV and text reports. Start with Getting started for a complete first run.

Documentation

Full documentation lives in docs/: Getting started · Installation · Usage · Command reference · Configuration · Architecture · Report schema · Automation · Troubleshooting

Support

File an issue.

Contributing

Contributions welcome. See the org-wide Contributing Guide and Code of Conduct.

License

MIT — see LICENSE.md.