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

To set up the multi-camera face tracker system, clone the aarambhdevhub/multi-cam-face-tracker repository, install dependencies from 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
Core services	Manages camera threads, face detection/recognition, alert processing, and database operations.	core/camera_manager.py, core/face_detection.py, core/alert_system.py, core/database.py
User interface	PyQt5 windows for live video display, controls, and historical data views.	ui/main_window.py, ui/face_manager.py
Utilities	Helper functions for image conversion, drawing overlays, and configuration handling.	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

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

2. Create a Virtual Environment

python -m venv venv

Activate the environment:

• Linux/macOS:

  source venv/bin/activate

• Windows:

  venv\Scripts\activate

3. Install Python Dependencies

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):

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)

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

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)

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

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:

python main.py

The application performs the following initialization sequence as implemented in main.py:

1. Loads configuration from 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
5. Starts camera capture threads via CameraManager in 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 – 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 – Video Capture Management

The CameraManager class maintains separate threads for each camera defined in 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 – 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 – 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 – Primary Interface

This PyQt5 window renders the camera grid, hosts control panels for threshold adjustment, and displays historical alerts pulled from 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

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) handles configuration loading and GUI initialization.

Enrolling a New Known Face at Runtime

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) handles embedding extraction and file persistence.

Adjusting Recognition Threshold Dynamically

# 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) without restarting the application.

Triggering a Manual Alert

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) 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.
• Configure the two YAML files: config/config.yaml for application thresholds and Telegram credentials, and 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 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.

Can I run the face tracker without Telegram notifications?

Yes. To disable Telegram alerts, open 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 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, 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, 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, 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.

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