# Understanding the Filter/NFilter Feature for Identity-Based Face Extraction in FaceSwap

> Learn about FaceSwap's filter and nfilter options for identity-based face extraction. Easily include or exclude specific faces from your swaps for precise control.

- Repository: [deepfakes/faceswap](https://github.com/deepfakes/faceswap)
- Tags: deep-dive
- Published: 2026-03-06

---

**The filter and nfilter options in FaceSwap enable identity-based face extraction by comparing facial embeddings against reference images, allowing you to include only specific identities (filter) or exclude unwanted faces (nfilter) during the extraction process.**

The deepfakes/faceswap repository provides advanced tools for face manipulation, including sophisticated identity-based filtering mechanisms. The filter and nfilter features allow users to control which faces are extracted from video or image sequences by leveraging pre-computed facial identity embeddings. This capability is essential when working with footage containing multiple subjects, ensuring only target identities are processed while filtering out background individuals or unwanted faces.

## What Are Filter and NFilter in FaceSwap?

The **filter** (positive filter) and **nfilter** (negative filter) options work as identity-based gatekeepers during the face extraction pipeline:

- **Filter (`-f/--filter`)**: Provide reference images containing faces you want to **keep**. The extractor will only retain faces whose identity embeddings match these references within a specified threshold.
- **NFilter (`-n/--nfilter`)**: Provide reference images containing faces you want to **exclude**. The extractor will reject any faces matching these identities, even if they might otherwise pass other criteria.

Both mechanisms rely on the same facial recognition models used during normal extraction, computing **512-dimensional identity embeddings** for comparison.

## How Identity-Based Filtering Works Internally

### Command-Line Interface Configuration

The CLI arguments are defined in [[`lib/cli/args_extract_convert.py`](https://github.com/deepfakes/faceswap/blob/main/lib/cli/args_extract_convert.py)](https://github.com/deepfakes/faceswap/blob/master/lib/cli/args_extract_convert.py), where the `-f/--filter` and `-n/--nfilter` options are registered as file path arguments. These accept one or more image files that serve as identity references.

### Extraction Pipeline Integration

In [[`scripts/extract.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/extract.py)](https://github.com/deepfakes/faceswap/blob/master/scripts/extract.py), the `IdentityExtractor` class handles the filter logic:

- **Validation**: The `_validate_inputs` method (around lines 184-205) ensures that provided filter files exist, are valid images, and contain detectable faces.
- **Embedding computation**: For each filter/nfilter image, the extractor detects the face and computes its identity embedding, storing these in `_filter_embeddings` and `_nfilter_embeddings` lists.
- **Flagging**: The `_has_filter_or_nfilter` property tracks whether any filtering is active, allowing the pipeline to skip unnecessary comparison operations when filters aren't specified.

### Recognition and Embedding Comparison

The core filtering logic resides in [[`plugins/extract/recognition/_base.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/recognition/_base.py)](https://github.com/deepfakes/faceswap/blob/master/plugins/extract/recognition/_base.py):

- **Registration**: The `add_filters(filters, nfilters, threshold)` method receives the embedding matrices and similarity threshold, storing them as instance attributes.
- **Enable flags**: The recogniser sets `self._filter_enabled` and `self._nfilter_enabled` to True when respective embeddings are provided.
- **Distance checking**: During face processing, the `_check_face` method (referenced around the `filter_type` handling logic) computes the Euclidean distance between the current face's embedding and all filter/nfilter embeddings.
- **Decision logic**:
  - If `_nfilter_enabled` is True and the distance to any nfilter embedding is **below** the threshold, the face is **rejected** immediately.
  - If `_filter_enabled` is True, the face is **only accepted** if its distance to at least one filter embedding is **below** the threshold.
  - When both are disabled, all detected faces proceed normally.

## Practical Usage Examples

### Basic CLI Usage

Extract faces from a video while keeping only identities matching `target_person.jpg` and excluding anyone resembling `unwanted_person.jpg`:

```bash
python scripts/extract.py \
    -i /path/to/input_video.mp4 \
    -o /path/to/extracted_faces \
    -f /path/to/target_person.jpg \
    -n /path/to/unwanted_person.jpg \
    -t 0.6

```

The `-t` parameter sets the similarity threshold (0.0 = identical, 1.0 = completely different). Lower values require stricter matches.

### Programmatic Implementation

Integrate identity filtering into a custom Python workflow:

```python
from scripts.extract import IdentityExtractor

# Initialize extractor with filter references

extractor = IdentityExtractor(
    filter_files=["/path/to/actor_ref_1.jpg", "/path/to/actor_ref_2.jpg"],
    nfilter_files=["/path/to/crowd_ref.jpg"],
    threshold=0.6,
)

# Process media

extractor.run(
    input_path="/videos/movie_scene.mp4",
    output_path="/output/extracted_actor",
)

```

### Advanced Filter Management

For plugin developers extending the recognition system:

```python
from plugins.extract.recognition._base import _BaseRecognizer
import numpy as np

# Assume filters and nfilters are pre-computed embedding arrays

# Shape: (num_reference_faces, 512)

filter_embeddings = np.array([...])  
nfilter_embeddings = np.array([...])

recognizer = _BaseRecognizer()
recognizer.add_filters(
    filters=filter_embeddings,
    nfilters=nfilter_embeddings,
    threshold=0.6
)

# During extraction loop

face_embedding = get_face_embedding()  # Your extraction logic

if recognizer.should_keep(face_embedding):
    process_face()

```

## Summary

- The **filter** (`-f`) option retains only faces matching provided reference identities, while **nfilter** (`-n`) excludes faces matching unwanted identities.
- Both features operate by computing **512-dimensional facial embeddings** and comparing Euclidean distances against a user-defined threshold.
- The implementation spans [[`lib/cli/args_extract_convert.py`](https://github.com/deepfakes/faceswap/blob/main/lib/cli/args_extract_convert.py)](https://github.com/deepfakes/faceswap/blob/master/lib/cli/args_extract_convert.py) for CLI parsing, [[`scripts/extract.py`](https://github.com/deepfakes/faceswap/blob/main/scripts/extract.py)](https://github.com/deepfakes/faceswap/blob/master/scripts/extract.py) for pipeline orchestration, and [[`plugins/extract/recognition/_base.py`](https://github.com/deepfakes/faceswap/blob/main/plugins/extract/recognition/_base.py)](https://github.com/deepfakes/faceswap/blob/master/plugins/extract/recognition/_base.py) for the core distance-based filtering logic.
- Identity-based extraction is essential for isolating specific subjects in crowded scenes or removing unwanted individuals from training datasets.

## Frequently Asked Questions

### What is the difference between filter and nfilter in FaceSwap?

The **filter** option acts as a positive selector, ensuring only faces that match your reference images are extracted. The **nfilter** option acts as a negative selector, automatically rejecting any faces that resemble your excluded reference images. You can use either option independently or combine them to precisely control which identities enter your extraction pipeline.

### How does FaceSwap calculate similarity for identity filtering?

FaceSwap uses a deep learning-based **face recognition model** to generate 512-dimensional embedding vectors for each face. During filtering, it calculates the **Euclidean distance** between the embedding of a detected face and the embeddings of your filter/nfilter reference images. If the distance falls below the threshold specified by the `-t` parameter (default typically around 0.6), the faces are considered a match.

### Can I use multiple filter images for identity-based extraction?

Yes, you can provide **multiple reference images** for both filter and nfilter options. The extractor computes embeddings for all provided reference faces and checks the detected face against the entire set. If a detected face matches any one of the filter references (or nfilter references), the corresponding action (keep or reject) is triggered. This is particularly useful when the target person appears with different expressions, angles, or lighting conditions.

### What happens if a face matches both filter and nfilter criteria?

The **nfilter (negative filter) takes precedence** over the filter. If a detected face's embedding is within the threshold distance of any nfilter reference, it is immediately rejected regardless of whether it also matches a filter reference. This safety mechanism ensures that explicitly excluded identities never enter your dataset, even in edge cases where a person might resemble both a target and an excluded individual.