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

> Discover how the Multi-Cam Face Tracker handles visual and audio alerts using pygame-mixer, OpenCV, and optional Telegram integration. Learn about its centralized AlertSystem.

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

---

**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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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

```python

# 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

```python

# 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

```python

# 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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/ui/alert_panel.py) enables runtime toggling of audio and screenshot features through `enable_alerts()` and `enable_screenshots()`.
- Configuration in [`config/config.yaml`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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`](https://github.com/aarambhdevhub/multi-cam-face-tracker/blob/main/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.