How Visual and Audio Alerts Work in the Multi-Cam Face Tracker

The Multi-Cam Face Tracker coordinates notifications through a centralized AlertSystem class that uses pygame-mixer for audio playback, OpenCV for screenshot capture, and an optional Telegram integration for remote visual alerts.

The aarambhdevhub/multi-cam-face-tracker repository implements a comprehensive alert pipeline that notifies users when faces are detected across multiple camera feeds. This system separates concerns between audio notifications, visual evidence capture, and remote messaging through a dedicated alert manager. Understanding how visual and audio alerts are handled reveals the architecture behind real-time security notifications in modern computer vision applications.

AlertSystem Architecture

At the heart of the notification pipeline lies the AlertSystem class defined in core/alert_system.py. This singleton-style manager orchestrates all alert modalities through a single entry point: trigger_alert(). When a face is detected, the main application loop invokes this method with the camera ID, face metadata, confidence score, and the raw video frame.

The system uses an AlertEvent dataclass to encapsulate detection metadata, including timestamps, screenshot paths, and recognition confidence. This event object travels through the pipeline, enabling the UI to display historical alerts and ensuring Telegram messages contain complete context.

Audio Alert Implementation

Audio notifications rely on pygame-mixer to stream sound files asynchronously without blocking the video processing pipeline.

The private method _play_alert_sound() handles audio playback:

• It validates that the file specified in app.alert_sound exists before attempting playback
• Loads the audio via mixer.music.load() and plays via mixer.music.play()
• Logs errors gracefully without stopping the face detection pipeline

This non-blocking approach ensures that a corrupted sound file or missing audio hardware does not interrupt real-time video analysis.

Visual Alert Mechanisms

Visual alerts serve dual purposes: local evidence preservation and remote notification delivery.

Local Screenshot Capture

When screenshots are enabled, trigger_alert() delegates to _capture_screenshot() to persist frames to disk:

• The method writes images using OpenCV’s cv2.imwrite() to the directory specified by app.screenshot_dir
• Each screenshot is saved as a .jpg file with a unique timestamp
• The file path is attached to the AlertEvent instance for later retrieval by the UI or Telegram dispatcher

Telegram Integration

For remote monitoring, the system formats detection data into markdown-style messages containing the person’s name, age, gender, camera source, confidence percentage, and timestamp. The AlertSystem forwards both this text and the screenshot file path to TelegramManager via the send_alert() method defined in core/telegram_manager.py.

This integration is gated by the config.telegram.enabled flag, allowing deployments to operate entirely offline if desired.

UI Integration and Runtime Control

The AlertPanel class in ui/alert_panel.py provides a Qt-based interface for monitoring alert history and toggling notification preferences in real time.

Users can interact with the alert system through these public methods:

• get_recent_alerts(limit): Retrieves the latest AlertEvent instances from the internal alert_history list for display in the panel’s list widget
• enable_alerts(boolean): Toggles the alert_enabled flag to mute or unmute audio notifications
• enable_screenshots(boolean): Controls the screenshot_enabled flag without requiring an application restart

The UI formats each entry with human-readable timestamps, camera names, and confidence percentages, allowing security personnel to scan recent detections quickly.

Configuration-Driven Setup

All alert behaviors are governed by config/config.yaml, which supplies:

• alert_sound: File system path to the audio cue (e.g., .wav or .mp3)
• screenshot_dir: Destination folder for captured frames
• Telegram credentials: Bot token and chat ID for remote notifications

This declarative approach allows operators to customize alert sounds and storage locations without modifying source code.

Code Examples

Triggering an Alert from Application Code

# frame is a numpy.ndarray from OpenCV VideoCapture

# face is a Face dataclass with age, gender, and name attributes

alert_system.trigger_alert(
    camera_id=1,
    camera_name="Front Door",
    face_name="John Doe",
    face=face,
    confidence=0.93,
    frame=frame,
)

This invocation creates an AlertEvent, writes a screenshot if enabled, plays the audio cue, and dispatches a Telegram message.

Enabling and Disabling Alerts at Runtime

# Silence audio notifications during maintenance

alert_system.enable_alerts(False)

# Re-enable automatic screenshot capture

alert_system.enable_screenshots(True)

The AlertPanel invokes these same methods when users check or uncheck the corresponding UI checkboxes.

Displaying Recent Alerts

# Fetch the 10 newest detection events

alerts = alert_system.get_recent_alerts(10)

for ev in alerts:
    formatted_time = time.strftime('%Y-%m-%d %H:%M:%S', time.localtime(ev.timestamp))
    print(f"{formatted_time} – {ev.face_name} @ {ev.camera_name} (conf: {ev.confidence:.2%})")

Each entry surfaces the timestamp, recognized identity, camera source, and model confidence score.

Summary

• The AlertSystem class in core/alert_system.py serves as the single coordination point for all notifications, preventing fragmentation across the codebase.
• Audio alerts use pygame-mixer with defensive file-existence checks that log errors without crashing the video pipeline.
• Visual alerts combine OpenCV screenshot capture (cv2.imwrite()) with optional Telegram delivery via TelegramManager.send_alert().
• The AlertPanel in ui/alert_panel.py enables runtime toggling of audio and screenshot features through enable_alerts() and enable_screenshots().
• Configuration in config/config.yaml controls file paths and remote notification credentials, keeping deployment-specific settings out of the source code.

Frequently Asked Questions

How do I change the alert sound file?

Modify the alert_sound path in config/config.yaml to point to your preferred audio file. The AlertSystem._play_alert_sound() method validates the file existence before calling mixer.music.load(), ensuring the system degrades gracefully if the path is invalid.

Can I disable audio alerts while keeping screenshot capture active?

Yes. Call alert_system.enable_alerts(False) to mute audio while leaving enable_screenshots(True) active. These flags operate independently, allowing you to mix notification modalities based on your monitoring requirements.

What information is included in the Telegram alert message?

According to the implementation in core/alert_system.py, Telegram messages include the detected person’s name, age, gender, source camera name, confidence score, and timestamp. If screenshot capture is enabled, the image file is attached to the message via TelegramManager.send_alert().

How does the AlertPanel retrieve historical detection events?

The AlertPanel queries alert_system.get_recent_alerts(n), which returns the last n entries from the internal alert_history list. Each entry is an AlertEvent dataclass containing the screenshot path, timestamp, and face metadata required to populate the UI list widget.

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