How eduardovisoni/retail-cctv-analytics works
1. System purpose
This repository is a small Python client for live CCTV viewing from a Hikvision DVR, not a full backend or web app. Its current architecture is centered on consuming RTSP streams, decoding them with OpenCV/FFmpeg, and displaying them locally.
2. Physical/device boundary
The first boundary is hardware: analog cameras connect by coax to the DVR, and the DVR is the only networked device. The cameras do not have IPs or streams of their own; the DVR acts as the bridge and exposes one RTSP stream per channel.
3. External stream source
The DVR publishes video over RTSP using Hikvision’s channel URL pattern:
rtsp://user:pass@dvr-ip:554/Streaming/Channels/<N><MM>
where <N> selects the camera and <MM> selects main stream (01) or substream (02). This is the main data input to the software.
4. Configuration boundary
config.example.py is the template for local secrets and device settings, while the real config.py is excluded from git. That makes credentials and DVR-specific parameters an explicit deployment-time boundary rather than source-controlled application logic.
5. Runtime stack
The application is pure Python with OpenCV as the media layer. The README notes that opencv-python brings its own FFmpeg integration, so there is no separate FFmpeg service in the architecture.
6. Entry points / user-facing flows
There are two main scripts:
- test_dvr.py: a single-camera diagnostic/viewer
- view_all.py: a multi-camera mosaic viewer
This suggests the repo is organized around two usage paths: validating one stream versus monitoring several streams concurrently.
7. Stream handling behavior
For reliable low-latency viewing, the application forces RTSP over TCP through OPENCV_FFMPEG_CAPTURE_OPTIONS and sets a very small capture buffer. Architecturally, this is important because it changes the transport from lossy/packet-drop-prone UDP to a more stable stream delivery path.
8. Concurrency model
The multi-camera viewer uses one thread per camera stream. That isolates each VideoCapture.read() call so a slow or disconnected camera does not block the others. Each thread is responsible for its own reconnect behavior, which makes camera failures local rather than system-wide.
9. Operational dependency on DVR settings
The app is only part of the solution; the DVR must also be configured correctly. Two DVR-side settings are critical to the architecture:
- Disable Hik-Connect stream encryption
- Disable H.264+
Without these, the RTSP session may connect but the video payload will be undecodable by OpenCV/FFmpeg.
10. Failure modes and diagnostics
The README documents several decode errors that all point to the same boundary issue: the stream is either encrypted, corrupted, or delivered in an unsupported form. The recommended diagnostic path is to test the RTSP URL first with ffplay or ffprobe; if FFmpeg cannot decode it, the Python code is not the root cause.
11. Current scope vs. roadmap
The repository currently stops at live visualization. The README’s roadmap shows planned expansion toward YOLO-based person detection and alerts/counting, which would likely become a downstream processing layer after frame acquisition.
12. What to diagram
A good architecture diagram for this repo should show:
- Cameras → DVR → RTSP streams
- Python/OpenCV client consuming those streams
- Separate single-camera and multi-camera entry points
- Config file boundary for credentials/settings
- DVR-side prerequisites that affect decode success
- Optional future analytics stage after frame ingestion
Main entry points: test_dvr.py Single viewer · view_all.py Mosaic viewer · config.example.py Config template
Components 16
Device chain
Physical cameras and DVR boundary
- Cameras · Coax-connected CCTV cameras with no direct network stream
- Hikvision DVR · Networked recorder that bridges analog cameras to RTSP channels
- RTSP streams · Per-channel main and sub streams exposed by the DVR
Python client
Live viewing application and media stack
- OpenCV · Python video capture and decoding layer backed by FFmpeg
- FFmpeg · Capture backend used through OpenCV for RTSP decoding
- TCP capture · Forces RTSP over TCP and low capture buffering for stability
- Single viewer · One-camera test path for validating a stream and decode setup
test_dvr.py - Mosaic viewer · Multi-stream local viewer that combines several channels
view_all.py - Camera threads · One thread per stream to isolate blocking reads and reconnects
- Frame buffer · Small capture buffer to keep viewing low-latency
Deployment settings
Local config and DVR prerequisites
- Config template · Example local configuration for credentials and device parameters
config.example.py - Local config · Gitignored deployment-specific config with DVR credentials and options
- DVR settings · Disable Hik-Connect encryption and H.264+ for OpenCV/FFmpeg compatibility
- ffplay/ffprobe · FFmpeg-based stream checks used to distinguish stream issues from code issues
Roadmap
Planned analytics after frame ingestion
- Person detection · Planned YOLO-based detection stage after frame ingestion
- Alerts/counting · Planned downstream analytics for notifications and counting
Connections 17
- Cameras → Hikvision DVR: coax video · Analog camera feeds terminate at the DVR
- Hikvision DVR → RTSP streams: publishes · DVR exposes one RTSP stream per channel and quality
- Config template → Local config: template · Example settings are copied into a local deployment config
- Local config → Single viewer: credentials · Single-camera viewer loads local device settings
- Local config → Mosaic viewer: credentials · Multi-camera viewer loads local device settings
- DVR settings → RTSP streams: compatibility · Encryption and H.264+ settings determine whether streams decode
- RTSP streams → TCP capture: stream delivery · RTSP sessions are forced onto TCP for reliability
- TCP capture → OpenCV: capture options · OpenCV receives the RTSP capture configuration
- OpenCV → FFmpeg: backend · OpenCV relies on FFmpeg for RTSP decode
- Single viewer → OpenCV: opens stream · Diagnostic viewer reads a single channel
- Mosaic viewer → Camera threads: spawns · Multi-camera viewer uses one worker thread per stream
- Camera threads → OpenCV: reads frames · Each thread performs its own VideoCapture loop
- Camera threads → Frame buffer: latest frame · Threads update a small buffer for display
- Single viewer → ffplay/ffprobe: verify stream · Recommended when a stream fails to decode
- Mosaic viewer → ffplay/ffprobe: verify stream · Recommended when a stream fails to decode
- Frame buffer → Person detection: future input · Planned analytics would consume captured frames
- Person detection → Alerts/counting: outputs · Detection results may feed alerts and counts