Steps
- Install peepshow + ultralytics
YOLO11 ships in the Python `ultralytics` package.
npm install -g peepshow pip install ultralytics - Run with --require-objects
Comma-separated YOLO11 class names. Frames without ≥1 match are dropped.
peepshow ./dashcam.mp4 --strategy scene --max 60 --require-objects person,car,truck - Combine with motion-only preset
Scene-detect first, then YOLO filter. Best signal-to-noise.
peepshow ./cctv.mp4 --strategy scene --max 100 --dedup perceptual --require-objects person - Inspect the result
Top-level `objectFilter` summary shows frames scanned vs kept.
peepshow ./dashcam.mp4 --require-objects car --emit json | jq '.objectFilter'
Why it works
YOLO11 (Ultralytics) is the current default object detector — fast, accurate, 80 COCO classes out of the box. peepshow auto-detects the `yolo` CLI on PATH and shells out per-frame. Class names match COCO (`person`, `bicycle`, `car`, `motorcycle`, `airplane`, `bus`, `train`, `truck`, `boat`, ...). Frames lacking the requested classes are deleted from the output dir; the `objectFilter` summary reports scanned/kept/dropped counts. Soft-fails the whole pass if `yolo` is missing.
When it helps
- CCTV monitoring — only flag frames with people, vehicles, or animals.
- Dashcam incident review — only frames with cars or pedestrians.
- Sport analysis — only frames with athletes (`person`).
- Wildlife / nature footage — only frames with detected animals (`bird`, `cat`, `dog`, `horse`, `sheep`, `cow`, `elephant`, `bear`, `zebra`, `giraffe`).
Pitfalls
- Requires `pip install ultralytics`. Soft-fails with hint if missing.
- Per-frame YOLO inference is GPU-accelerated on supported hardware but CPU-only on others — long videos may take minutes.
- Class names must match COCO exactly (case-insensitive). Custom-trained models need a different setup.