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

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 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), while the _play_alert_sound method handles the actual audio playback.

# 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.

# 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 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.

# 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.

# 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.

# 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 — Central AlertSystem class implementing audio, screenshot, history, and Telegram coordination
• core/telegram_manager.py — Low-level Telegram Bot API integration with rate limiting and connection management
• core/face_detection.py — Defines the Face data class (age, gender, bounding box) passed to alert triggers
• 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, allowing non-developers to customize behavior without modifying source code:

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:

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 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 supports a single chat_id as defined in 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.

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