Configuration options are available in the config.ini file.

Note: Using CUDA-enabled OpenCV is recommended for faster operation. CUDA-enabled OpenCV2 needs to be compiled manually and installed separately, as the compiling process is highly dependent on your hardware setup. Refer to the "Troubleshooting" section for guidance and an example build script for OpenCV with CUDA.

Real-time detection also supports additional CUDA features such as CUDA video denoising (note: this feature requires CUDA and is often available only when OpenCV is compiled from source).

Configurable Features via config.ini:

• Video source (USB webcam or RTMP stream)
• Confidence threshold for detections
• Enable or disable rescaling of video frames
• CUDA-based video denoising (experimental)
• Log detection details into a separate log file
• Save frames with detected objects as image files
• Model variant selection (e.g., YOLOv8n, YOLOv8s, YOLOv8m)
• ... and other additional customizable options

🐳 For Docker setup, see the DOCKER_SETUP.md for a guide.

Setup

Requirements

• Python 3.6+ (Python 3.10.x recommended)
  • Python modules:
  • See requirements.txt
• FFmpeg
• Python 3.10.x
• If you wish to use CUDA GPU acceleration, you will need:
  • A Nvidia GPU that supports CUDA
  • Install CUDA 11.8 or higher to enable GPU-accelerated processing
• Use Miniconda or Mamba for environment management

Installation (Conda/Mamba Environments)

1. Clone the repository:

   git clone https://github.com/FlyingFathead/dvr-yolov8-detection.git
   cd dvr-yolov8-detection
   

1.2 (Install Miniconda or Anaconda if not already installed):

• Download and install Miniconda (recommended):

  • For Linux/macOS:

    wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
    bash Miniconda3-latest-Linux-x86_64.sh
    

  • For Windows, download the installer from here and follow the installation instructions.

2. Set up the environment Conda/Mamba environment:

   ./setup_mamba_env.sh
   

   This script creates a Conda/Mamba environment with the required dependencies.

3. Run the detection script:

   ./run_detection.sh
   

Installation (Manual Steps)

1. Clone the repository:

   git clone https://github.com/FlyingFathead/dvr-yolov8-detection.git
   cd dvr-yolov8-detection
   

2. Install the required Python packages:

   pip install -r requirements.txt
   

   This ensures that all dependencies are managed through the requirements.txt file.

3. Install OpenCV:

   • For a full version with GUI support (recommended):

     pip install opencv-python
     

   • For CUDA-enabled OpenCV, you need to build it from source. Refer to the OpenCV documentation or check the build script for guidance.

4. Install FFmpeg:

   • On Ubuntu:

     sudo apt-get install ffmpeg
     

   • On Windows and macOS, follow the instructions on the FFmpeg download page.

Real-Time Detection

This project supports real-time object detection from RTMP streams or USB webcams using YOLOv8. The provided run_detection.sh script ensures the detection script runs continuously, automatically restarting if it exits.

(New in v0.155): The real-time detection now comes with a mini web server running on Flask that enables you to run the detection framework in your browser by default when headless and enable_webserver are set to true. This will make headless deployment very easy. Note that it listens on 0.0.0.0:5000 by default, which you might want to change (i.e. to 127.0.0.1:5000) for safety reasons.

Usage

1. For RTMP Streams:

• Set up your RTMP server:

  • Use the example NGINX configuration (example-nginx.conf) to set up an RTMP loopback server.
  • Ensure your streaming client (e.g., OBS Studio) is set to stream to rtmp://127.0.0.1:1935/live.

• Run the detection script:

  ./run_detection.sh
  

2. For USB Webcams:

• Run the detection script with the --use_webcam option:

  python3 yolov8_live_rtmp_stream_detection.py --use_webcam true
  

• Specify webcam index (if needed):

  python3 yolov8_live_rtmp_stream_detection.py --use_webcam true --webcam_index <number>
  

  • Replace <number> with the index number of your webcam.
  • Use the utils/get_webcams.py tool to find available webcams and their index numbers.

• Alternatively, configure via config.ini:

  • Set use_webcam to true.
  • Set webcam_index to your desired webcam index.

Configuration

Running Headless / As A Web Server

Due to Docker being a popular install option, you can run the program headless and with a Flask based mini-web server included. Compared to the regular GUI verison, there is likely a small framerate dip and latency in the output, but other than that, the functionality is not too far off from the GUI variant.

In headless Docker installs, make sure that headless and enable_webserver are both set to true.

Editing Program Configuration

You can configure the program's parameters by editing the config.ini file. This allows you to set program parameters such as the input source, input stream address, output directory, confidence threshold, model variant, stream URL, and more.

(For RTMP Sources) Example NGINX Configuration

An example NGINX configuration is provided in example-nginx.conf. This config sets up an RTMP server that listens on 127.0.0.1:1935 and allows local clients to publish and play streams.

(For RTMP Sources) RTMP Loopback Script

To stream and process the video in real-time, use the ffmpeg_video_stream_loopback.sh script. Ensure your streaming client (e.g., OBS Studio) is set to stream to rtmp://127.0.0.1:1935/live.

(For RTMP Sources) Windows Users / Platform-Agnostic Loopback for RTMP

Use the utils/loopback_test_unit_ffmpeg-python.py script to set up a loopback for your RTMP stream.

1. Install ffmpeg-python:

   pip install -U ffmpeg-python
   

2. Run the loopback script:

   python3 utils/loopback_test_unit_ffmpeg-python.py
   

3. Run the detection script:

   python3 yolov8_live_rtmp_stream_detection.py
   

4. Configure your streaming client to stream to:

   rtmp://127.0.0.1:1935/live
   

Note: Using NGINX as a loopback method is highly recommended for stability.

Setup separate mask areas/zones (minimum confidence)

Mask detection areas: this is highly useful where detections need to be above certain threshold to be saved and registered with separate alerts. You can use the method to i.e. increase thresholds on the input image's detection areas to avoid false positives.

The masking can be done with a GUI rectangle painter util under ./utils/region_masker.py, i.e.:

 python ./utils/region_masker.py

This will run a region masking utility that enables you to set special zones with a GUI interface (no headless mode yet!) and have it saved into a file (./data/ignore_zones.json by default; see config.ini on how to utilize the feature)

Offline Batch Detection Utility

Use utils/batch_humdet_yolo8_opencv2.py to run YOLOv8 batch detection on directories of video files, suitable for faster offline use.

Troubleshooting

RTMP Loopback Issues

• If for whatever reason the loopback doesn't seem working, you can create a test stream with i.e. utils/test_stream_generator.py. When ran, the script generates synthetic video frames and streams them to your RTMP server using FFmpeg as a subprocess, enabling you to try out if your loopback works.
• Run the test_stream_generator.py and keep it running in the background, then try to first use VLC to connect to your stream (VLC: Media -> Open Network Stream -> rtmp://127.0.0.1:1935/live/stream). If this works, the main detection script should work as well.

CUDA Not Found

• Ensure that you have all necessary modules installed with CUDA enabled.
• You may need to compile OpenCV from source to enable CUDA support.
• Refer i.e. to the OpenCV w/ CUDA build script for Ubuntu 22.04LTS or the 24.04LTS build script for some degree of guidance.
• Verify CUDA support by checking if the program detects your GPU on startup.

CUDA Installation

• See: CUDA Setup Guide

Running Without a CUDA-Capable GPU

• The program can run in CPU-only mode, though performance may be slower.
• To improve performance:
  • Use a smaller model size in the config.ini.
  • Adjust rescale and frame rate options.
  • Reduce the resolution and frame rate from the video source.

TODO

• WIP: Separate watchdog(s) for stream stability monitoring
  • automated restarts if and when needed
• Implement more error handling for edge cases
• Refactor code for improved modularity
• Add setup scripts for easier deployment
• Implement threshold settings for alerts (e.g., number of detections within a time frame)
• Add hooks for sending detections to web servers or APIs

Changelog

• 0.18.1
  • Docker / CI: tightened NumPy version handling in the Docker build to avoid dependency breakage
  • GitHub Action