# Notifier
{% hint style="info" %}
This API Reference is based on DeGirum Tools version 1.2.0.
{% endhint %}
## Notification Analyzer Module Overview
This module provides tools for generating and delivering notifications based on AI inference events. It implements the `EventNotifier` analyzer for triggering notifications and optional clip saving on events.
Key Features
* Event-Based Triggers: Generates notifications when user-defined event conditions are met
* Message Formatting: Supports `${expression}` fields for dynamic notification content
* Holdoff Control: Configurable time/frame windows to suppress repeat notifications
* Video Clip Saving: Optional video clip saving with local or cloud storage
* Visual Overlay: Annotates active notification status on images
* File Management: Handles temporary file cleanup and storage integration
Typical Usage
1. Configure notification service. For external services, use Apprise URL or config file. For console output, use "json://console" as notification\_config
2. Define event conditions and create `EventNotifier` instances
3. Process inference results through the notifier chain
4. Notifications are sent when conditions are met
Integration Notes
* Requires `EventDetector` analyzer in the chain to provide event detection
* Optional dependencies (e.g., apprise) must be installed for external notification services
* Storage configuration required for clip saving (supports both local and cloud storage)
* Supports both frame-based and time-based notification holdoff periods
Key Classes
* `EventNotifier`: Analyzer for triggering notifications based on event conditions
Configuration Options
* `notification_config`: Apprise URL or config file for notification service, or "json://console" for stdout output
* `notification_title`: Default title for notifications
* `holdoff_frames`: Number of frames to wait between notifications
* `holdoff_seconds`: Time in seconds to wait between notifications
* `clip_save`: Enable/disable video clip saving
* `storage_config`: Storage configuration for clip saving (supports local and cloud storage)
* `show_overlay`: Enable/disable visual annotations
Message Formatting
* Use `${expression}` fields in the `message` parameter to include dynamic content (e.g., `${time}` for the time the notification was sent)
* Use markdown formatting for rich text notifications (e.g. `**bold**`, `*italic*`, `[link](url)`)
* Supported variables to use in `${expression}` fields include:
* `${result}`: The inference result
* `${time}`: The time the notification was sent
* `${url}`: The URL of the uploaded file
* `${filename}`: The name of the uploaded file
Example
For local storage configuration:
{% code overflow="wrap" %}
```
clip_storage_config = ObjectStorageConfig(
endpoint=".", # path to local folder
access_key="", # not needed for local storage
secret_key="", # not needed for local storage
bucket="my_bucket_dir", # subdirectory name for local storage
)
```
{% endcode %}
## Classes
## EventNotifier
`EventNotifier`
Bases: `ResultAnalyzerBase`
Analyzer for event-based notifications.
Works in conjunction with an `EventDetector` analyzer by examining the `events_detected` set in the inference results. Generates notifications when user-defined event conditions are met.
Features
* Message Formatting: supports `${expression}` fields for dynamic notification content.
* Holdoff to suppress repeat notifications within a specified time/frame window
* Optional video clip saving upon notification trigger with local or cloud storage
* Records triggered notifications in the result object's `notifications` dictionary
* Overlay annotation of active notification status on images
### EventNotifier Methods
#### \_\_init\_\_(name, ...)
`__init__(name, condition, *, message='', notify_while_true=False, holdoff=0, notification_config=None, notification_tags=None, show_overlay=True, annotation_color=None, annotation_font_scale=None, annotation_pos=AnchorPoint.BOTTOM_LEFT, annotation_cool_down=3.0, clip_save=False, clip_sub_dir='', clip_duration=0, clip_pre_trigger_delay=0, clip_embed_ai_annotations=True, clip_target_fps=30.0, storage_config=None, notification_timeout_s=None)`
Constructor.
Parameters:
| Name | Type | Description | Default |
| --------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| `name` | `str` | Name of the notification. | *required* |
| `condition` | `str` | Python expression defining the condition to trigger the notification (references event names from `EventDetector`). | *required* |
| `message` | `str` | Notification message format string. If empty, uses "Notification triggered: {name}". Default is "". | `''` |
| `notify_while_true` | `bool` | Whether to notify continuously while the condition is true. Default is False: notify only when condition changes from False to True. | `False` |
| `holdoff` | `int \| float \| Tuple[float, str]` | Holdoff duration to suppress repeated notifications. If int, interpreted as frames; if float, as seconds; if tuple (value, "seconds"/"frames"), uses the specified unit. Default is 0 (no holdoff). | `0` |
| `notification_config` | `str` | Notification service config file path, Apprise URL, or "json://console" for stdout output. If None, notifications are not sent to any external service. | `None` |
| `notification_tags` | `str` | Tags to attach to notifications for filtering. Multiple tags can be separated by commas (for logical AND) or spaces (for logical OR). | `None` |
| `show_overlay` | `bool` | Whether to overlay notification text on images. Default is True. | `True` |
| `annotation_color` | `tuple` | RGB color for the annotation text background. If None, uses a complementary color to the result overlay. | `None` |
| `annotation_font_scale` | `float` | Font scale for the annotation text. If None, uses the default model font scale. | `None` |
| `annotation_pos` | `AnchorPoint \| Tuple[int, int] \| List[int]` | Position to place annotation text (either an AnchorPoint or an (x,y) coordinate). Default is AnchorPoint.BOTTOM\_LEFT. | `BOTTOM_LEFT` |
| `annotation_cool_down` | `float` | Time in seconds to display the notification text on the image. Default is 3.0. | `3.0` |
| `clip_save` | `bool` | If True, save a video clip when the notification triggers. Default is False. | `False` |
| `clip_sub_dir` | `str` | Subdirectory name in the storage bucket for saved clips. Default is "" (no subdirectory). | `''` |
| `clip_duration` | `int` | Length of the saved video clip in frames. Default is 0 (uses available frames around event). | `0` |
| `clip_pre_trigger_delay` | `int` | Number of frames to include before the trigger event in the saved clip. Default is 0. | `0` |
| `clip_embed_ai_annotations` | `bool` | If True, embed AI annotations in the saved clip. Default is True. | `True` |
| `clip_target_fps` | `float` | Frame rate (FPS) for the saved video clip. Default is 30.0. | `30.0` |
| `storage_config` | `ObjectStorageConfig` | Storage configuration for clip saving. For local storage, use endpoint="./" and local directory as bucket. For cloud storage, use S3-compatible endpoint and credentials. If None, clips are only saved locally. | `None` |
| `notification_timeout_s` | `float` | Maximum time in seconds to wait for a notification job to complete before marking it as timed out. If None, uses the default timeout. | `None` |
Raises: ValueError: If holdoff unit is not "seconds" or "frames". ImportError: If required optional packages are not installed.
Message Formatting
* Use `${expression}` fields in the `message` parameter to include dynamic content (e.g., `${time}` for the time the notification was sent)
* Use markdown formatting for rich text notifications (e.g. `**bold**`, `*italic*`, `[link](url)`)
* Supported variables to use in `${expression}` fields include:
* `${result}`: The inference result
* `${time}`: The time the notification was sent
* `${url}`: The URL of the uploaded file
* `${filename}`: The name of the uploaded file
* `re` and `json` modules are also available for advanced formatting
#### analyze(result)
`analyze(result)`
Evaluate the notification condition on the given inference result.
If the condition is satisfied (and not within a holdoff period), generates a notification message and stores it in `result.notifications`. Optionally saves a video clip when a notification is triggered, and schedules that clip for upload if storage is configured. This method modifies the input result object in-place.
Parameters:
| Name | Type | Description | Default |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ---------- |
| `result` | [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | The inference result to analyze, which should include events detected by an `EventDetector`. | *required* |
Returns:
| Type | Description |
| ------ | ------------------------------------------------------ |
| `None` | This method modifies the input result object in-place. |
Raises:
| Type | Description |
| ---------------- | ----------------------------------------------------------------------------- |
| `AttributeError` | If the result does not contain events\_detected (EventDetector not in chain). |
#### annotate(result, ...)
`annotate(result, image)`
Draws the active notification message on the image.
Only draws the message if the notification is currently active and within its cool-down period.
Parameters:
| Name | Type | Description | Default |
| -------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ---------- |
| `result` | [InferenceResults](https://docs.degirum.com/pysdk/user-guide-pysdk/api-ref/postprocessor#degirum.postprocessor.inferenceresults) | The inference result object (may contain a notification entry). | *required* |
| `image` | `ndarray` | The image frame (BGR format) to annotate. | *required* |
Returns:
| Type | Description |
| --------- | -------------------------------- |
| `ndarray` | np.ndarray: The annotated image. |
#### finalize
`finalize()`
Finalize and clean up resources.
Waits for all background clip-saving threads to finish, stops the notification server, and removes the temporary clip directory if it was used.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.degirum.com/degirum-tools/analyzers/notifier.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.