blurfaces

Detect and censor faces in video using insightface and ffmpeg.

Samples

Input	Blackout (default)
ross.mp4	blackout_all.mp4

Blur	Pixel
blur_one.mp4	pixel_exclude.mp4

Features

• Three modes — blur all faces, just one specific face, or everyone except one face
• Four blur styles — blur, blackout, pixelation, or eye bar
• Speed / accuracy tradeoff — choose model pack (buffalo_l → buffalo_sc) and detection resolution
• GPU support — uses ONNX Runtime; swap in onnxruntime-gpu for CUDA acceleration
• Audio preserved — audio is muxed back into the output automatically

Installation

Requires Python 3.12+, uv, and ffmpeg.

git clone git@github.com:raviksharma/blurfaces.git
cd blurfaces
uv sync

For GPU support:

uv sync --extra gpu

Usage

# Blur all faces
uv run blurfaces video.mp4

# Blur one specific person with pixelation
uv run blurfaces video.mp4 --mode target --face person.jpg --blur pixel

# Blur everyone except one person
uv run blurfaces video.mp4 --mode exclude --face person.jpg --blur blackout

# Faster processing (smaller model + lower detection resolution)
uv run blurfaces video.mp4 --model buffalo_sc --det-size 320

# Custom output path
uv run blurfaces video.mp4 -o censored.mp4

Docker

Pre-built image (GHCR)

docker pull ghcr.io/raviksharma/blurfaces:latest
docker run --rm -v $(pwd)/media:/data ghcr.io/raviksharma/blurfaces /data/video.mp4 -o /data/out.mp4

Build locally

docker build -t blurfaces .
docker run --rm -v $(pwd)/media:/data blurfaces /data/video.mp4 -o /data/out.mp4

Options

Option	Default	Description
--mode	all	all, target, or exclude
--blur	blackout	blur, blackout, pixel, or bar
--face	NA	Reference face image (required for target/exclude)
--model	buffalo_sc	buffalo_l (accurate), buffalo_s (balanced), buffalo_sc (fast)
--det-size	640	Detection resolution in pixels
--threshold	0.45	Cosine similarity threshold for face matching
-o	out.<ext>	Output file path

Additional Information

• originally developed for Bellingcat Oct 2022 Hackathon
• tool is not perfect; should be used with other manual editing before final publish
• next steps
  • smooth face locations (fixes failure in detecting odd frames)
  • detect scene change and use it to reset face locations