Deep-Live-Cam map_faces and Simple Mode: What's the Difference?

Deep-Live-Cam's map_faces processing creates explicit source-to-target face mappings for precise multi-face control, while simple mode applies a single source face to all targets using lightweight embedding matching for faster performance.

When working with the hacksider/Deep-Live-Cam repository, choosing between map_faces processing and simple mode determines how the application handles face detection and replacement workflows. These distinct regimes are controlled by the global modules.globals.map_faces flag and serve different purposes, ranging from complex collage creation requiring granular control to rapid single-face video processing or live webcam feeds.

What is map_faces Processing?

In map_faces processing (also called Mapping Mode), Deep-Live-Cam constructs a detailed source-to-target mapping table (source_target_map) that stores explicit face pairings with unique identifiers. This mode activates when you pass the --map-faces CLI flag or enable the manual mapping toggle in the UI.

According to modules/globals.py (lines 16-30), the system defines the core data structures that enable this mode:

simple_map: Dict[str, Any] = {}             # Stores simplified map for live/simple mode

map_faces: bool = False                     # Use source_target_map or simple_map

When map_faces is set to True, the Face Analyser utilities get_unique_faces_from_target_image() and get_unique_faces_from_target_video() populate modules.globals.source_target_map with unique face IDs, target cv2 crops, and comprehensive face metadata. This preprocessing step enables precise control over which specific source face replaces which target face, even across different frames in a video sequence.

The swapping logic executes in process_frame_v2() within modules/processors/frame/face_swapper.py (lines 24-30), which iterates through the pre-computed entries to handle complex scenarios including many_faces processing (modules.globals.many_faces) and per-frame mappings.

What is Simple Mode?

Simple mode (the default when --map-faces is omitted) takes a lightweight approach optimized for speed. Instead of building a comprehensive mapping table, the system either uses a streamlined simple_map containing only source faces and target embeddings, or bypasses mapping entirely when a single source face is sufficient.

In modules/processors/frame/face_swapper.py (lines 47-61), the code pre-loads a single source face once at initialization when map_faces is False:

# Logic executed when map_faces is False

source_face = get_source_face_from_image(modules.globals.source_path)

For live webcam scenarios, the system creates simple_map via the simplify_maps() function in modules/face_analyser.py (lines 63-71), which copies essential source faces and target embeddings from the full source_target_map. During processing, process_frames() performs dynamic embedding matching against simple_map on-the-fly (lines 86-100 in the face swapper) to identify the best source match for detected targets.

Key Differences Between map_faces and Simple Mode

Data Structure:

• Mapping Mode: Uses the full source_target_map dictionary with explicit source-to-target pairings, unique face IDs, and crop coordinates.
• Simple Mode: Relies on simple_map with lightweight embeddings or a single pre-loaded source face, minimizing memory overhead and startup time.

Processing Functions:

• process_frame_v2(): Executes when map_faces=True, reading the detailed source_target_map to handle specific face assignments and per-frame mappings.
• process_frames(): Runs in simple mode, applying a single source face to every frame or performing dynamic embedding matching against simple_map.

Performance Characteristics:

• Mapping Mode: Requires preprocessing (face extraction and clustering via the Face Analyser) but enables granular control over multiple distinct faces.
• Simple Mode: Offers faster startup with no preprocessing, ideal for quick "one-source-to-all-targets" swaps or live webcam processing where face similarity matching is sufficient.

Activation Method:

• Mapping Mode: Activated via --map-faces CLI flag (parsed in modules/core.py, lines 48-80) or the UI toggle in modules/ui.py (lines 328-340).
• Simple Mode: Default behavior when the flag is omitted.

How the Code Decides Which Mode to Run

The decision logic centers on the map_faces boolean defined in modules/globals.py. When modules.core.parse_args() processes the command line, it sets modules.globals.map_faces = True if --map-faces is present.

In the UI layer (modules/ui.py), a CTkSwitch controls this state at runtime:

map_faces = ctk.BooleanVar(value=modules.globals.map_faces)
map_faces_switch = ctk.CTkSwitch(
    ..., 
    variable=map_faces, 
    command=lambda: setattr(modules.globals, "map_faces", map_faces.get())
)

The face swapper (modules/processors/frame/face_swapper.py) branches accordingly at lines 17-21, printing a human-readable description of the selected mode before executing the appropriate processing path.

Practical Code Examples

Run in Simple Mode (Default)

python -m modules.run -s source.jpg -t target.mp4 -o output.mp4

This command keeps map_faces as False, triggering process_frames() to load source.jpg once and apply it to all detected faces in target.mp4 without preprocessing.

Run in Mapping Mode

python -m modules.run -s source.jpg -t target.mp4 -o output.mp4 --map-faces

This activates the full pipeline:

1. get_unique_faces_from_target_video() extracts faces and builds source_target_map
2. process_frame_v2() processes frames using the explicit mappings
3. Different source faces can be assigned to different targets across frames

UI Toggle

Enable "Manually assign which source face maps to which target face" in the interface. This sets modules.globals.map_faces = True, switching the pipeline to mapping mode at runtime without requiring CLI arguments.

Summary

• map_faces processing builds a comprehensive source_target_map for explicit multi-face control, requiring preprocessing but enabling precise assignments.
• Simple mode uses lightweight simple_map or single-source pre-loading in process_frames() for faster processing without face analysis overhead.
• The global flag in modules/globals.py controls the branch between process_frame_v2() (mapping) and process_frames() (simple).
• Face Analyser utilities (get_unique_faces_from_target_image(), get_unique_faces_from_target_video()) populate the maps, while the Face Swapper executes the appropriate logic based on the active mode.

Frequently Asked Questions

When should I use map_faces processing instead of simple mode?

Use map_faces processing when you need to swap multiple specific source faces onto different target faces within the same video or image. This mode is essential for creating collages or when you require precise control over which source replaces which target. Simple mode works best for quick portrait-to-video swaps or live webcam feeds where one source face should replace all detected targets indiscriminately.

Does map_faces processing slow down the application?

Yes, map_faces processing requires a preprocessing step where the Face Analyser extracts and clusters unique faces from the target media to populate source_target_map. This adds initial overhead but provides the granular control needed for complex multi-face scenarios. Simple mode skips this step entirely, offering significantly faster startup times.

How does the live webcam mode handle face mapping?

In live mode with map_faces=False, the system utilizes simple_map created by simplify_maps() in modules/face_analyser.py. This structure stores target embeddings and source faces for on-the-fly matching (implemented in lines 86-100 of face_swapper.py). Rather than using pre-computed frame-specific mappings, the system dynamically matches detected faces against these embeddings in real-time.

Can I switch between modes without restarting the application?

Yes. The UI toggle in modules/ui.py (lines 328-340) allows runtime switching by updating modules.globals.map_faces through the CTkSwitch command callback. However, changing modes may require re-analyzing the target media or reloading source faces depending on whether the maps have already been computed.

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