dvr-yolov8-detection
is designed for real-time detection of humans, animals, or objects using the YOLOv8 model and OpenCV. It supports real-time video streams via RTMP or USB webcams, includes CUDA GPU acceleration for enhanced performance, and provides options for saving detections and logging events.
- Real-time human/animal/object detection and alert system
- Runs on Python + YOLOv8 + OpenCV2
- CUDA GPU acceleration; also runs in CPU-only mode
- Supports either RTMP streams or USB webcams for real-time video sources
- Includes a loopback example and NGINX configuration example for RTMP use (i.e. OBS Studio)
- Detections can be automatically saved as images with a detection log
- Separate tool included for offline video file detections (see:
utils/
)
The project uses Python with YOLOv8 and OpenCV2 to perform object detection on either real-time video streams or batches of video files. It processes each video frame by frame, detecting humans by default (other YOLOv8-supported objects can be added as needed). The program can log detections into a separate log file, save detection frames with highlighted objects, and send out audio alerts via pyttsx3
.
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).
- 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
-
Python 3.6+ (Python 3.10.x recommended)
- Modules:
torch
ultralytics
(YOLO)opencv-python
(CUDA-enabled recommended for faster processing)numpy
pyttsx3
(for text-to-speech alerts)ffmpeg-python
(for video streams)pytz
- Modules:
-
FFmpeg
- Python 3.10.x
- Install CUDA 11.8 or higher to enable GPU-accelerated processing
- Use Miniconda or Mamba for environment management
-
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.
-
-
Set up the environment Conda/Mamba environment:
./setup_mamba_env.sh
This script creates a Conda/Mamba environment with the required dependencies.
-
Run the detection script:
./run_detection.sh
-
Clone the repository:
git clone https://github.com/FlyingFathead/dvr-yolov8-detection.git cd dvr-yolov8-detection
-
Install the required Python packages:
pip install -r requirements.txt
This ensures that all dependencies are managed through the
requirements.txt
file. -
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.
-
-
Install FFmpeg:
-
On Ubuntu:
sudo apt-get install ffmpeg
-
On Windows and macOS, follow the instructions on the FFmpeg download page.
-
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.
-
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
.
- Use the example NGINX configuration (
-
Run the detection script:
./run_detection.sh
-
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.
- Replace
-
Alternatively, configure via
config.ini
:- Set
use_webcam
totrue
. - Set
webcam_index
to your desired webcam index.
- Set
Configure various 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.
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.
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
.
Use the utils/loopback_test_unit_ffmpeg-python.py
script to set up a loopback for your RTMP stream.
-
Install
ffmpeg-python
:pip install -U ffmpeg-python
-
Run the loopback script:
python3 utils/loopback_test_unit_ffmpeg-python.py
-
Run the detection script:
python3 yolov8_live_rtmp_stream_detection.py
-
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.
Use utils/batch_humdet_yolo8_opencv2.py
to run YOLOv8 batch detection on directories of video files, suitable for faster offline use.
- 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.
- 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.
- Use a smaller model size in the
- 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
- v0.153
config.ini
& program changes:- Fallback directory (
fallback_save_dir
) - Option to create date-based sub-directories (i.e.
/detections_path/year/month/day/
)
- v0.152
- Added Conda/Mamba installer script for easier deployment
- v0.151
- Added fallbacks for directories
- v0.1501
- Fallback to non-CUDA modes if CUDA not supported
- v0.15
- Added direct USB webcam support
- Configure via
config.ini
or use--use_webcam
flag - Added
utils/get_webcams.py
to find webcam indices
- Configure via
- Added direct USB webcam support
- v0.1402
- Added detection logging to a file
- v0.1401
- Added
configparser
; now configurable viaconfig.ini
- Added
- v0.140
- Improved configuration option checks
This project is licensed under the GNU General Public License v3.0 (GPLv3).
I created this project to support non-profit and educational endeavors. While the GPLv3 license permits commercial use, I kindly ask that if you plan to use this project for commercial purposes, you consider reaching out to me. Your support and collaboration are greatly appreciated.
For inquiries, suggestions, or collaborations, please contact me at flyingfathead@protonmail.com
or visit FlyingFathead on GitHub.
Contributions are welcome! Feel free to open issues or submit pull requests on GitHub, or contact the author (me) directly at flyingfathead@protonmail.com
.
Developed by FlyingFathead, with digital ghost code contributions from ChaosWhisperer.
Star it if you like it. *;-)