FaceGuard

FaceGuard is a computer vision filter that automatically detects and blurs faces in video streams using OpenCV's YuNet face detection model. Perfect for privacy-conscious applications that need real-time face anonymization.

Demo

Here are some examples of FaceGuard in action:

Quick Start

The easiest way to run FaceGuard is using the provided usage script:

# Basic usage with default settings
python scripts/filter_usage.py

# Custom video input
VIDEO_INPUT="./data/your-video.mp4" python scripts/filter_usage.py

# Custom configuration
FILTER_DETECTION_CONFIDENCE_THRESHOLD=0.3 FILTER_BLUR_STRENGTH=2.0 python scripts/filter_usage.py

Environment Variables

The filter can be configured using environment variables:

Variable	Default	Description
VIDEO_INPUT	./data/video-01.mp4	Input video file path
OUTPUT_VIDEO_PATH	./output/{input_name}_blurred.mp4	Output video file path
OUTPUT_FPS	30	Output video frames per second
WEBVIS_PORT	8000	Port for Webvis visualization
FILTER_DETECTOR_NAME	yunet	Face detector. yunet is the only supported detector. The legacy haar and dnn values were retired in the OpenCV 5 upgrade (their cv2 backends were removed) and now fall back to yunet with a deprecation warning.
FILTER_BLURRER_NAME	gaussian	Blur algorithm: gaussian, box, or median
FILTER_BLUR_STRENGTH	1.0	Blur intensity
FILTER_DETECTION_CONFIDENCE_THRESHOLD	0.25	Minimum confidence for face detection
FILTER_DEBUG	False	Enable debug logging
FILTER_FORWARD_UPSTREAM_DATA	True	Forward data from upstream filters
FILTER_INCLUDE_FACE_COORDINATES	True	Include face coordinates in frame data
FILTER_YUNET_SHA256	unset	Optional SHA-256 (hex) of the YuNet ONNX. When set, the downloaded or cached file is verified before use; mismatch raises and removes the file so the next attempt re-downloads.

Viewing Results

After running the filter, you can view the results at:

• Webvis: http://localhost:8000 - Real-time video stream
• Output Video: Check the ./output/ directory for the processed video file

Documentation

For detailed information about configuration options, performance tuning, and advanced usage, see the comprehensive documentation.

Features

• Real-time Face Detection: Uses OpenCV's YuNet model for accurate face detection
• Configurable Blurring: Adjustable blur strength and detection sensitivity
• Rich Metadata: Face coordinates, confidence scores, and detection details
• Environment Variable Configuration: No command-line arguments needed
• Upstream Data Forwarding: Passes through data from other filters
• Debug Mode: Optional logging for development and troubleshooting

Install

To install the filter and its dependencies:

# Create and activate virtual environment
virtualenv venv
source venv/bin/activate

# Install the filter
make install

Run locally

To run the filter locally:

make run

Then navigate to http://localhost:8000 to see the video stream.

Run in Docker

Build and run the filter in Docker:

# Build the Docker image
make build-image

# Run the filter
make run-image

Navigate to http://localhost:8000 to view the video stream.

Testing

Run the test suite:

make test