Frame Processor pre_check and pre_start Validation Checks in Deep-Live-Cam

The pre_check and pre_start functions in Deep-Live-Cam validate runtime prerequisites including Python version ≥ 3.9, ffmpeg availability, required ONNX model files, and target media formats before processing begins.

Deep-Live-Cam uses a two-stage validation pipeline to prevent runtime failures during face swapping and enhancement. The pre_check functions verify environment and model dependencies, while pre_start functions validate user inputs and media compatibility before any frame-level processing occurs.

Core Environment Validation

The global validation in modules/core.py establishes baseline system requirements before any frame processors load.

Python and FFmpeg Checks

The modules.core.pre_check() function (lines 177–184) performs two critical system validations:

• Python version: Verifies the runtime is using Python 3.9 or higher to ensure compatibility with modern asyncio and typing features used throughout the codebase.
• FFmpeg availability: Uses shutil.which('ffmpeg') to confirm that FFmpeg is installed and accessible in the system PATH, which is required for video encoding and decoding operations.

If either check fails, the function returns False, preventing the application from starting with missing system dependencies.

Face Swapper Validation

The face swapper processor in modules/processors/frame/face_swapper.py implements both validation hooks to ensure model availability and target media validity.

Model Preparation in pre_check

The face_swapper.pre_check() function (lines 46–64) handles model directory initialization:

1. Creates the models directory (models_dir) if it does not exist, with explicit handling of PermissionError exceptions to provide clear feedback when directory creation fails.
2. Downloads the inswapper_128_fp16.onnx model file via conditional_download if the file is absent, ensuring the ONNX inference session can initialize successfully.

Target Media Validation in pre_start

The face_swapper.pre_start() function (lines 67–78) validates user configuration:

• File existence: Verifies that the global target_path variable points to an existing file.
• Model presence: Confirms that inswapper_128_fp16.onnx exists in the models directory, reporting a missing model error to the UI if the file cannot be located.

This prevents the processor from attempting inference with missing weights or invalid input paths.

Face Enhancer Validation

Deep-Live-Cam includes three face enhancement processors, each implementing specialized validation for their respective ONNX models and input formats.

GFPGAN Face Enhancer

Located in modules/processors/frame/face_enhancer.py:

• pre_check() (lines 46–55): Checks for the presence of gfpgan-1024.onnx in the models folder. If the model is missing, it reports the error to the UI rather than attempting download, as this model requires manual placement or alternative acquisition.
• pre_start() (lines 58–64): Validates that target_path points to a supported image or video file using the is_image and is_video utility functions, ensuring the enhancement pipeline receives compatible media.

GPEN-512 Enhancer

Located in modules/processors/frame/face_enhancer_gpen512.py:

• pre_check() (lines 39–45): Validates the presence of GPEN-BFR-512.onnx. If absent, automatically downloads the model from the configured MODEL_URL to ensure the 512-pixel restoration model is available.
• pre_start() (lines 48–52): Confirms that the target path is either a valid image or video file before processing begins.

GPEN-256 Enhancer

Located in modules/processors/frame/face_enhancer_gpen256.py:

• pre_check() (lines 39–45): Mirrors the GPEN-512 logic, checking for GPEN-BFR-256.onnx and downloading from MODEL_URL if the model is missing.
• pre_start() (lines 48–52): Validates target media format compatibility using the same image/video checks as other processors.

How the Validation Pipeline Executes

The validation functions operate in a specific sequence to ensure dependencies are satisfied before processing begins:

1. Global sanity check: modules.core.pre_check() runs during application startup to verify Python version and FFmpeg availability.
2. Per-processor setup: When modules.core.start() initializes the pipeline, it calls get_frame_processors_modules() to load each enabled processor, triggering their individual pre_check() functions to download or verify required ONNX models.
3. Pre-flight validation: Before processing any frames, the core iterates through loaded processors and calls pre_start(), allowing each processor to validate that the user has selected appropriate target media files.

This architecture ensures that missing system dependencies are caught immediately, missing models are downloaded automatically where supported, and invalid user inputs are rejected before GPU-intensive inference begins.

Practical Code Examples

Running Global Environment Checks

from modules.core import pre_check

# Validate Python version and FFmpeg before starting the UI

if not pre_check():
    raise SystemExit("Environment does not meet minimum requirements.")

Loading and Validating Processors

from modules.processors.frame.core import get_frame_processors_modules
from modules.globals import frame_processors

# This triggers pre_check() for each processor, downloading missing models

processor_modules = get_frame_processors_modules(frame_processors)

Executing Pre-Start Validations

from modules.core import start

# start() calls pre_start() for every enabled processor

# Returns False if any validation fails, preventing frame processing

if not start():
    print("Validation failed - check target media and model files")

Manual Processor Validation

from modules.processors.frame.face_enhancer import pre_check, pre_start

# Check for GFPGAN model availability

if not pre_check():
    print("GFPGAN model missing - please add gfpgan-1024.onnx to models/")

# Validate user selected an image or video

if not pre_start():
    print("Invalid target path - select an image or video file")

Summary

• Global checks in modules/core.py validate Python ≥ 3.9 and FFmpeg installation before the application initializes.
• Face swapper validation ensures the inswapper_128_fp16.onnx model exists and handles directory permissions during setup.
• Enhancer processors verify specific ONNX model files (gfpgan-1024.onnx, GPEN-BFR-512.onnx, GPEN-BFR-256.onnx) and download missing GPEN models automatically.
• pre_start functions validate that target_path points to supported image or video formats, preventing runtime errors during frame processing.
• The validation pipeline runs sequentially: environment → models → media, ensuring all prerequisites are met before GPU inference begins.

Frequently Asked Questions

What happens if the GFPGAN model is missing?

The face_enhancer.pre_check() function in modules/processors/frame/face_enhancer.py (lines 46–55) detects the missing gfpgan-1024.onnx file and reports an error to the UI. Unlike the GPEN processors, the GFPGAN implementation does not automatically download models, requiring manual placement of the ONNX file in the models directory.

Does Deep-Live-Cam validate the Python version before loading models?

Yes. The modules.core.pre_check() function (lines 177–184) validates the Python version is 3.9 or higher before any frame processors are loaded. This early validation prevents compatibility issues with type hints and asyncio patterns used in the processor modules.

How does the face swapper handle missing model files?

The face_swapper.pre_check() function in modules/processors/frame/face_swapper.py (lines 46–64) automatically downloads the inswapper_128_fp16.onnx model using conditional_download if the file is absent. It also creates the models directory and handles permission errors explicitly to provide clear user feedback if directory creation fails.

What validation occurs when clicking the Start button?

When processing begins, modules.core.start() calls pre_start() on each loaded frame processor. These functions verify that the global target_path variable points to a valid image or video file using is_image() and is_video() checks, ensuring the pipeline only processes supported media formats.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}