← Back to Guides
PrivateFrameLocal video processingDesktop · CLI · PythonBlur & mosaic

PrivateFrame — Installation and usage guide

Start with the desktop app, automate a video workflow, or integrate processing into Python.

•8 min read

What you will build

Detect and track faces in your videos, then apply blur or mosaic on your own device. Select everyone or use reference photos to choose who stays visible.

Commercial deployment with InsightFace pretrained models requires a separate commercial model license.

Video demo

See PrivateFrame in action.

Watch face tracking and redaction across different scenes, with Gaussian blur and mosaic output.

Actual PrivateFrame output. Review the processed video before sharing.

Open the video

Music: Tears in Rain by Scott Buckley · CC BY 4.0. Excerpted and mixed.

Before you start

  • Python 3.10+ and an updated InsightFace source checkout that contains python-package/insightface/app/privateframe/. Run the installation commands from that repository's root. This guide uses the updated source package; an older checkout or published package may not contain PrivateFrame.
  • A local video and an output folder. Replace the /data/... paths in the examples with paths on your device. Use a different output folder for each example to keep your results separate.
  • Video processing runs locally after dependencies and models are installed. Videos and reference photos are not uploaded for processing. Missing models may download on first use.

1. Installation and usage guide

Python 3.10+ and an updated InsightFace source checkout that contains python-package/insightface/app/privateframe/. Run the installation commands from that repository's root. This guide uses the updated source package; an older checkout or published package may not contain PrivateFrame.

Requires Python 3.10+. Install from the updated repository using the guide. Model downloads may be needed on the first run. The supplied pretrained models are for non-commercial research evaluation only. Obtain a model license before commercial deployment.

Desktop app
python -m pip install "./python-package[gui]"
Command line / Python API
python -m pip install "./python-package[privateframe]"
insightface-privateframe --help

2. Desktop app

Open the PrivateFrame workflow in InsightFace Evaluation Studio. Choose your video, settings, and output folder.

  • Open PrivateFrame in the InsightFace desktop app, or pass a video to the CLI or Python API.
  • Choose a selection mode, add reference photos if needed, and pick blur or mosaic.
  • Export a new video and reusable analysis JSON. Review the output before sharing it.
Desktop app
insightface-gui

3. Command line — Choose who to blur

Process a video in one command, or separate analysis and rendering for review and repeat exports.

For either photo mode, put clear single-person JPG, JPEG, PNG, or WebP photos directly in one reference folder. Each photo contributes only its largest detected face. Both photo modes require at least one usable reference face. Unmatched or uncertain faces remain visible with blur_only and are blurred with exempt under the default policy.

  • Blur every face: Apply redaction to every detected face. No reference photos or identity matching needed.
  • Blur selected people: Blur people matched to your reference photos and keep other people visible.
  • Keep selected people visible: Keep matched people visible while blurring unmatched or uncertain faces.
Blur every face
insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/all
Blur selected people
insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/selected \
  --recognition.mode blur_only \
  --recognition.reference_dir /data/reference_photos
Keep selected people visible
insightface-privateframe process \
  --input /data/video.mp4 --output-dir /data/exempt \
  --recognition.mode exempt \
  --recognition.reference_dir /data/reference_photos

4. Analyze once, render again

Reuse the analysis JSON to change rendering settings or edit face boxes without repeating detection and recognition.

Yes. Keep the original video and the analysis JSON to render again with different blur, mosaic, or encoding settings. You can also edit face boxes in the JSON. Changes to detection or identity matching require a new analysis.

analyze
insightface-privateframe analyze \
  --input /data/video.mp4 --output-dir /data/review
render · mosaic
insightface-privateframe render \
  --input /data/video.mp4 \
  --result /data/review/video_privateframe.json \
  --redacted /data/review/video_mosaic.mp4 \
  --render.redaction.method mosaic

5. Python API

Integrate analysis and rendering into your own application with progress and cancellation callbacks.

Python API
from insightface.app.privateframe import (
    analyze_streaming_pipeline,
    default_output_paths,
    render_streaming_artifacts,
)
from insightface.app.privateframe.base_config import DEFAULT_CONFIG_PATH

paths = default_output_paths("/data/video.mp4", "/data/python_output")

analysis = analyze_streaming_pipeline(
    config_path=DEFAULT_CONFIG_PATH,
    input_path=paths.source,
    workdir=paths.workdir,
    result_path=paths.result_json,
)

rendered = render_streaming_artifacts(
    input_path=paths.source,
    result_path=paths.result_json,
    redacted_path=paths.result_video,
    config_overrides={"render.redaction.method": "mosaic"},
)

6. Process, review, and share

Export a new video and reusable analysis JSON. Review the output before sharing it.

Photo matching can miss a person. Review selective results before sharing; an unmatched target can remain visible in the selected-people mode.

No. Detection, tracking, and matching can miss faces or make mistakes. Review the exported video, especially brief appearances, scene cuts, and occlusions. Face redaction does not hide voices, names, clothing, or other identifying context.

7. Can I use PrivateFrame commercially?

The InsightFace code is MIT licensed. The pretrained models supplied by the project are for non-commercial research; commercial use requires appropriate model authorization. Contact us to discuss your deployment.

Bring video face privacy into your workflow.

Commercial deployment with InsightFace pretrained models requires a separate model license. The code is MIT licensed; code and model licenses apply separately.

Request Commercial License