An interactive command-line tool that automatically detects, clusters, and blurs faces in videos.
fiatcode
236e0d2ff2
- Add YuNet face detector as alternative option (built into OpenCV) - Add multi-scale detection (1.0x + 1.5x) to catch faces at different distances - Add NMS to remove duplicate detections from multi-scale - Move frame interval and clustering settings to advanced options - Increase default blur padding from 25% to 40% - Change default frame interval from 30 to 15 - Change default confidence threshold from 0.7 to 0.8 - Add limitations section to README (extreme angles, small faces, motion blur) - Require scikit-learn>=1.3.0 for HDBSCAN support |
||
|---|---|---|
| src/faceblur | ||
| .gitignore | ||
| .python-version | ||
| DEV_GUIDE.md | ||
| main.py | ||
| pyproject.toml | ||
| README.md | ||
| uv.lock | ||
PyFaceBlur
An interactive command-line tool that automatically detects, clusters, and blurs faces in videos. It guides you through a simple step-by-step process to extract frames, group people by facial identity, select who you want to blur, and re-encode the video.
Features
- Interactive CLI: Built with
richandquestionaryfor a clean, prompt-based UX including file path auto-completion. - Accurate Face Recognition: Uses UniFace (RetinaFace detection + ArcFace 512-dim neural embeddings via ONNX Runtime) to accurately re-identify the same person across a video.
- DBSCAN Clustering: Automatically groups identical faces into "clusters" using Cosine similarity.
- Hardware-Accelerated Encoding: Automatically detects and leverages GPU encoders like
av1_vaapi,hevc_vaapi,h264_vaapi,h264_nvenc, and more via FFmpeg. - Visual Face Selection: Extracts one high-quality thumbnail per detected person and opens your system's file explorer so you can easily check boxes for who to blur.
- Multiple Blur Styles: Choose from Gaussian, Pixelate, Blackout, Elliptical, or Median blur methods.
- Smooth Interpolation: Bounding boxes are linearly interpolated between sampled keyframes and held static when faces exit/enter, ensuring smooth blurring without split-second exposures.
Requirements
- Python 3.11+
- uv for fast dependency management
ffmpeginstalled and available in your system$PATH(for frame extraction and re-encoding)
Setup
# Clone the repository and navigate to the project directory
cd py-faceblur
# Sync dependencies using uv
uv sync
Usage
Run the interactive wizard:
uv run pyfaceblur
The Pipeline
- Input: You provide the path to your video and the frame sampling interval (e.g., sample every 30th frame).
- Processing: The app uses FFmpeg to extract frames, runs RetinaFace to find all faces, and generates ArcFace embeddings.
- Clustering: DBSCAN groups the embeddings to identify unique individuals.
- Selection: The app saves a thumbnail of each person to a temporary folder, opens it, and asks you to select which people to blur using interactive checkboxes.
- Encoding: The app finds the best available video encoder on your system, applies the chosen blur method to the selected faces, interpolates their movement, and generates a new
*_blurred.mp4video.
Advanced / Legacy CLI
The original proof-of-concept command-line interface is also still available for purely extracting and debugging the clustering outputs into an output folder.
uv run pyfaceblur-legacy detect --video input.mp4 --output ./output --interval 30 --confidence 0.7
Limitations
- Extreme face angles: Faces viewed from extreme angles (e.g., strong profile views, looking up/down) may not be detected or may be clustered as separate identities. For best results, use videos where faces are mostly front-facing or at moderate angles.
- Small/distant faces: Very small faces (below 50 pixels) may not be reliably detected or produce accurate embeddings for clustering.
- Rapid motion blur: Fast head movements causing motion blur can affect detection accuracy.