How greywarden07/faceforge works
Project Type & Purpose
• Project type: Desktop/CLI AI application (not a web service)
• Purpose: Real-time face swapping & enhancement using deep-learning models, via both CLI and CustomTkinter GUI
Top-Level Architecture Overview
• Entry points
– run.py (main orchestrator)
– run-cuda.bat / run-directml.bat (Windows launcher scripts)
• User Interfaces
– CLI interface (argument parser in run.py)
– GUI interface (modules/ui.py + modules/ui.json + CustomTkinter)
• Core Orchestration
– modules/core.py (pipeline setup & coordination)
– modules/globals.py (config & state)
• AI & CV Processing
– Face Detection & Clustering
• modules/face_analyser.py (InsightFace & OpenCV)
• modules/cluster_analysis.py
– NSFW Filtering
• modules/predicter.py (OpenNSFW2)
– Frame Processing Pipeline (plugin-style)
• modules/processors/frame/core.py (pipeline engine)
• modules/processors/frame/face_swapper.py (ONNX InSwap)
• modules/processors/frame/face_enhancer.py (GFPGAN)
• Video/Capture & I/O
– modules/video_capture.py (webcam/live)
– modules/capturer.py (file I/O, frames extraction)
– Encoding & Audio Handling (OpenCV + FFmpeg via wrappers)
• Model Storage
– models/ directory (pretrained ONNX/PyTorch model files)
Relationships & Interactions
• User → run.py
– CLI flags or GUI events
• run.py → Core
– initializes modules/globals → loads model artifacts → builds processing pipeline
• Core → Video/Capturer
– reads frames from file or camera
• For each frame:
• Core → Encoder/Writer
– writes processed frames to video file (preserving audio if requested) or shows real-time preview
• GUI ↔ Core
– user config changes → pipeline rebuilt on-the-fly → live preview updated
Architectural Patterns & Principles
• Pipeline / Plugin Pattern
– Frame processors registered dynamically (see modules/processors/frame)
• Modular Separation of Concerns
– UI, Core, Analytics, Processing modules decoupled via well-defined interfaces
• Configuration & Dependency Injection
– globals.py holds runtime options → passed into modules at init
• Concurrency
– Multi-threaded frame capture vs. processing queues (for real-time performance)