Deep-Live-Cam processes every frame through an ordered pipeline of modules called frame processors. Each processor is a Python module insideDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/hacksider/Deep-Live-Cam/llms.txt
Use this file to discover all available pages before exploring further.
modules/processors/frame/ that exposes a standard interface: pre_check, pre_start, process_frame, process_image, and process_video. Processors are loaded in the order they appear on the command line (or in the GUI toggles), and the output of one becomes the input of the next.
Available processors
face_swapper
Core identity transfer. Replaces detected faces using the
inswapper_128_fp16.onnx model from InsightFace. This is the only processor active by default.face_enhancer
Upscales and restores facial detail using
GFPGANv1.4.onnx. Adds clarity and removes compression artifacts introduced by the swap.face_enhancer_gpen256
GPEN-based enhancement at 256 px internal resolution. Faster than GFPGAN; suitable for lower-end hardware or real-time use.
face_enhancer_gpen512
GPEN-based enhancement at 512 px internal resolution. Higher quality than the 256 variant at the cost of additional compute.
face_swapper
face_swapper is the foundation of the pipeline. It uses InsightFace’s inswapper_128_fp16.onnx to perform identity transfer: the face embedding from your source image is projected into the target face region of each frame.
Key behaviors:
- Single-face mode (default): only the most prominent face in the frame is swapped.
- Many-faces mode (
--many-faces): every detected face is swapped with the same source. - Map-faces mode (
--map-faces): specific source embeddings are matched to specific target faces using centroid-cluster analysis.
modules.globals:
| Control | Global | Range | Effect |
|---|---|---|---|
| Opacity | modules.globals.opacity | 0.0–1.0 | Blends the swapped face with the original. 1.0 is a full replacement; 0.0 leaves the original untouched. |
| Sharpness | modules.globals.sharpness | 0.0–5.0 | Applies GPU-accelerated sharpening to the pasted face region after blending. |
Opacity and sharpness are GUI-only controls in the current release. They are stored in
modules.globals and applied at runtime but cannot be set via CLI flags.face_enhancer (GFPGAN)
face_enhancer runs GFPGANv1.4.onnx on each face crop after swapping. GFPGAN is a generative prior designed to restore facial detail lost during compression or low-resolution capture. It is the highest-quality enhancement option but is also the most computationally expensive of the three enhancer variants.
When to use it: post-processing recorded video where quality matters more than speed, or when the source image is low resolution and the swap introduces visible degradation.
face_enhancer_gpen256 and face_enhancer_gpen512
GPEN (GAN Prior Embedded Network) operates at a fixed internal resolution—256 px or 512 px—before upscaling back to the frame resolution. The 256-px variant runs approximately 2× faster than GFPGAN and is more suited to near-real-time scenarios. The 512-px variant sits between the two in both quality and speed.| Processor | Internal resolution | Relative speed | Best use |
|---|---|---|---|
face_enhancer | ~1024 px (GFPGAN) | Slowest | High-quality offline video |
face_enhancer_gpen512 | 512 px | Medium | Balanced quality / speed |
face_enhancer_gpen256 | 256 px | Fastest | Near-real-time on mid-range GPU |
Chaining processors
Pass multiple processor names to--frame-processor to build a pipeline. Processors run in the order specified.
get_frame_processors_modules in modules/processors/frame/core.py, which validates every name against the ALLOWED_PROCESSORS set before importing the module.
Mouth mask
--mouth-mask is a special compositing mode that runs alongside any processor combination. After the full frame-processor pipeline completes, the original mouth region is feathered back over the processed result. This preserves natural lip movement and avoids the “locked mouth” artifact common in face-swap outputs.
Mouth mask tuning parameters (accessible via modules.globals):
| Parameter | Default | Description |
|---|---|---|
mask_feather_ratio | 12 | Controls feather edge width. Higher values produce a narrower blend boundary. |
mask_down_size | 0.1 | Expansion factor for the lower-lip region of the mask. |
mask_size | 1.0 | Expansion factor for the upper-lip region. |
mouth_mask_size | 0.0 | Overall mouth mask scale (0 = off, 100 = mouth-to-chin coverage). |
Performance trade-offs
- Real-time / live mode
- Offline video (quality focus)
- Balanced (GPEN)
Use
face_swapper alone. Adding any enhancer introduces a second ONNX inference pass per face crop per frame, which cuts effective throughput roughly in half on a mid-range GPU.