# lightbatis/deeplivecam architecture

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

- Interactive diagram: https://gitdiagram.com/lightbatis/deeplivecam
- Repository: https://github.com/lightbatis/deeplivecam

## Overview

##### Project type and purpose
- Type: This is an open-source desktop tool (Python application with optional GUI and CLI) for real-time face swapping and enhancement (“Deep Live Cam”).
- Purpose: Capture or load video/image frames, detect and analyse faces, apply face swapping/enhancement models, and write out processed frames or video.

##### File structure
- Top-level scripts & configs:
- run.py (entry point for GUI/CLI)
- setup and run-*.bat scripts for different environments
- mypi.ini, requirements.txt (configuration & dependencies)
- models/ folder: pre-trained model files (face swapper, enhancer, GFPGAN, inswapper)
- modules/ package: main application logic
- capturer.py – frame capture (webcam or file via FFmpeg)
- core.py – orchestration of processing pipeline
- face_analyser.py – face detection & alignment
- predicter.py – calls ONNXRuntime for face models
- processors/frame/ – specific frame transformations
– face_swapper.py, face_enhancer.py, etc.
- metadata.py & globals.py – shared constants & runtime state
- ui.py & ui.json – GUI layout and event loop
- utilities.py – helper functions (I/O, logging, UX)
- docs & CONTRIBUTING.md – documentation

##### Key insights from README
- Supports CPU and multiple execution providers (CUDA, CoreML, DirectML, OpenVINO)
- Downloads and manages large models at first run
- Offers both GUI (interactive) and CLI modes
- Uses FFmpeg for video I/O, ONNXRuntime for inference

a. Main components
1. User Interface (GUI or CLI)
2. Frame Capturer (File reader or Webcam)
3. Face Analyser (Detection & Alignment)
4. Model Inference Engine (ONNXRuntime)
5. Frame Processors (swap, enhance, etc.)
6. Output Writer (frames → video via FFmpeg)
7. External Dependencies (FFmpeg, pre-trained models)
8. Execution Providers (CPU / CUDA / CoreML / DirectML / OpenVINO)
b. Relationships & data flow
- UI sends user commands (source, target, options) to Core Orchestrator
- Capturer reads raw frames → hands off to Face Analyser
- Model Engine runs inference using chosen Execution Provider → returns face embeddings or swapped faces
- Frame Processors apply the outputs (enhancement, swapping) to original frames
- Processed frames forwarded to Output Writer, which streams frames into final video file
- UI receives progress updates and displays preview (live or batch)
c. Architectural patterns & design principles
- Modular pipeline: decoupled stages (capture, analyse, infer, process, write)
- Strategy pattern for execution providers (selectable ONNXRuntime backend)
- Plugin-style processors (frame processors directory) allowing easy extension
- Single orchestration core coordinating subcomponents
d. Key technologies & libraries
- Python 3.10+, ONNXRuntime, numpy, OpenCV (implied), PySimpleGUI or similar (for UI)
- FFmpeg (external binary) for video I/O
- Pre-trained deep learning models stored in models/
- Batch scripts for setting up environment (CUDA, CoreML, DirectML, OpenVINO)

##### Detail without over-splitting
- Both real-time (webcam) and batch (file) flows
- How new processors plug into the processor pipeline
- How UI or CLI triggers the same Core orchestrator
- Models directory as a runtime dependency for the Model Engine

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface"
        GUI["GUI (PySimpleGUI)"]:::io
        CLI["CLI (Argument Parser)"]:::io
    end

    %% Core Orchestrator
    Core["Core Orchestrator"]:::process

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        Capturer["Frame Capturer"]:::io
        Analyser["Face Analyser"]:::process
        subgraph "Model Inference"
            Engine["ONNXRuntime Engine"]:::engine
            subgraph "Execution Providers"
                CPU["CPU"]:::external
                CUDA["CUDA"]:::external
                CoreML["CoreML"]:::external
                DirectML["DirectML"]:::external
                OpenVINO["OpenVINO"]:::external
            end
        end
        subgraph "Frame Processors"
            Swap["Face Swapper"]:::process
            Enhance["Face Enhancer"]:::process
            ProcCore["Processors Core"]:::process
        end
        Writer["Output Writer (FFmpeg)"]:::io
    end

    %% Supporting Components
    subgraph "Support Modules"
        Metadata["Metadata & Globals"]:::external
        Utilities["Utilities & I/O Helpers"]:::external
    end

    %% Configuration & Scripts
    subgraph "Configuration & Scripts"
        Config["Config & Dependencies"]:::external
        Scripts["Batch & Env Scripts"]:::external
    end

    %% Documentation
    subgraph "Documentation"
        Docs["docs/"]:::external
        Contrib["CONTRIBUTING.md"]:::external
        Readme["README.md"]:::external
    end

    %% Data Flows
    GUI -->|"command"| Core
    CLI -->|"command"| Core
    Core -->|"request frame"| Capturer
    Capturer -->|"Raw Frame"| Analyser
    Analyser -->|"Face Crop"| Engine
    Engine -->|"face tensor"| Swap
    Engine -->|"face tensor"| Enhance
    Swap -->|"swapped frame"| ProcCore
    Enhance -->|"enhanced frame"| ProcCore
    ProcCore -->|"Processed Frame"| Writer
    Writer -->|"video file"| FileSystem["File System"]:::external

    Core -->|"uses"| Metadata
    Core -->|"uses"| Utilities
    Engine -->|"loads models"| Models["models/"]:::external
    Engine -->|"select backend"| CPU
    Engine -->|"select backend"| CUDA
    Engine -->|"select backend"| CoreML
    Engine -->|"select backend"| DirectML
    Engine -->|"select backend"| OpenVINO
    Config --> Core
    Scripts --> Core

    %% Click Events
    click GUI "https://github.com/lightbatis/deeplivecam/blob/main/modules/ui.py"
    click CLI "https://github.com/lightbatis/deeplivecam/blob/main/run.py"
    click Core "https://github.com/lightbatis/deeplivecam/blob/main/modules/core.py"
    click Capturer "https://github.com/lightbatis/deeplivecam/blob/main/modules/capturer.py"
    click Analyser "https://github.com/lightbatis/deeplivecam/blob/main/modules/face_analyser.py"
    click Engine "https://github.com/lightbatis/deeplivecam/blob/main/modules/predicter.py"
    click Models "https://github.com/lightbatis/deeplivecam/tree/main/models/"
    click Swap "https://github.com/lightbatis/deeplivecam/blob/main/modules/processors/frame/face_swapper.py"
    click Enhance "https://github.com/lightbatis/deeplivecam/blob/main/modules/processors/frame/face_enhancer.py"
    click ProcCore "https://github.com/lightbatis/deeplivecam/blob/main/modules/processors/frame/core.py"
    click Metadata "https://github.com/lightbatis/deeplivecam/blob/main/modules/metadata.py"
    click Utilities "https://github.com/lightbatis/deeplivecam/blob/main/modules/utilities.py"
    click Config "https://github.com/lightbatis/deeplivecam/blob/main/mypi.ini"
    click Scripts "https://github.com/lightbatis/deeplivecam/blob/main/run-cuda.bat"
    click Docs "https://github.com/lightbatis/deeplivecam/tree/main/docs/"
    click Contrib "https://github.com/lightbatis/deeplivecam/blob/main/CONTRIBUTING.md"
    click Readme "https://github.com/lightbatis/deeplivecam/blob/main/README.md"

    %% Styles
    classDef io fill:#aec7e8,stroke:#000;
    classDef process fill:#98df8a,stroke:#000;
    classDef engine fill:#ff7f0e,stroke:#000;
    classDef external fill:#d3d3d3,stroke:#000;
```
