jungbae009/faceblur-anti-ai

faceblur-anti-ai is a single Python file you drop into a project to automatically blur faces in images and video for privacy reasons. The README describes the workflow simply: a YOLO person-detection model is used to find people in a frame, and for each accepted detection the module works out a conservative face or head region and applies a blur over it before any media is saved or returned. The project is shipped as one file called faceblur_anti_ai.py, with no package layout, no PyPI release, and no build configuration. You copy the file into your project and import it directly. It needs Python 3.9 or newer plus three libraries: ultralytics, opencv-python and numpy. Model weights for YOLO are not included, and the README is explicit that the user must supply weights suited to their own camera or media domain. The basic usage is to create a FaceBlurAntiAI object with a YOLO model path, then call blur_image, blur_video or blur_frame. blur_image reads an input file, applies the blur, and writes the result to an output path. blur_video does the same for a video, processing every frame and writing a new file without audio in version 0.1. blur_frame takes a single OpenCV-style frame array, always works on a copy, and returns the blurred frame along with metadata. A lot of the README is about what the module calls fail-closed behaviour: defaults that lean towards over-blurring rather than leaking a raw frame. If people are detected, every derived head region is blurred. If no person is detected, the whole frame is blurred by default. If YOLO inference fails, the default is to raise an error rather than return raw pixels; a setting can change that to a full-frame blur instead. Files are first written to a temporary location and then moved, overwriting is off by default, and input and output paths must be different. A no_person_policy of allow is available for workflows where unblurred passthrough is acceptable when no person is found. The README is honest about limits. The module only supports YOLO models, not OpenCV DNN, MediaPipe, Haar cascades or cloud APIs. Standard YOLO person models do not find exact faces, so the face region is derived from the upper part of each person box and may miss side or back views. Detection quality depends on the chosen weights, video audio is not preserved, and the module does not claim to be a legal compliance solution. It also avoids network calls, shell commands, telemetry and raw frame logging.