How Deep-Live-Cam Parses Command-Line Arguments and Handles Deprecated Options

Deep-Live-Cam uses Python's argparse module in modules/core.py to parse CLI inputs, storing values in modules.globals while translating deprecated flags like -f to modern equivalents with warning messages.

The Deep-Live-Cam repository implements a robust command-line interface that balances modern usability with backward compatibility. Understanding how command-line arguments are parsed and how deprecated options are managed is essential for developers extending the tool or troubleshooting legacy scripts. The entire parsing workflow is centralized in modules/core.py, which orchestrates argument definition, global state management, and legacy flag translation.

Command-Line Argument Architecture in modules/core.py

The CLI implementation follows a three-phase architecture within the modules/core.py file: definition, parsing, and state assignment.

Argument Definition and Registration

All current command-line arguments are registered between lines 36 and 66 of modules/core.py. The code creates an ArgumentParser instance (referenced as program) and adds modern flags including --source, --target, --frame-processor, --execution-provider, and --execution-threads.

# Conceptual excerpt from core.py lines 36-66

parser.add_argument('-s', '--source', help='Source image path')
parser.add_argument('-t', '--target', help='Target video/image path')
parser.add_argument('-o', '--output', help='Output file path')
parser.add_argument('--frame-processor', nargs='+', default=['face_swapper'])
parser.add_argument('--execution-provider', default='cpu')

Simultaneously, deprecated arguments are registered but hidden using argparse.SUPPRESS on lines 60-65. This allows the parser to recognize legacy flags like -f, --cpu-cores, --gpu-vendor, and --gpu-threads without displaying them in help text.

Global State Assignment

After parse_args() executes, the application transfers values from the parsed namespace to the global state module. Lines 68 through 88 of modules/core.py assign these values to modules.globals, making them accessible throughout the application lifecycle:

# From core.py lines 68-88

modules.globals.source_path = args.source_path
modules.globals.target_path = args.target_path
modules.globals.output_path = normalize_output_path(args.source_path, args.target_path, args.output_path)
modules.globals.frame_processors = args.frame_processor
modules.globals.execution_threads = args.execution_threads
modules.globals.execution_providers = decode_execution_providers([args.execution_provider])

Deprecated Argument Handling Strategy

Deep-Live-Cam maintains backward compatibility through a structured deprecation pipeline that intercepts legacy flags before they reach the processing logic.

Hidden Registration of Legacy Flags

Deprecated arguments are added to the parser with the help=argparse.SUPPRESS parameter, ensuring they remain functional but invisible in --help output. This registration occurs on lines 60-65 of modules/core.py, capturing flags such as:

• -f / --face (replaced by -s / --source)
• --cpu-cores (replaced by --execution-threads)
• --gpu-vendor (replaced by --execution-provider)
• --gpu-threads (replaced by --execution-threads)

Post-Parse Translation and Warnings

The critical translation logic resides between lines 93 and 113 of modules/core.py. After argument parsing completes, the code checks for the presence of deprecated flags and performs three actions:

1. Prints a yellow warning message to console using ANSI color codes ([33m... [0m)
2. Maps the deprecated value to its modern counterpart in modules.globals
3. Recomputes dependent values (such as output_path) when necessary

The specific mappings implemented in the translation block include:

Deprecated Flag	Modern Replacement	Translation Action
-f / --face	-s / --source	Copies value to modules.globals.source_path and recomputes output path
--cpu-cores	--execution-threads	Assigns value to modules.globals.execution_threads
--gpu-threads	--execution-threads	Assigns value to modules.globals.execution_threads
--gpu-vendor apple	--execution-provider coreml	Decodes to coreml provider
--gpu-vendor nvidia	--execution-provider cuda	Decodes to cuda provider
--gpu-vendor amd	--execution-provider rocm	Decodes to rocm provider

Practical Usage Examples

Modern command-line usage follows the current argument specification:

python run.py \
    -s source_face.jpg \
    -t target_video.mp4 \
    -o output.mp4 \
    --frame-processor face_swapper face_enhancer \
    --execution-provider cuda \
    --execution-threads 8

Legacy scripts using deprecated arguments continue to function but trigger deprecation warnings:

python run.py \
    -f old_face.png \
    -t video.mp4 \
    --cpu-cores 4 \
    --gpu-vendor nvidia

Console output when using deprecated flags:

[33mArgument -f and --face are deprecated. Use -s and --source instead.[0m
[33mArgument --cpu-cores is deprecated. Use --execution-threads instead.[0m
[33mArgument --gpu-vendor is deprecated. Use --execution-provider instead.[0m

Summary

• Centralized Parsing: All command-line argument parsing occurs in modules/core.py using Python's standard argparse module.
• Global State Storage: Parsed values are immediately transferred to modules.globals (lines 68-88) for application-wide access.
• Hidden Legacy Support: Deprecated flags are registered with argparse.SUPPRESS (lines 60-65) to maintain compatibility without cluttering help text.
• Runtime Translation: Lines 93-113 implement post-parse logic that maps deprecated arguments to modern equivalents while printing yellow warning messages.
• Provider Decoding: Legacy --gpu-vendor flags are translated to modern --execution-provider values including cuda, coreml, and rocm.

Frequently Asked Questions

Where are command-line arguments defined in the Deep-Live-Cam codebase?

Command-line arguments are defined in modules/core.py between lines 36 and 66, where an ArgumentParser instance registers both current flags (like --source and --execution-provider) and deprecated hidden flags (like --face and --gpu-vendor).

What happens if I use the deprecated -f flag instead of -s?

The application accepts the -f input and prints a yellow deprecation warning to the console. According to the translation logic in lines 93-113 of modules/core.py, the value is automatically assigned to modules.globals.source_path, ensuring the face swapping operation proceeds without error.

How does Deep-Live-Cam handle legacy GPU vendor arguments?

When --gpu-vendor is detected (with values like apple, nvidia, or amd), the post-parse translation block maps these to modern execution providers (coreml, cuda, or rocm respectively), prints a deprecation warning, and sets modules.globals.execution_providers accordingly.

Where does the application store parsed arguments after processing?

After parsing completes, arguments are stored in the global state module (modules/globals.py) through direct assignment statements in modules/core.py lines 68-88. This design allows frame processors and other modules to access configuration values without passing arguments through every function call.

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