This page provides a comprehensive reference for all configuration options available in Deep-Live-Cam. Configuration options control processing behavior, output quality, performance characteristics, and UI appearance. They can be set through the graphical interface, command-line arguments, or by directly modifying the global state.
Deep-Live-Cam uses a centralized configuration management system where all settings converge in the modules.globals module. Configuration can originate from three sources and is persisted across sessions for UI settings.
Title: Configuration Data Flow and State Management
Sources: modules/globals.py1-74 modules/core.py40-116
| Source | Scope | Persistence | Priority |
|---|---|---|---|
| CLI Arguments | All options except UI-specific | Not persisted | Overrides defaults modules/core.py72-91 |
| UI Controls | User-facing options | Persisted to switch_states.json | Modifiable at runtime |
| Default Values | All options | Hardcoded in modules.globals | Lowest priority modules/globals.py19-71 |
All configuration variables are stored in modules.globals. This module serves as the single source of truth for the application state during runtime.
Title: Global State Organization
Sources: modules/globals.py14-73
UI toggle states and slider values are persisted to switch_states.json in the application root directory. This file is loaded on startup and written whenever a UI control changes.
Persisted Settings:
keep_fps, keep_audio, keep_frames modules/globals.py25-27many_faces, map_faces modules/globals.py28-29poisson_blend, color_correction, nsfw_filter modules/globals.py30-32live_mirror, live_resizable, show_fps modules/globals.py39-43fp_ui (face enhancer selection dict) modules/globals.py53mouth_mask, show_mouth_mask_box, mouth_mask_size modules/globals.py61-66Paths specify the input source face image, target media, and output destination.
| Variable | Type | Description | Set By |
|---|---|---|---|
source_path | str | None | Path to the source face image used for swapping | CLI -s/--source modules/core.py43 |
target_path | str | None | Path to target image or video to process | CLI -t/--target modules/core.py44 |
output_path | str | None | Path where processed output will be saved | CLI -o/--output modules/core.py45 |
Sources: modules/globals.py18-21 modules/core.py72-74
Core processing behavior flags that control how faces are detected and swapped.
| Variable | Type | Default | Description | CLI Argument |
|---|---|---|---|---|
keep_fps | bool | True | Maintain original frame rate in output video | --keep-fps modules/core.py47 |
keep_audio | bool | True | Preserve audio track from source video | --keep-audio modules/core.py48 |
keep_frames | bool | False | Retain extracted frames on disk after processing | --keep-frames modules/core.py49 |
many_faces | bool | False | Process all detected faces, not just the primary one | --many-faces modules/core.py50 |
map_faces | bool | False | Enable face mapping mode for specific source-to-target assignments | --map-faces modules/core.py52 |
poisson_blend | bool | False | Use Poisson blending for smoother face edge transitions | Not exposed in CLI modules/globals.py30 |
color_correction | bool | False | Apply color correction to fix color casts | Not exposed in CLI modules/globals.py31 |
nsfw_filter | bool | False | Enable NSFW content detection and blocking | --nsfw-filter modules/core.py51 |
Sources: modules/globals.py23-32 modules/core.py47-53
Fine-grained control over face swapping quality and appearance.
| Variable | Type | Default | Range | Description |
|---|---|---|---|---|
opacity | float | 1.0 | 0.0-1.0 | Blend factor between original and swapped face modules/globals.py57 |
sharpness | float | 0.0 | 0.0-5.0 | Sharpness enhancement applied to swapped face modules/globals.py58 |
mouth_mask_size | float | 0.0 | 0.0-100.0 | Size of mouth mask area (0=disabled) modules/globals.py66 |
mouth_mask | bool | False | - | Enable mouth area masking/pasting modules/core.py53 |
enable_interpolation | bool | True | - | Enable temporal frame interpolation for smoother video modules/globals.py69 |
interpolation_weight | float | 0.0 | 0.0-1.0 | Blend weight for current vs previous frame modules/globals.py70 |
Sources: modules/globals.py56-71 modules/core.py81
Control which face enhancement model is active. These are mutually exclusive selections stored in the fp_ui dictionary.
| fp_ui Key | Enhancement Model | Description | CLI Choice |
|---|---|---|---|
face_enhancer | GFPGAN v1.4 | Standard quality enhancement (1024x1024) | face_enhancer |
face_enhancer_gpen512 | GPEN-BFR-512 | Higher quality GPEN model (512x512) | face_enhancer_gpen512 |
face_enhancer_gpen256 | GPEN-BFR-256 | Faster GPEN model (256x256) | face_enhancer_gpen256 |
Note: The CLI argument --frame-processor updates both modules.globals.frame_processors and the fp_ui toggles during initialization.
Sources: modules/globals.py53 modules/core.py94-95
Settings that affect video encoding and output quality.
| Variable | Type | Default | Description | CLI Argument |
|---|---|---|---|---|
video_encoder | str | None | 'libx264' | FFmpeg encoder selection (libx264, libx265, libvpx-vp9) | --video-encoder modules/core.py54 |
video_quality | int | None | 18 | Video quality setting (CRF value, 0-51) | --video-quality modules/core.py55 |
Sources: modules/globals.py34-36 modules/core.py84-85
Configuration specific to real-time webcam face swapping.
| Variable | Type | Default | Description | CLI Argument |
|---|---|---|---|---|
live_mirror | bool | False | Mirror the webcam display horizontally | --live-mirror modules/core.py57 |
live_resizable | bool | False | Allow live preview window to be resized | --live-resizable modules/core.py58 |
show_fps | bool | False | Display FPS counter on live preview | Not exposed modules/globals.py43 |
Sources: modules/globals.py38-43 modules/core.py86-87
Low-level settings that control hardware acceleration and resource management.
| Variable | Type | Default | Description | CLI Argument |
|---|---|---|---|---|
execution_providers | List[str] | [] | ONNX runtime execution providers (e.g., CUDAExecutionProvider) | --execution-provider modules/core.py60 |
execution_threads | int | None | None | Number of threads for execution | --execution-threads modules/core.py61 |
max_memory | int | None | None | Maximum RAM usage in GB | --max-memory modules/core.py59 |
headless | bool | None | None | Run without GUI (CLI mode) | Implicit when paths are provided modules/core.py76 |
log_level | str | "error" | Logging verbosity | Not exposed modules/globals.py50 |
Sources: modules/globals.py45-50 modules/core.py88-90
Title: CLI Argument Parsing to Global State Mapping
Sources: modules/core.py40-116
Title: Application Lifecycle and Configuration Loading
Sources: modules/core.py72-91 modules/core.py94-96
Some configuration options are available in modules.globals but not exposed through the CLI:
| Variable | Type | Default | Description | Usage |
|---|---|---|---|---|
mask_feather_ratio | int | 12 | Denominator for mask feathering | Mouth mask blending modules/globals.py63 |
mask_down_size | float | 0.1 | Lower lip mask expansion factor | Mouth mask geometry modules/globals.py64 |
mask_size | float | 1.0 | Upper lip mask expansion factor | Mouth mask geometry modules/globals.py65 |
show_mouth_mask_box | bool | False | Visualize mouth mask bounding box | Debugging modules/globals.py62 |
webcam_preview_running | bool | False | Internal state flag for webcam preview | Runtime state modules/globals.py42 |
Sources: modules/globals.py42-66
Refresh this wiki