How to Configure Face Detection and Alignment in the FaceSwap Extract Process

Face detection and alignment in FaceSwap are configured via the -D/--detector and -A/--aligner CLI arguments, which dynamically load plugin classes from plugins/extract/detect/ and plugins/extract/align/ through the PluginLoader system.

The extraction pipeline in the deepfakes/faceswap repository relies on a modular plugin architecture to locate faces and determine their orientation. When you configure face detection and alignment settings, you are selecting specific neural network models that run sequentially—first finding the face boundary box, then predicting facial landmarks. This configuration can be performed via command-line arguments when running faceswap.py extract or programmatically through the Python API.

Understanding the Plugin Architecture

The extraction system separates concerns into two distinct plugin types managed by the Extractor class in plugins/extract/pipeline.py.

Detector Plugins

Detectors implement the base class plugins.extract.detect._base.Detector and are responsible for locating faces within a frame. The system provides different defaults based on hardware availability:

• GPU systems: s3fd (Single Shot MultiBox Detector)
• CPU systems: mtcnn (Multi-task Cascaded Convolutional Networks)

Other available detectors include cv2-dnn and external, located in plugins/extract/detect/.

Aligner Plugins

Aligners implement plugins.extract.align._base.Aligner and predict facial landmarks (typically 68 or 81 points) to normalize face orientation:

• GPU systems: fan (Face Alignment Network)
• CPU systems: cv2-dnn (OpenCV DNN implementation)

These reside in plugins/extract/align/ and are instantiated based on the -A argument.

Command-Line Configuration

The CLI arguments are defined in lib/cli/args_extract_convert.py within the ExtractArgs class. The -D/--detector and -A/--aligner options use PluginLoader.get_available_extractors() to populate valid choices dynamically.

# lib/cli/args_extract_convert.py

argument_list.append({
    "opts": ("-D", "--detector"),
    "action": Radio,
    "type": str.lower,
    "default": default_detector,
    "choices": PluginLoader.get_available_extractors("detect"),
    "group": _("Plugins"),
    "help": _("Detector to use …")
})
argument_list.append({
    "opts": ("-A", "--aligner"),
    "action": Radio,
    "type": str.lower,
    "default": default_aligner,
    "choices": PluginLoader.get_available_extractors("align"),
    "group": _("Plugins"),
    "help": _("Aligner to use …")
})

To run extraction with specific plugins:

# Default GPU configuration (s3fd + fan)

python3 faceswap.py extract -i /data/input -o /data/output

# CPU-optimized configuration (mtcnn + cv2-dnn)

python3 faceswap.py extract -i /data/input -o /data/output \
    -D mtcnn -A cv2-dnn

Programmatic Configuration

You can configure the extraction pipeline directly in Python by constructing an argparse.Namespace and passing it to the Extract class from scripts/extract.py:

from argparse import Namespace
from scripts.extract import Extract

# Configure arguments programmatically

args = Namespace(
    input_dir="/data/input",
    output_dir="/data/output",
    detector="mtcnn",          # Custom detector

    aligner="cv2-dnn",         # Custom aligner

    maskers=[],                # Default maskers

    # … additional arguments as needed …

)

# Initialize and run extraction

extractor = Extract(args)
extractor.process()

Pipeline Initialization Deep Dive

The Extractor class in plugins/extract/pipeline.py handles the instantiation of selected plugins through the _load_detect and _load_align methods.

Loading the Detector

The _load_detect method resolves the detector name via PluginLoader.get_detector() and handles special logic for external aligners:

# plugins/extract/pipeline.py

def _load_detect(self, detector, aligner, rotation, min_size, configfile):
    if detector is None or detector.lower() == "none":
        return None
    detector_name = detector.replace("-", "_").lower()
    # Force external detector if aligner is external but detector isn't

    if aligner == "external" and detector_name != "external":
        detector_name = aligner
    plugin = PluginLoader.get_detector(detector_name)(
        rotation=rotation,
        min_size=min_size,
        configfile=configfile,
        instance=self._instance)
    return plugin

Loading the Aligner

Similarly, _load_align instantiates the aligner plugin:

# plugins/extract/pipeline.py

def _load_align(self, aligner, configfile, normalize_method,
                re_feed, re_align, disable_filter):
    if aligner is None or aligner.lower() == "none":
        return None
    aligner_name = aligner.replace("-", "_").lower()
    plugin = PluginLoader.get_aligner(aligner_name)(
        configfile=configfile,
        normalize_method=normalize_method,
        re_feed=re_feed,
        re_align=re_align,
        disable_filter=disable_filter,
        instance=self._instance)
    return plugin

Configuration Files and Plugin Options

Beyond CLI selection, each plugin exposes hardware-specific settings through config/extract.ini. Detector options typically include rotation and min_size, while aligners support normalize_method, re_feed, re_align, and disable_filter.

To use a custom configuration file:

python3 faceswap.py extract -i /data/input -o /data/output \
    --configfile /path/to/custom_extract.ini

Summary

• Face detection and alignment in FaceSwap are handled by swappable plugins loaded via PluginLoader according to the deepfakes/faceswap source code.
• Default selections are hardware-dependent: s3fd/fan for GPU, mtcnn/cv2-dnn for CPU.
• CLI configuration uses -D/--detector and -A/--aligner arguments defined in lib/cli/args_extract_convert.py.
• Programmatic configuration requires passing a Namespace object with detector and aligner attributes to the Extract class.
• Pipeline initialization occurs in plugins/extract/pipeline.py, where _load_detect and _load_align instantiate the selected plugins with configuration from config/extract.ini.

Frequently Asked Questions

What are the default face detection and alignment plugins in FaceSwap?

FaceSwap automatically selects plugins based on your hardware configuration. For GPU systems, the defaults are s3fd (Single Shot MultiBox Detector) for detection and fan (Face Alignment Network) for alignment. For CPU-only systems, the defaults switch to mtcnn (Multi-task Cascaded Convolutional Networks) for detection and cv2-dnn for alignment.

How do I switch to a CPU-friendly detector when running extraction?

Pass the -D or --detector flag with the value mtcnn or cv2-dnn when launching the extraction command. For example: python3 faceswap.py extract -i /data/input -o /data/output -D mtcnn -A cv2-dnn. This bypasses the GPU-optimized defaults and loads the CPU-efficient implementations from plugins/extract/detect/mtcnn.py and plugins/extract/align/cv2_dnn.py.

Can I use external face detection models with FaceSwap?

Yes. FaceSwap supports an external detector and aligner option designed for integration with external systems. When you specify external for the aligner via -A external, the pipeline automatically forces the detector to external as well if it isn't already set, as implemented in the _load_detect method in plugins/extract/pipeline.py. This allows you to inject custom detection logic while maintaining the standard extraction workflow.

Where are the plugin-specific settings for detectors and aligners stored?

Per-plugin configuration options are stored in config/extract.ini. Each detector and aligner defines its own section in this file, controlling parameters such as rotation, min_size for detectors, and normalize_method, re_feed, re_align, and disable_filter for aligners. You can override the default configuration file path by passing --configfile /path/to/custom.ini when running the extract command.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}