# How to Set Up the Multi-Camera Face Tracker System: Complete Installation Guide

> Learn how to set up the multi-camera face tracker system with this complete installation guide. Clone the repo, install dependencies, configure settings, and launch the interface in minutes.

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

---

**To set up the multi-camera face tracker system, clone the `aarambhdevhub/multi-cam-face-tracker` repository, install dependencies from [`requirements.txt`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/requirements.txt), configure the YAML files for cameras and Telegram alerts, and execute `python main.py` to launch the PyQt5 interface.**

The multi-camera face tracker system is a Python desktop application that performs real-time face detection and recognition across multiple video streams using **InsightFace** and **OpenCV**. According to the `aarambhdevhub/multi-cam-face-tracker` source code, the system integrates **PyQt5** for the user interface, **SQLite** for persistent storage, and optional **Telegram** notifications for security alerts.

## System Architecture Overview

The codebase is organized into four distinct layers that handle everything from video capture to alert generation.

| Layer | Purpose | Core Modules |
|-------|---------|--------------|
| **Entry point** | Loads configuration, initializes logging, displays splash screen, and launches the GUI. | [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) |
| **Core services** | Manages camera threads, face detection/recognition, alert processing, and database operations. | [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py), [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py), [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py), [`core/database.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/database.py) |
| **User interface** | PyQt5 windows for live video display, controls, and historical data views. | [`ui/main_window.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/main_window.py), [`ui/face_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/face_manager.py) |
| **Utilities** | Helper functions for image conversion, drawing overlays, and configuration handling. | [`core/utils.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/utils.py) |

## Prerequisites and Installation

Follow these steps to set up the multi-camera face tracker system on a fresh machine.

### 1. Clone the Repository

```bash
git clone https://github.com/aarambhdevhub/multi-cam-face-tracker.git
cd multi-cam-face-tracker

```

### 2. Create a Virtual Environment

```bash
python -m venv venv

```

Activate the environment:

- **Linux/macOS:**
  ```bash
  source venv/bin/activate
  ```

- **Windows:**
  ```bash
  venv\Scripts\activate
  ```

### 3. Install Python Dependencies

```bash
pip install -r requirements.txt

```

The key packages are `opencv-python`, `insightface`, `PyQt5`, `loguru`, `python-telegram-bot`, and `pygame` (for sound).

### 4. Prepare Required Directories

Create the folder structure for data storage (the installer creates these automatically, but manual creation ensures proper permissions):

```bash
mkdir -p data/known_faces data/screenshots config logs

```

## Configuration Files

The system is highly configurable via two YAML files that control application behavior and video sources.

### Application Settings ([`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml))

Edit this file to set thresholds, paths, and Telegram credentials:

```yaml
app:
  name: "Multi-Cam Face Tracker"
  version: "1.0.0"
  threshold: 0.6
  screenshot_dir: "data/screenshots"
  known_faces_dir: "data/known_faces"
  database_path: "data/database.db"
  alert_sound: "assets/alert.wav"
  logo: "assets/logo.png"
  log_dir: "logs"

recognition:
  detection_threshold: 0.5
  recognition_threshold: 0.6
  max_batch_size: 8
  device: "cpu"  # Set to "cuda" if an NVIDIA GPU is available

  analysis_enabled: true
  age_estimation: true
  gender_detection: true

telegram:
  enabled: true
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"
  rate_limit: 30

```

Leave the Telegram fields empty if you do not want remote alerts.

### Camera Configuration ([`config/camera_config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/camera_config.yaml))

Define video sources, resolutions, and orientations for each camera:

```yaml
cameras:
  - id: 0
    name: "Front Camera"
    source: 0  # 0 for default webcam; use RTSP URL for IP cameras

    enabled: true
    resolution:
      width: 1280
      height: 720
    fps: 30
    rotate: 0  # Options: 0, 90, 180, 270

```

## Running the Application

Launch the tracker by executing the entry point:

```bash
python main.py

```

The application performs the following initialization sequence as implemented in [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py):

1. Loads configuration from [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml)
2. Initializes logging to `logs/app.log`
3. Displays a splash screen with the application logo
4. Instantiates `MainWindow` from [`ui/main_window.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/main_window.py)
5. Starts camera capture threads via `CameraManager` in [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py)

Once running, the interface displays live video feeds with bounding boxes, recognized names, confidence scores, and estimated age/gender attributes.

## Key Components and Source Files

Understanding the core modules helps with customization and debugging.

### [`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) – Application Entry Point

This file orchestrates startup by loading YAML configurations, setting up Loguru logging, and launching the PyQt5 event loop. It serves as the bootstrap layer that wires together all services before the GUI appears.

### [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py) – Video Capture Management

The `CameraManager` class maintains separate threads for each camera defined in [`camera_config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/camera_config.yaml). It handles RTSP streams and local webcams, manages frame queues, and provides thread-safe access to the latest frames for the face detection pipeline.

### [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) – Recognition Engine

This module initializes the **InsightFace** model and performs detection, embedding extraction, and identity matching against the `data/known_faces` directory. Key methods include `detect_faces()` for inference and `add_known_face()` for enrolling new identities at runtime.

### [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) – Notification Dispatcher

The `AlertSystem` class processes `AlertEvent` objects generated when unrecognized or specific faces are detected. It coordinates screenshot capture to `data/screenshots`, plays audio alerts via `pygame`, and dispatches Telegram messages using `python-telegram-bot`.

### [`ui/main_window.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/main_window.py) – Primary Interface

This PyQt5 window renders the camera grid, hosts control panels for threshold adjustment, and displays historical alerts pulled from [`core/database.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/database.py). It connects user actions to backend services through Qt signals and slots.

## Programmatic Usage Examples

These snippets demonstrate how to interact with the system components directly.

### Starting the Tracker Programmatically

```python
from main import main

if __name__ == "__main__":
    main()  # Equivalent to running `python main.py`

```

*Reference: [[`main.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py)](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/main.py) handles configuration loading and GUI initialization.*

### Enrolling a New Known Face at Runtime

```python
import cv2
from core.face_detection import FaceDetector

# Initialize detector with loaded configuration

detector = FaceDetector(config)
image = cv2.imread("path/to/portrait.jpg")

# Extract embedding and save to known_faces directory

detector.add_known_face(
    image=image,
    name="NewPerson",
    save_dir="data/known_faces"
)

```

*The `add_known_face` method in [[`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py)](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) handles embedding extraction and file persistence.*

### Adjusting Recognition Threshold Dynamically

```python

# Access the face detector instance from your application context

face_detector.recognition_threshold = 0.75  # Increase for stricter matching

```

*This updates the comparison threshold used in [[`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py)](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py) without restarting the application.*

### Triggering a Manual Alert

```python
from core.alert_system import AlertSystem, AlertEvent
from core.face_detection import Face
import numpy as np
import cv2

# Create a dummy Face object for testing

dummy_face = Face(
    bbox=None,
    kps=None,
    det_score=0.0,
    embedding=np.zeros(512),
    age=30,
    gender="Male"
)

# Initialize alert system

alert_system = AlertSystem(config)

# Trigger alert

event = alert_system.trigger_alert(
    camera_id=0,
    camera_name="Test Camera",
    face_name="Unknown",
    face=dummy_face,
    confidence=0.88,
    frame=cv2.imread("test_frame.jpg")
)

```

*`AlertSystem.trigger_alert` in [[`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py)](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) coordinates screenshot capture, sound playback, and Telegram notifications.*

## Summary

To successfully set up the multi-camera face tracker system:

- **Clone** the `aarambhdevhub/multi-cam-face-tracker` repository and create a Python virtual environment to isolate dependencies.
- **Install** required packages including `opencv-python`, `insightface`, `PyQt5`, and `python-telegram-bot` via [`requirements.txt`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/requirements.txt).
- **Configure** the two YAML files: [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) for application thresholds and Telegram credentials, and [`config/camera_config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/camera_config.yaml) for camera sources and resolutions.
- **Initialize** the directory structure for `data/known_faces`, `data/screenshots`, and `logs` to ensure proper file storage.
- **Launch** the application with `python main.py` to start the PyQt5 interface and begin real-time face detection across configured cameras.

## Frequently Asked Questions

### How do I add IP cameras instead of USB webcams?

Edit [`config/camera_config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/camera_config.yaml) and set the `source` field to the RTSP URL of your IP camera instead of the integer device ID. For example: `source: "rtsp://192.168.1.100:554/stream1"`. Ensure the `resolution` and `fps` values match your camera's capabilities to avoid buffer errors in [`core/camera_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/camera_manager.py).

### Can I run the face tracker without Telegram notifications?

Yes. To disable Telegram alerts, open [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml) and set `telegram.enabled` to `false` or leave the `bot_token` and `chat_id` fields empty. The `AlertSystem` class in [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) checks these settings before initializing the Telegram bot, allowing the application to run with only local sound and screenshot alerts.

### What hardware acceleration options are available?

The system supports both CPU and CUDA GPU acceleration for face recognition. In [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml), set `recognition.device` to `"cuda"` if you have an NVIDIA GPU with CUDA support. This parameter is passed directly to the InsightFace model initialization in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py), significantly improving frame processing rates when running multiple high-resolution camera streams.

### How do I enroll new faces after the application is running?

Use the built-in Face Manager accessible via the **Tools → Face Manager** menu in the PyQt5 interface. Alternatively, programmatically call `FaceDetector.add_known_face()` as implemented in [`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py), providing a clear portrait image and a label name. The system automatically extracts the 512-dimensional embedding and saves the reference image to `data/known_faces/` for persistent recognition.