# fantaclaus-com/ai_exp-facefusion architecture

> Architecture diagram of the GitHub repository fantaclaus-com/ai_exp-facefusion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fantaclaus-com/ai_exp-facefusion
- Repository: https://github.com/fantaclaus-com/ai_exp-facefusion

## Overview

##### Project type and purpose
- FaceFusion is a Python-based command-line and optional UI application for face swapping and enhancement in images/videos.
- It combines a CLI entry point (`run.py`) with a modular core engine that orchestrates downloading models, analyzing faces, masking, per-frame processing, and output generation.

##### File structure
- Top-level:
- `run.py` & `install.py`: CLI entry points
- `facefusion/`: core package
- `tests/`: unit tests
- Configs: `facefusion.ini`, `.flake8`, `mypy.ini`
- `facefusion/` break-down:
- Core modules: `core.py`, `config.py`, `download.py`, `installer.py`, `filesystem.py`, `ffmpeg.py`, `memory.py`, `logger.py`, etc.
- Analytics & helpers: `content_analyser.py`, `face_analyser.py`, `face_helper.py`, `normalizer.py`, `metadata.py`, `execution_helper.py`
- Face store: `face_store.py` to cache detected faces
- Processors: `facefusion/processors/frame/*` – a plugin-style folder for `face_debugger`, `face_enhancer`, `face_swapper`, `frame_enhancer`
- UI layer: `facefusion/uis/` – assets, components, layouts for interactive mode
- Patterns & concerns:
- Pipeline pattern: data flows from source → analyzer → masker → frame processors → output
- Plugin architecture: each frame processor is a self-contained module
- Separation of concerns: UI vs core vs processing vs I/O

##### README
- Describes CLI options, face analysis parameters, frame extraction, output encoding, UI layouts.
- Emphasizes headless vs interactive mode, execution providers (CPU/GPU), and memory strategies.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI/UI Layer
    subgraph "CLI/UI Layer"
        Run["run.py"]:::cli
        InstallCLI["install.py"]:::cli
        UIS["facefusion/uis/"]:::cli
    end

    %% Core Orchestrator
    subgraph "Core Orchestrator"
        Core["core.py"]:::core
        Config["config.py"]:::core
        Logger["logger.py"]:::core
        Installer["installer.py"]:::core
        Downloader["download.py"]:::core
        Globals["globals.py"]:::core
    end

    %% I/O & Pre/Post Processing
    subgraph "I/O & Pre/Post Processing"
        FFmpeg["ffmpeg.py"]:::io
        FS["filesystem.py"]:::io
    end

    %% Face Analysis & Caching
    subgraph "Face Analysis & Caching"
        Content["content_analyser.py"]:::analysis
        FaceAnalyser["face_analyser.py"]:::analysis
        FaceStore["face_store.py"]:::storage
    end

    %% Masking & Normalization
    subgraph "Masking & Normalization"
        Masker["face_masker.py"]:::core
        Normalizer["normalizer.py"]:::core
    end

    %% Frame Processing Pipeline
    subgraph "Frame Processing Pipeline"
        FPCore["core.py"]:::process
        FPChoices["choices.py"]:::process
        FPGlobals["globals.py"]:::process
        subgraph "Plugins"
            Debugger["face_debugger.py"]:::process
            Enhancer["face_enhancer.py"]:::process
            Swapper["face_swapper.py"]:::process
            FrameEnh["frame_enhancer.py"]:::process
        end
    end

    %% Memory & Execution Management
    subgraph "Memory & Execution Management"
        Memory["memory.py"]:::core
        ExecHelper["execution_helper.py"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        FFmpegBin["FFmpeg Binary"]:::external
        DLFramework["DL Frameworks"]:::external
    end

    %% Output
    subgraph "Output"
        Output["Final Video/Image"]:::output
    end

    %% Data and Control Flows
    Run -->|CLI Invoke| Core
    InstallCLI -->|CLI Invoke| Core
    UIS -->|Interactive Control| Core

    Core -->|uses| Config
    Core -->|logs to| Logger
    Core -->|manages install| Installer
    Core -->|downloads models| Downloader
    Core -->|reads globals| Globals

    Core -->|"invokes"| FFmpeg
    Core -->|"accesses"| FS

    FFmpeg -->|"extracts frames"| Content
    Content -->|"analyzes content"| FaceAnalyser
    FaceAnalyser -->|"caches faces"| FaceStore

    FaceAnalyser -->|"generates mask"| Masker
    Masker -->|"normalizes faces"| Normalizer

    Normalizer -->|"feeds frames"| FPCore
    FPCore -->|"loads config"| FPChoices
    FPCore -->|"reads globals"| FPGlobals

    FPCore -->|process| Debugger
    FPCore -->|process| Enhancer
    FPCore -->|process| Swapper
    FPCore -->|process| FrameEnh

    Debugger -->|"processed frames"| FFmpeg
    Enhancer -->|"processed frames"| FFmpeg
    Swapper -->|"processed frames"| FFmpeg
    FrameEnh -->|"processed frames"| FFmpeg

    FFmpeg -->|assembles| Output
    Output -->|written to| FS
    Core -->|manages| ExecHelper
    Core -->|uses| Memory

    FPCore -->|uses| ExecHelper
    FPCore -->|uses| Memory

    FFmpegBin ---|utilized by| FFmpeg
    DLFramework ---|utilized by| FaceAnalyser
    DLFramework ---|utilized by| Enhancer
    DLFramework ---|utilized by| Swapper

    %% Click Events
    click Run "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/run.py"
    click InstallCLI "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/install.py"
    click UIS "https://github.com/fantaclaus-com/ai_exp-facefusion/tree/master/facefusion/uis/"
    click Core "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/core.py"
    click Config "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/config.py"
    click Logger "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/logger.py"
    click Installer "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/installer.py"
    click Downloader "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/download.py"
    click Globals "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/globals.py"
    click FFmpeg "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/ffmpeg.py"
    click FS "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/filesystem.py"
    click Content "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/content_analyser.py"
    click FaceAnalyser "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/face_analyser.py"
    click FaceStore "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/face_store.py"
    click Masker "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/face_masker.py"
    click Normalizer "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/normalizer.py"
    click FPCore "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/core.py"
    click FPChoices "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/choices.py"
    click FPGlobals "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/globals.py"
    click Debugger "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/modules/face_debugger.py"
    click Enhancer "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/modules/face_enhancer.py"
    click Swapper "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/modules/face_swapper.py"
    click FrameEnh "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/processors/frame/modules/frame_enhancer.py"
    click Memory "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/memory.py"
    click ExecHelper "https://github.com/fantaclaus-com/ai_exp-facefusion/blob/master/facefusion/execution_helper.py"

    %% Styles
    classDef cli fill:#D6E9FF,stroke:#000,stroke-width:1px
    classDef core fill:#DFF2BF,stroke:#000,stroke-width:1px
    classDef io fill:#FEEFB3,stroke:#000,stroke-width:1px
    classDef analysis fill:#F3E2A9,stroke:#000,stroke-width:1px
    classDef storage fill:#E4E1F7,stroke:#000,stroke-width:1px
    classDef process fill:#FFD3B6,stroke:#000,stroke-width:1px
    classDef external fill:#FFB6B9,stroke:#000,stroke-width:1px
    classDef output fill:#D0F0C0,stroke:#000,stroke-width:1px
```
