# Multi-Camera Face Tracker Alert System Capabilities: Audio, Screenshots, and Telegram Integration

> Explore the multi-camera face tracker's alert system: audio alarms, screenshots, Telegram integration, and event logs. Configure runtime alerts easily.

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

---

**The multi-camera face tracker provides a modular alert system with audio alarms, automatic screenshot capture, Telegram notifications, and comprehensive event history tracking, all configurable at runtime.**

The **aarambhdevhub/multi-cam-face-tracker** repository implements a robust `AlertSystem` class designed to notify users immediately when faces are detected across multiple camera feeds. Understanding the full **alert system capabilities** helps security developers configure real-time monitoring solutions that balance immediate local feedback with remote notification workflows.

## Core Alert System Capabilities

The `AlertSystem` component in [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) serves as the central notification hub, offering five distinct alert mechanisms that operate independently based on runtime configuration.

### Audio Alarm Notifications

The system plays configurable sound files using **pygame.mixer** whenever a detection triggers an alert. During initialization, `AlertSystem.__init__` loads the sound path from `self.alert_sound` (specified in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml)), while the `_play_alert_sound` method handles the actual audio playback.

```python

# From core/alert_system.py

def _play_alert_sound(self):
    if self.alert_enabled and self.alert_sound:
        pygame.mixer.music.load(self.alert_sound)
        pygame.mixer.music.play()

```

### Visual Documentation with Screenshots

The `_capture_screenshot` method automatically saves JPEG snapshots of the frame that triggered the alert, enabling visual verification of detected faces. This method uses **OpenCV** (`cv2.imwrite`) to write timestamped files to the configured screenshot directory.

```python

# Screenshot capability implementation

def _capture_screenshot(self, frame, face_name, camera_id):
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"{self.screenshot_dir}/alert_{camera_id}_{face_name}_{timestamp}.jpg"
    cv2.imwrite(filename, frame)
    return filename

```

### Remote Telegram Notifications

When `telegram.enabled` is set to `true` in the configuration, the system instantiates a `TelegramManager` from [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) during initialization. The `trigger_alert` method constructs formatted messages containing camera ID, face name, confidence scores, and metadata, then dispatches them via the Telegram Bot API.

```python

# Telegram integration in trigger_alert

if self.telegram and self.telegram_enabled:
    message = f"🚨 Alert: {face_name} detected on {camera_name} (ID: {camera_id})"
    self.telegram.send_alert(message, screenshot_path)

```

### Alert History and Event Tracking

The system maintains an in-memory list (`self.alert_history`) of `AlertEvent` objects, creating a complete audit trail of all detection events. Helper methods including `get_recent_alerts`, `clear_alerts`, and property accessors allow applications to query historical data without accessing the database directly.

```python

# AlertEvent tracking

class AlertEvent:
    def __init__(self, timestamp, camera_id, face_name, confidence, screenshot_path):
        self.timestamp = timestamp
        self.camera_id = camera_id
        self.face_name = face_name
        self.confidence = confidence
        self.screenshot_path = screenshot_path

```

### Runtime Configuration Toggles

Users can dynamically enable or disable specific alert modalities without restarting the application. The `enable_alerts` and `enable_screenshots` methods toggle boolean flags (`self.alert_enabled` and `self.screenshot_enabled`) that the `trigger_alert` method checks before executing notification logic.

```python

# Runtime toggles

def enable_alerts(self, enabled: bool):
    self.alert_enabled = enabled

def enable_screenshots(self, enabled: bool):
    self.screenshot_enabled = enabled

```

## Implementation Architecture

The **alert system capabilities** span multiple source files within the repository, each handling specific responsibilities:

- **[`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py)** — Central `AlertSystem` class implementing audio, screenshot, history, and Telegram coordination
- **[`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py)** — Low-level Telegram Bot API integration with rate limiting and connection management
- **[`core/face_detection.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/face_detection.py)** — Defines the `Face` data class (age, gender, bounding box) passed to alert triggers
- **[`ui/alert_panel.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/alert_panel.py)** — Desktop GUI component displaying recent alerts from the history buffer

## Configuration and Setup

All **alert system capabilities** are controlled through [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml), allowing non-developers to customize behavior without modifying source code:

```yaml
app:
  alert_sound: "assets/alert.wav"
  screenshot_dir: "screenshots"
  alert_enabled: true
  screenshot_enabled: true

telegram:
  enabled: true
  bot_token: "YOUR_BOT_TOKEN"
  chat_id: "YOUR_CHAT_ID"
  rate_limit: 1  # messages per second

```

## Practical Usage Example

The following example demonstrates the complete lifecycle of the alert system, from initialization through triggering and shutdown:

```python
from core.alert_system import AlertSystem
import yaml
import cv2
import numpy as np

# Load configuration

with open("config/config.yaml") as fh:
    cfg = yaml.safe_load(fh)

# Initialize alert system

alerts = AlertSystem(cfg)

# Simulate detection event

camera_id = 2
camera_name = "Lobby Cam"
face_name = "Alice"
confidence = 0.93

# Create dummy frame (normally from video feed)

frame = np.zeros((480, 640, 3), dtype=np.uint8)

# Trigger alert - plays sound, saves screenshot, sends Telegram message

event = alerts.trigger_alert(
    camera_id, camera_name, face_name, None, confidence, frame
)

# Query recent history

recent = alerts.get_recent_alerts(limit=5)
for e in recent:
    print(f"[{e.camera_name}] {e.face_name} detected")

# Runtime toggle - disable audio but keep screenshots

alerts.enable_alerts(False)
alerts.enable_screenshots(True)

# Graceful shutdown

alerts.shutdown()

```

## Summary

The **multi-camera face tracker alert system capabilities** provide comprehensive notification infrastructure for security applications:

- **Audio alerts** using pygame.mixer with configurable sound files
- **Automatic screenshot capture** with OpenCV timestamping and directory management
- **Telegram integration** for remote mobile notifications with rate limiting
- **In-memory alert history** tracking all detection events with metadata
- **Runtime toggles** allowing dynamic enable/disable without application restart
- **Graceful shutdown** ensuring proper resource cleanup for Telegram connections

## Frequently Asked Questions

### How do I disable audio alerts while keeping screenshot capture active?

Use the `enable_alerts()` method with `False` while keeping `enable_screenshots()` set to `True`. This toggles the `self.alert_enabled` boolean without affecting the screenshot directory or capture logic in `_capture_screenshot`.

### What file format does the screenshot capability use?

The `_capture_screenshot` method in [`core/alert_system.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/alert_system.py) saves frames as **JPEG files** using `cv2.imwrite()`. Filenames include timestamps, camera IDs, and detected face names for easy sorting: `alert_{camera_id}_{face_name}_{timestamp}.jpg`.

### Can I send alerts to multiple Telegram chats simultaneously?

The current implementation in [`core/telegram_manager.py`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/core/telegram_manager.py) supports a single `chat_id` as defined in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/config/config.yaml). To support multiple chats, you would need to modify the `TelegramManager` class to iterate over a list of chat IDs in its `send_alert` method.

### Where is the alert history stored, and how long does it persist?

Alert history is maintained in memory as a Python list (`self.alert_history`) within the `AlertSystem` class. It does **not** persist to disk automatically; the data is lost when the application terminates unless you explicitly serialize the `AlertEvent` objects using the `get_recent_alerts()` method and save them to a database or file.