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

> Discover the difference between Deep-Live-Cam map_faces and simple mode. Learn how map_faces offers precise multi-face control while simple mode delivers faster performance with single-face application.

- Repository: [Kenneth Estanislao/Deep-Live-Cam](https://github.com/hacksider/Deep-Live-Cam)
- Tags: deep-dive
- Published: 2026-03-01

---

**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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/globals.py) (lines 16-30), the system defines the core data structures that enable this mode:

```python
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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`:

```python

# 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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/core.py), lines 48-80) or the UI toggle in [`modules/ui.py`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/modules/ui.py)), a CTkSwitch controls this state at runtime:

```python
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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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)

```bash
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

```bash
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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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`](https://github.com/hacksider/Deep-Live-Cam/blob/main/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.