# echkidieu1102/deep-live-cam architecture

> Architecture diagram of the GitHub repository echkidieu1102/deep-live-cam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/echkidieu1102/deep-live-cam
- Repository: https://github.com/echkidieu1102/deep-live-cam

## Overview

##### Project’s Type and Purpose
- This project is a specialized deepfake or face-swap tool aimed at assisting artists and creators in animating custom characters or producing swapped-face media.
- Its primary function is to allow users to select a source face (from an image) and then apply that onto a target image, video, or real-time webcam feed. This is achieved by using different models (stored in the “models” directory) and a series of processing modules.

##### File Structure and Key Components
- The root contains various run scripts (run.py, several .bat files) that serve as different execution entry points, including specific setups for CUDA, GPU acceleration, and even a CLI mode.
- The “modules” directory is central – it contains core processing logic:
- modules/core.py: Likely orchestrates the overall processing pipeline.
- modules/capturer.py: Handles video capture (webcam input).
- modules/face_analyser.py: Deals with facial detection and analysis.
- modules/predicter.py: Possibly manages prediction/inference routines.
- modules/ui.py and modules/ui.json: Define and drive the graphical user interface.
- Under “modules/processors/frame/” you have:
- core.py: The base for frame-level processing.
- face_swapper.py: Implements face swapping.
- face_enhancer.py: Provides image enhancement for faces.
- Other utilities and support files (globals.py, metadata.py, utilities.py, typing.py) support shared functionality and type definitions.
- The “models” folder holds externally downloaded AI models (e.g., GFPGAN and inswapper), indicating that the system loads pre-trained weights and ONNX models.
- Various batch scripts and configuration files (mypi.ini, run-cuda.bat, etc.) indicate that hardware acceleration (CUDA, CoreML, DirectML, OpenVINO) is a first-class concern.

##### Main Components & Their Interactions
- User Interface Component:
- Represents the GUI (modules/ui.py, modules/ui.json) that provides an interactive selection for source faces, target media, and settings for webcam or file-based processing.
- Input/Output Management:
- Input: Capturing source faces and target media (images, videos, webcam feed, handled by modules/capturer.py and command-line arguments from run.py).
- Output: Processed frames (saved to directories named after video titles) and ultimately an output video or image.
- Core Orchestration:
- The central controller (modules/core.py) orchestrates how the data flows between receiving user input, preprocessing, and invoking the right processors.
- Face Analysis and Prediction:
- The system uses modules/face_analyser.py to detect and analyze facial features.
- modules/predicter.py likely runs inference using the loaded ONNX models.
- Frame-Level Processors:
- Under modules/processors/frame, two main modules are implemented:
- face_swapper.py: Swaps faces on each frame.
- face_enhancer.py: Applies enhancements to face details.
- There’s an internal “core” module inside the “frame” processor that might provide common processing routines.
- External Dependencies and Hardware Acceleration:
- ONNX Runtime providers (CPU, CUDA, CoreML, DirectML, OpenVINO) are configured through command line arguments and installation scripts.
- Other external libraries like ffmpeg are used for processing video/audio elements.

- The project follows a modular and layered architecture – separating UI, core orchestration, and processor logic.
- It integrates a plug-and-play approach for frame processors, meaning additional processing modules could be swapped or enhanced independently.
- The design adheres to the separation of concerns, dividing responsibilities among input handling, processing logic, and external interfacing.

##### Specific Elements
- Clear labels for each component:
- User Input & UI (with distinction between CLI and GUI modes)
- Core Processing (modules/core.py)
- Face Analysis & Prediction (modules/face_analyser.py and modules/predicter.py)
- Frame Processors (modules/processors/frame/core.py, face_swapper.py, face_enhancer.py)
- External modules and dependencies (models folder, ffmpeg, ONNX Runtime providers)
- The flow from user input to the core engine, then to face detection, and finally through frame processors.
- Data flows that illustrate the dependency on external model files and hardware acceleration configurations.
- Annotations that indicate:
- Architectural patterns like “modular design”, “pluggable processors”, or “hardware acceleration abstraction”.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["User Interface (modules/ui.py & modules/ui.json)"]:::ui
        Capturer["Video & Webcam Input (modules/capturer.py)"]:::ui
    end

    %% Core Engine
    subgraph "Core Engine"
        Core["Core Orchestration (modules/core.py)"]:::core
    end

    %% Face Analysis & Prediction
    subgraph "Face Analysis & Prediction"
        FaceAnalyser["Face Analysis (modules/face_analyser.py)"]:::analysis
        Prediction["Inference/Prediction (modules/predicter.py)"]:::analysis
    end

    %% Frame Processors
    subgraph "Frame Processors"
        FrameCore["Frame Processing Core (modules/processors/frame/core.py)"]:::processor
        FaceSwapper["Face Swapping Processor (modules/processors/frame/face_swapper.py)"]:::processor
        FaceEnhancer["Face Enhancement Processor (modules/processors/frame/face_enhancer.py)"]:::processor
    end

    %% External Integrations
    subgraph "External Integrations"
        Models["External Model Integrations (models/)"]:::external
        FFmpeg["FFmpeg/ONNX Runtime"]:::external
    end

    %% Output Generation
    Output["Output Generation"]:::output

    %% Connections
    UI -->|"triggers"| Core
    Capturer -->|"supplies media"| Core
    Core -->|"initiates analysis"| FaceAnalyser
    Core -->|"initiates prediction"| Prediction
    FaceAnalyser -->|"provides features"| FrameCore
    Prediction -->|"provides inference"| FrameCore
    FrameCore -->|"applies face swap"| FaceSwapper
    FrameCore -->|"applies enhancement"| FaceEnhancer
    FaceSwapper -->|"saves processed frame"| Output
    FaceEnhancer -->|"saves processed frame"| Output
    Models -->|"loads models"| Prediction
    Models -->|"supports processing"| FaceSwapper
    Models -->|"supports processing"| FaceEnhancer
    FFmpeg -->|"handles video processing"| Output

    %% Styling
    classDef ui fill:#f9c74f,stroke:#f9844a,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#43aa8b,stroke-width:2px;
    classDef analysis fill:#f94144,stroke:#c9184a,stroke-width:2px;
    classDef processor fill:#577590,stroke:#4d908e,stroke-width:2px;
    classDef external fill:#277da1,stroke:#577590,stroke-width:2px;
    classDef output fill:#90a8b8,stroke:#5a6d7c,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/ui.py"
    click Capturer "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/capturer.py"
    click Core "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/core.py"
    click FaceAnalyser "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/face_analyser.py"
    click Prediction "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/predicter.py"
    click FrameCore "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/processors/frame/core.py"
    click FaceSwapper "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/processors/frame/face_swapper.py"
    click FaceEnhancer "https://github.com/echkidieu1102/deep-live-cam/blob/main/modules/processors/frame/face_enhancer.py"
    click Models "https://github.com/echkidieu1102/deep-live-cam/tree/main/models/"
```
