# deepfakes/faceswap architecture

> Architecture diagram of the GitHub repository deepfakes/faceswap, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/deepfakes/faceswap
- Repository: https://github.com/deepfakes/faceswap

## Overview

FaceSwap is a face-swapping application whose documented workflow is to extract faces from source media, train a model on faces from two identities, then convert target media with that model. The graph separates those domain stages and shows shared inference, alignment, and media handling where the source index supports relationships. It also preserves GUI access, manual alignment, and video tooling as product capabilities. Some stage-level connections come from the README; unsampled implementation details are not inferred.

Main entry points: [`faceswap.py`](https://github.com/deepfakes/faceswap/blob/master/faceswap.py) (CLI entry), [`lib/training/train.py`](https://github.com/deepfakes/faceswap/blob/master/lib/training/train.py) (Training loop), [`lib/convert.py`](https://github.com/deepfakes/faceswap/blob/master/lib/convert.py) (Conversion engine), [`lib/infer/handler.py`](https://github.com/deepfakes/faceswap/blob/master/lib/infer/handler.py) (Inference handlers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["Face extraction"]
  node_extract_cmd["Extract command<br/>[extract.py]"]
  node_extract_plugins["Detection and alignment plugins<br/>[base.py]"]
end

subgraph group_train["Model training"]
  node_train_cmd["Training command<br/>[train.py]"]
  node_train_loop["Training loop<br/>[train.py]"]
  node_train_data["Training data<br/>[data_set.py]"]
  node_model_plugins["Model architectures<br/>[phaze_a.py]"]
  node_trainer_plugins["Trainer implementations<br/>[base.py]"]
end

subgraph group_convert["Face conversion"]
  node_convert_cmd["Convert command<br/>[convert.py]"]
  node_convert_engine["Conversion engine<br/>[convert.py]"]
  node_convert_plugins["Swap and output plugins<br/>[color_transfer.py]"]
end

subgraph group_runtime["Shared runtime"]
  node_infer_handler["Inference handlers<br/>[handler.py]"]
  node_plugin_loader["Plugin loader<br/>[plugin_loader.py]"]
  node_align_data["Face alignment data<br/>[aligned_face.py]"]
  node_align_store[("Alignment files<br/>[alignments.py]")]
  node_image_io["Image and video I/O<br/>[image.py]"]
  node_infer_runner["Inference runner<br/>[runner.py]"]
end

subgraph group_interfaces["User interfaces and tools"]
  node_entry["CLI entry<br/>[faceswap.py]"]
  node_gui["Graphical interface<br/>[gui.py]"]
  node_preview["Swap preview<br/>[preview.py]"]
  node_manual_tools["Manual face tools<br/>[manual.py]"]
  node_video_tools["Video tools<br/>[effmpeg.py]"]
end

node_user(("User"))

node_user -->|"runs"| node_entry
node_entry -->|"starts extraction"| node_extract_cmd
node_entry -->|"starts training"| node_train_cmd
node_entry -->|"starts conversion"| node_convert_cmd
node_entry -->|"opens GUI"| node_gui
node_extract_cmd -.->|"uses plugins"| node_extract_plugins
node_extract_plugins -->|"handled by"| node_infer_handler
node_infer_handler -->|"loads plugins"| node_plugin_loader
node_infer_handler -->|"managed by"| node_infer_runner
node_infer_handler -->|"creates aligned faces"| node_align_data
node_extract_cmd -.->|"saves alignments"| node_align_store
node_train_cmd -.->|"starts training"| node_train_loop
node_train_loop -.->|"uses datasets"| node_train_data
node_train_loop -.->|"trains model"| node_model_plugins
node_train_loop -.->|"uses trainer"| node_trainer_plugins
node_convert_cmd -->|"runs conversion"| node_convert_engine
node_convert_engine -.->|"uses inference"| node_infer_runner
node_convert_engine -.->|"uses plugins"| node_convert_plugins
node_convert_engine -.->|"processes media"| node_image_io
node_gui -.->|"offers preview"| node_preview
node_user -.->|"edits faces"| node_manual_tools
node_user -->|"runs video tools"| node_video_tools

click node_entry "https://github.com/deepfakes/faceswap/blob/master/faceswap.py"
click node_extract_cmd "https://github.com/deepfakes/faceswap/blob/master/scripts/extract.py"
click node_extract_plugins "https://github.com/deepfakes/faceswap/blob/master/plugins/extract/base.py"
click node_infer_handler "https://github.com/deepfakes/faceswap/blob/master/lib/infer/handler.py"
click node_plugin_loader "https://github.com/deepfakes/faceswap/blob/master/plugins/plugin_loader.py"
click node_align_data "https://github.com/deepfakes/faceswap/blob/master/lib/align/aligned_face.py"
click node_align_store "https://github.com/deepfakes/faceswap/blob/master/lib/align/alignments.py"
click node_image_io "https://github.com/deepfakes/faceswap/blob/master/lib/image.py"
click node_train_cmd "https://github.com/deepfakes/faceswap/blob/master/scripts/train.py"
click node_train_loop "https://github.com/deepfakes/faceswap/blob/master/lib/training/train.py"
click node_train_data "https://github.com/deepfakes/faceswap/blob/master/lib/training/data/data_set.py"
click node_model_plugins "https://github.com/deepfakes/faceswap/blob/master/plugins/train/model/phaze_a.py"
click node_trainer_plugins "https://github.com/deepfakes/faceswap/blob/master/plugins/train/trainer/base.py"
click node_convert_cmd "https://github.com/deepfakes/faceswap/blob/master/scripts/convert.py"
click node_convert_engine "https://github.com/deepfakes/faceswap/blob/master/lib/convert.py"
click node_convert_plugins "https://github.com/deepfakes/faceswap/blob/master/plugins/convert/color/color_transfer.py"
click node_infer_runner "https://github.com/deepfakes/faceswap/blob/master/lib/infer/runner.py"
click node_gui "https://github.com/deepfakes/faceswap/blob/master/scripts/gui.py"
click node_preview "https://github.com/deepfakes/faceswap/blob/master/tools/preview/preview.py"
click node_manual_tools "https://github.com/deepfakes/faceswap/blob/master/tools/manual/manual.py"
click node_video_tools "https://github.com/deepfakes/faceswap/blob/master/tools/effmpeg/effmpeg.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extract_cmd,node_extract_plugins,node_user toneBlue
class node_train_cmd,node_train_loop,node_train_data,node_model_plugins,node_trainer_plugins toneAmber
class node_convert_cmd,node_convert_engine,node_convert_plugins toneMint
class node_infer_handler,node_plugin_loader,node_align_data,node_align_store,node_image_io,node_infer_runner toneRose
class node_entry,node_gui,node_preview,node_manual_tools,node_video_tools toneIndigo
```

## Components

### Face extraction

- [Extract command](https://github.com/deepfakes/faceswap/blob/master/scripts/extract.py): `scripts/extract.py`
- [Detection and alignment plugins](https://github.com/deepfakes/faceswap/blob/master/plugins/extract/base.py): `plugins/extract/base.py`

### Model training

- [Training command](https://github.com/deepfakes/faceswap/blob/master/scripts/train.py): `scripts/train.py`
- [Training loop](https://github.com/deepfakes/faceswap/blob/master/lib/training/train.py): `lib/training/train.py`
- [Training data](https://github.com/deepfakes/faceswap/blob/master/lib/training/data/data_set.py): `lib/training/data/data_set.py`
- [Model architectures](https://github.com/deepfakes/faceswap/blob/master/plugins/train/model/phaze_a.py): `plugins/train/model/phaze_a.py`
- [Trainer implementations](https://github.com/deepfakes/faceswap/blob/master/plugins/train/trainer/base.py): `plugins/train/trainer/base.py`

### Face conversion

- [Convert command](https://github.com/deepfakes/faceswap/blob/master/scripts/convert.py): `scripts/convert.py`
- [Conversion engine](https://github.com/deepfakes/faceswap/blob/master/lib/convert.py): `lib/convert.py`
- [Swap and output plugins](https://github.com/deepfakes/faceswap/blob/master/plugins/convert/color/color_transfer.py): `plugins/convert/color/color_transfer.py`

### Shared runtime

- [Inference handlers](https://github.com/deepfakes/faceswap/blob/master/lib/infer/handler.py): `lib/infer/handler.py`
- [Plugin loader](https://github.com/deepfakes/faceswap/blob/master/plugins/plugin_loader.py): `plugins/plugin_loader.py`
- [Face alignment data](https://github.com/deepfakes/faceswap/blob/master/lib/align/aligned_face.py): `lib/align/aligned_face.py`
- [Alignment files](https://github.com/deepfakes/faceswap/blob/master/lib/align/alignments.py): `lib/align/alignments.py`
- [Image and video I/O](https://github.com/deepfakes/faceswap/blob/master/lib/image.py): `lib/image.py`
- [Inference runner](https://github.com/deepfakes/faceswap/blob/master/lib/infer/runner.py): `lib/infer/runner.py`

### User interfaces and tools

- [CLI entry](https://github.com/deepfakes/faceswap/blob/master/faceswap.py): `faceswap.py`
- [Graphical interface](https://github.com/deepfakes/faceswap/blob/master/scripts/gui.py): `scripts/gui.py`
- [Swap preview](https://github.com/deepfakes/faceswap/blob/master/tools/preview/preview.py): `tools/preview/preview.py`
- [Manual face tools](https://github.com/deepfakes/faceswap/blob/master/tools/manual/manual.py): `tools/manual/manual.py`
- [Video tools](https://github.com/deepfakes/faceswap/blob/master/tools/effmpeg/effmpeg.py): `tools/effmpeg/effmpeg.py`

### Other components

- **User**

## Connections

- User → CLI entry: runs (evidence: `README.md`)
- CLI entry → Extract command: starts extraction (evidence: `README.md`)
- CLI entry → Training command: starts training (evidence: `README.md`)
- CLI entry → Convert command: starts conversion (evidence: `README.md`)
- CLI entry → Graphical interface: opens GUI (evidence: `README.md`)
- Extract command → Detection and alignment plugins: uses plugins
- Detection and alignment plugins → Inference handlers: handled by (evidence: `lib/infer/handler.py`)
- Inference handlers → Plugin loader: loads plugins (evidence: `lib/infer/handler.py`)
- Inference handlers → Inference runner: managed by (evidence: `lib/infer/handler.py`)
- Inference handlers → Face alignment data: creates aligned faces (evidence: `lib/infer/handler.py`)
- Extract command → Alignment files: saves alignments
- Training command → Training loop: starts training
- Training loop → Training data: uses datasets
- Training loop → Model architectures: trains model
- Training loop → Trainer implementations: uses trainer
- Convert command → Conversion engine: runs conversion (evidence: `tools/preview/preview.py`)
- Conversion engine → Inference runner: uses inference
- Conversion engine → Swap and output plugins: uses plugins
- Conversion engine → Image and video I/O: processes media
- Graphical interface → Swap preview: offers preview
- User → Manual face tools: edits faces
- User → Video tools: runs video tools (evidence: `README.md`)
