# How to Configure System Settings Using config.yaml in Multi-Cam Face Tracker

> Easily configure system settings for the multi-cam-face-tracker by editing the config.yaml file. Learn how to load and initialize runtime parameters using Python.

- Repository: [AarambhDevHub/multi-cam-face-tracker](https://github.com/aarambhdevhub/multi-cam-face-tracker)
- Tags: how-to-guide
- Published: 2026-02-23

---

**To configure system settings in multi-cam-face-tracker, edit the [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) file and restart the application; the `load_config()` function in [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) parses the YAML and initializes all runtime parameters as a Python dictionary.**

The `aarambhdevhub/multi-cam-face-tracker` repository centralizes all runtime behavior in a single YAML configuration file. When you configure the system settings using [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml), you control everything from face detection thresholds and GPU acceleration to Telegram alert routing without modifying source code.

## Where Configuration Lives: The config.yaml File Structure

The application expects its configuration at **[`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml)**. During startup, [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) invokes `load_config('config/config.yaml')` to ingest settings. This function uses `yaml.safe_load` to parse the file into a Python dictionary, creates required directories for screenshots, known faces, and logs, then passes the configuration object to the **MainWindow**, logger, camera manager, and Telegram notifier.

## Core Configuration Sections

The YAML file organizes settings into three top-level keys: `app`, `recognition`, and `telegram`.

### Application Settings (`app`)

The `app` section defines global application behavior and file system paths:

- **`name`** — Human-readable application identifier (e.g., `"Multi-Cam Face Tracker"`).
- **`version`** — Current release version (e.g., `"1.0.0"`).
- **`threshold`** — Global face-match confidence threshold (e.g., `0.6`).
- **`screenshot_dir`** — Target directory for captured screenshots (e.g., `"data/screenshots"`).
- **`known_faces_dir`** — Directory containing reference images for known faces (e.g., `"data/known_faces"`).
- **`database_path`** — SQLite database file for detection logging (e.g., `"data/database.db"`).
- **`alert_sound`** — Path to the audio file played during alerts (e.g., `"assets/alert.wav"`).
- **`logo`** — Path to the splash-screen logo (e.g., `"assets/logo.png"`).
- **`log_dir`** — Directory for rotating log files (e.g., `"logs"`).

### Face Recognition Parameters (`recognition`)

The `recognition` section controls the deep learning pipeline and hardware acceleration:

- **`detection_threshold`** — Minimum confidence for the detector model (e.g., `0.5`).
- **`recognition_threshold`** — Minimum confidence for the recognizer model (e.g., `0.6`).
- **`max_batch_size`** — Number of faces processed simultaneously for GPU/CPU optimization (e.g., `8`).
- **`device`** — Compute device selection: `"cpu"` or `"cuda"` for GPU acceleration.
- **`analysis_enabled`** — Master toggle for age/gender/emotion analysis (`true` or `false`).
- **`age_estimation`** — Specific toggle for age estimation.
- **`gender_detection`** — Specific toggle for gender detection.

### Telegram Alert Integration (`telegram`)

The `telegram` section configures remote alerting via the Telegram Bot API:

- **`enabled`** — Master switch for Telegram notifications (`true` or `false`).
- **`bot_token`** — Authentication token obtained from @BotFather (keep secret).
- **`chat_id`** — Destination chat ID for alert messages.
- **`rate_limit`** — Minimum seconds between successive messages to prevent spam (e.g., `30`).

## How Configuration Loading Works

The `load_config` function in [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) orchestrates the initialization sequence. It validates file existence, parses YAML safely, and ensures the file system structure matches the configuration.

```python
from pathlib import Path
import yaml
from loguru import logger

def load_config(config_path: str) -> dict:
    with open(config_path, "r") as f:
        config = yaml.safe_load(f)

    # Ensure required directories exist

    Path(config["app"]["screenshot_dir"]).mkdir(parents=True, exist_ok=True)
    Path(config["app"]["known_faces_dir"]).mkdir(parents=True, exist_ok=True)
    Path(config["app"]["log_dir"]).mkdir(parents=True, exist_ok=True)

    return config

```

After loading, the dictionary propagates through the application: `MainWindow` receives it for UI configuration, the camera manager extracts device and threshold settings, and the Telegram notifier reads bot credentials.

## Practical Configuration Examples

### Adjusting Detection Sensitivity

To reduce false positives by requiring higher confidence scores, modify the `recognition` section:

```yaml
recognition:
  detection_threshold: 0.7   # increased from 0.5 for stricter detection

  recognition_threshold: 0.6
  max_batch_size: 8
  device: "cpu"
  analysis_enabled: true
  age_estimation: true
  gender_detection: true

```

### Disabling Telegram Notifications

To stop alert messages without removing your bot configuration:

```yaml
telegram:
  enabled: false
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"
  rate_limit: 30

```

### Switching Between CPU and GPU

For CUDA-enabled systems, change the compute device to accelerate face recognition:

```yaml
recognition:
  detection_threshold: 0.5
  recognition_threshold: 0.6
  max_batch_size: 8
  device: "cuda"   # switch from "cpu" to use GPU acceleration

  analysis_enabled: true

```

## Summary

- **Centralized configuration**: All runtime parameters live in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml), parsed by `load_config()` in [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) using `yaml.safe_load`.
- **Three main sections**: `app` (paths and global settings), `recognition` (ML pipeline and hardware), and `telegram` (alert integration).
- **Automatic directory setup**: The loader creates screenshot, known-face, and log directories automatically if they do not exist.
- **Restart required**: Changes to [`config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config.yaml) only take effect after restarting the application.

## Frequently Asked Questions

### Where is the config.yaml file located?

The configuration file is located at [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) relative to the project root. The [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) script specifically calls `load_config('config/config.yaml')` during startup to locate and parse this file.

### Do I need to restart the application after editing config.yaml?

Yes, you must restart the program for changes to take effect. The `load_config` function reads the YAML file only once during application initialization; it does not watch for file changes or hot-reload configurations while running.

### How do I switch from CPU to GPU processing?

Change the `device` key in the `recognition` section from `"cpu"` to `"cuda"`. Ensure your system has CUDA-capable hardware and the appropriate PyTorch CUDA drivers installed. You may also want to increase `max_batch_size` to utilize GPU memory efficiently.

### Can I disable specific analysis features like age estimation?

Yes, set `analysis_enabled` to `false` to disable all demographic analysis, or selectively toggle individual features by setting `age_estimation`, `gender_detection`, or related keys to `false` under the `recognition` section. This reduces computational overhead if you only need basic face detection and recognition.