Yolo Privacy Blur with GUI

Blur license plates and/or faces in photos and videos using Ultralytics YOLO + OpenCV. This fork provides a YAML-first batch workflow and a GUI designed for repeatable bulk processing.

Credits / Upstream

This project is based on MengWoods/video-privacy-blur:

• https://github.com/MengWoods/video-privacy-blur

What’s improved in this fork

• YAML-first config (config.yaml) for all settings (no long CLI flags).
• Batch folder scan with photo / video modes.
• GUI:
  • Select input folders.
  • Browse files in the selected folder.
  • Click a file to view the original preview.
  • For videos, drag Start (s) to show the original frame at that timestamp.
  • Press Preview to show a processed 3-second clip (t → t+3).
  • Press Save to process and save only the selected file.
• Video audio/encoding via FFmpeg (keep original audio, or re-encode with codec/crf/preset).
• Performance: YOLO every N frames + optical-flow tracking between detections.
• Progress UI: Overall (files) + Current file (image / video frames).

Requirements

• Python >= 3.9
• Python packages: ultralytics, opencv-python, numpy, PyYAML, Pillow, ttkbootstrap
• FFmpeg: required if you want to keep original audio and control video encoding.
  • Without FFmpeg, video output is written by OpenCV and is typically silent.

Models

To run the tool, you need to download the following YOLOv8 models and place them in the models/ folder:

• Face detection model: yolov8m-face.pt

  • Downloaded from akanametov/yolo-face
  • Used to detect human faces with YOLOv8.
  • Can be replaced with any YOLOv8 face model you prefer.

• License plate detection model: license_plate_detector.pt

  • Downloaded from Muhammad-Zeerak-Khan/Automatic-License-Plate-Recognition-using-YOLOv8
  • Used to detect vehicle license plates with YOLOv8.
  • Can be swapped with any YOLOv8 license plate detector model you have trained or obtained.

Install

# inside this repo
pip install -r requirements.txt
pip install -e .

Quick start

GUI

privacy-blur-gui

CLI (batch from YAML)

cp config.example.yaml config.yaml
privacy-blur --config config.yaml

Dry run (no files written):

privacy-blur --config config.yaml --dry-run

Configuration (config.yaml)

Use config.example.yaml as a template. Key fields:

• mode: photo or video
• input_dirs: list of {path, enabled}
• recursive: scan subfolders
• preserve_structure: keep subfolders under output/
• output_dir_name: output folder name (default output)

processing (detection + blur):

• device: auto|cpu|cuda|mps
• imgsz: YOLO input size
• conf: confidence threshold
• iou_thresh: NMS IoU threshold
• detect_interval: run YOLO every N frames (videos)
• scale: expand/shrink boxes (<1 shrink, >1 expand)
• blur_plates, blur_faces: targets
• plate_weights, face_yolo_weights: YOLO weight paths
• method: gaussian|pixelate
• blur_strength, pixelate_blocks: blur intensity

ffmpeg (video mux/encode):

• enabled: auto|on|off
• path: ffmpeg binary (default ffmpeg)
• audio: copy|none
• codec: copy or e.g. libx264
• crf, preset: encoding quality/speed (used when codec != copy)

Tips

• If blur coverage is too large/small: adjust processing.scale.
• For faster video processing: increase processing.detect_interval and/or reduce processing.imgsz.