alexei.dolgolyov/haos-blueprints
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
b48d78a18874db8ac94c80ae69d9774d94fc4499
haos-blueprints/Common/Immich Album Watcher/README.md
alexei.dolgolyov b48d78a188 Add Memory Mode as separate feature with independent schedule 
Replace the previous memory order_by option with a dedicated Memory Mode
feature that has its own enable toggle, schedule (interval/start hour),
and settings. Users can now run both Scheduled Assets and Memory Mode
independently at different times.

Memory Mode fetches photos taken on today's date in previous years using
the memory_date parameter, sorted by date ascending (oldest first).

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-02 14:23:57 +03:00

274 lines
12 KiB
Markdown
Raw Blame History

# Immich Album Watcher Blueprint
This blueprint monitors Immich album changes and sends notifications when assets (photos/videos) are added to specified albums. Designed to be used in pair with the [Immich Album Watcher](https://github.com/DolgolyovAlexei/haos-hacs-immich-album-watcher) integration.
## Features
- Filter by hub/instance name (for multi-hub setups)
- Monitor specific albums by name (whitelist)
- Filter by asset type (track images only, videos only, or both)
- Send notifications to multiple targets simultaneously
- Customizable notification messages with template variables
- Separate templates for image and video assets
- Optional: include people detected in photos
- Optional: include detailed asset list with per-item formatting
- Support for multiple change types (assets added, removed, changed)
- Optional: send photos/videos as Telegram media attachments
- Optional: periodic summary notifications with album list and share URLs
## Event Data from Immich
### Assets Added/Removed/Changed Events
| Field | Description |
|-------|-------------|
| `hub_name` | Name of the Immich hub/instance that sent the event |
| `album_id` | Album ID |
| `album_name` | Album name |
| `album_url` | Public URL to view the album (only if album has shared link) |
| `change_type` | Type of change (assets_added, assets_removed, changed) |
| `added_count` | Number of assets added |
| `removed_count` | Number of assets removed |
| `added_assets` | List of added assets (see Added Assets Fields below) |
| `removed_assets` | List of removed asset IDs |
| `people` | List of all people detected in the album |
### Album Renamed Event
| Field | Description |
|-------|-------------|
| `hub_name` | Name of the Immich hub/instance that sent the event |
| `album_id` | Album ID |
| `old_name` | Previous album name |
| `new_name` | New album name |
| `album_url` | Public URL to view the album (only if album has shared link) |
### Album Deleted Event
| Field | Description |
|-------|-------------|
| `hub_name` | Name of the Immich hub/instance that sent the event |
| `album_id` | Album ID |
| `album_name` | Album name that was deleted |
## Added Assets Fields
Each item in `added_assets` contains:
| Field | Description |
|-------|-------------|
| `id` | Unique asset ID |
| `type` | Type of asset (IMAGE or VIDEO) |
| `filename` | Original filename of the asset |
| `created_at` | Date/time when the asset was originally created |
| `owner` | Display name of the user who owns the asset |
| `owner_id` | Unique ID of the user who owns the asset |
| `description` | Description/caption (user-added in Immich, or EXIF fallback) |
| `is_favorite` | Whether the asset is marked as favorite (true or false) |
| `rating` | User rating of the asset (1-5 stars, or null if not rated) |
| `url` | Public URL to view the asset (only if album has shared link) |
| `download_url` | Direct download URL for the original file (if shared link exists) |
| `playback_url` | Video playback URL (for VIDEO assets only, if shared link exists) |
| `photo_url` | Photo preview URL (for IMAGE assets only, if shared link exists) |
| `people` | List of people detected in this specific asset |
| `city` | City name from reverse geocoding (if available) |
| `state` | State/region name from reverse geocoding (if available) |
| `country` | Country name from reverse geocoding (if available) |
## Message Template Variables
All message templates support these placeholder variables (use single braces):
| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_url}` | Public URL to view the album (empty if no shared link) |
| `{album_created}` | Album creation date (formatted with date format) |
| `{album_updated}` | Album last update date (formatted with date format) |
| `{added_count}` | Number of assets added |
| `{removed_count}` | Number of assets removed |
| `{people}` | Comma-separated list of people detected |
| `{assets}` | Formatted list of added assets (using asset item template) |
| `{video_warning}` | Warning about video size limits (Telegram only, empty otherwise) |
| `{common_date}` | Common date formatted with template if all assets share same date, empty otherwise |
| `{common_location}` | Common location formatted with template if all assets share same location (requires city, state, country), empty otherwise |
## Asset Item Template Variables
These variables can be used in the image and video asset templates. Also used for Telegram media captions.
| Variable | Description |
|----------|-------------|
| `{filename}` | Original filename of the asset |
| `{description}` | Description/caption (user-added in Immich, or EXIF fallback) |
| `{type}` | Asset type (IMAGE or VIDEO) |
| `{created}` | Creation date/time (always shown) |
| `{created_if_unique}` | Creation date/time formatted with template if dates differ, empty if all same |
| `{owner}` | Owner display name |
| `{url}` | Public URL to view the asset (empty if no shared link) |
| `{download_url}` | Direct download URL for the original file |
| `{photo_url}` | Photo preview URL (for IMAGE assets only) |
| `{playback_url}` | Video playback URL (for VIDEO assets only) |
| `{people}` | People detected in this asset |
| `{album_name}` | Name of the album |
| `{album_created}` | Album creation date (formatted with date format) |
| `{album_updated}` | Album last update date (formatted with date format) |
| `{is_favorite}` | Favorite indicator (using template) if asset is favorite, empty otherwise |
| `{rating}` | User rating (1-5) or empty if not rated |
| `{location}` | Formatted location string (using location format template), empty if location data incomplete |
| `{location_if_unique}` | Location formatted with template if locations differ between assets, empty if all same or data incomplete |
| `{city}` | City name from reverse geocoding, empty if not available |
| `{state}` | State/region name from reverse geocoding, empty if not available |
| `{country}` | Country name from reverse geocoding, empty if not available |
## Telegram Media Attachments
When enabled, photos/videos are sent as media attachments to Telegram using the `immich_album_watcher.send_telegram_notification` service.
### Supported Recipients
1. **Notify Entities**: Select Telegram notify entities. Chat ID is extracted from the friendly name. Format: `"Name (123456789)"`
2. **Input Text Entities**: Select input_text entities containing chat IDs for groups/channels.
### Requirements
- Immich Album Watcher integration must be configured with Telegram bot token
- Immich album must have a shared link (to generate public asset URLs)
### Behavior
- First sends a text notification message to each Telegram chat
- Then sends photos/videos as media groups (albums) as replies to that message
- Media is downloaded from Immich and uploaded to Telegram (bypasses CORS)
- Large media lists are automatically split into multiple groups (2-10 items per group)
### Limitations
- Only assets with valid public URLs will be sent
- Telegram has a 50 MB file size limit for media
- Optional video warning can be shown when videos are present
- Media captions use the Image/Video Asset Templates
## Periodic Summary
Sends a summary notification of tracked albums at regular intervals. Album names and share URLs are automatically read from the Album ID Entity's `album_name` and `share_url` attributes (if available).
### Summary Message Template Variables
| Variable | Description |
|----------|-------------|
| `{albums}` | Formatted list of albums (using album item template) |
| `{album_count}` | Number of tracked albums |
### Album Item Template Variables
| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_id}` | Album ID |
| `{album_url}` | Share URL for the album |
| `{album_created}` | Album creation date (formatted with date format) |
| `{album_updated}` | Album last update date (formatted with date format) |
### Testing Periodic Summary
To test the periodic summary without waiting for the scheduled time, fire this event from Developer Tools > Events:
- **Event type**: `immich_album_watcher_test_periodic_summary`
To target a specific automation, set its Automation ID in config and include it in the event data:
- **Event data**: `{"automation_id": "your-automation-id"}`
## Scheduled Assets
Sends scheduled notifications with existing assets from tracked albums. Uses the `immich_album_watcher.get_assets` service to fetch assets.
### Album Modes
| Mode | Description |
|------|-------------|
| `per_album` | Send separate notifications for each tracked album |
| `combined` | Fetch assets from all albums into one notification |
| `random` | Pick one random album each time |
### Asset Filter Options
| Option | Description |
|--------|-------------|
| `limit` | Maximum number of assets to fetch (1-100) |
| `favorite_only` | Only fetch favorite assets |
| `asset_type` | Filter by type (all, photo, video) |
| `order_by` | Sort by (random, date, rating, name) |
| `order` | Sort direction (ascending, descending) |
| `filter_min_rating` | Minimum rating filter (1-5, 0 = no filter) |
| `min_date` | Assets created on or after this date (YYYY-MM-DD) |
| `max_date` | Assets created on or before this date (YYYY-MM-DD) |
### Scheduled Assets Message Template Variables
| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_url}` | Share URL for the album |
| `{album_created}` | Album creation date (empty in combined mode) |
| `{album_updated}` | Album last update date (empty in combined mode) |
| `{asset_count}` | Number of assets fetched |
| `{assets}` | Formatted list of assets (using asset item template) |
| `{common_date}` | Common date if all assets share same date |
| `{common_location}` | Common location if all assets share same location |
### Testing Scheduled Assets
To test without waiting for the scheduled time, fire this event:
- **Event type**: `immich_album_watcher_test_scheduled_assets`
To target a specific automation, set its Automation ID in config and include it in the event data:
- **Event data**: `{"automation_id": "your-automation-id"}`
## Memory Mode (On This Day)
Send scheduled notifications with photos taken on today's date in previous years - similar to "On This Day" or "Memories" features in photo apps. This is a separate feature from Scheduled Assets with its own schedule and settings.
### Memory Mode Options
| Option | Description |
|--------|-------------|
| `enable_memory_mode` | Enable/disable memory notifications |
| `interval_hours` | How often to send (1-168 hours) |
| `start_hour` | Hour of day for first notification (0-23) |
| `album_mode` | per_album, combined, or random |
| `limit` | Maximum number of assets to fetch (1-100) |
| `favorite_only` | Only fetch favorite assets |
| `asset_type` | Filter by type (all, photo, video) |
| `min_rating` | Minimum rating filter (1-5, 0 = no filter) |
### Memory Mode Message Template Variables
| Variable | Description |
|----------|-------------|
| `{album_name}` | Name of the album |
| `{album_url}` | Share URL for the album |
| `{album_created}` | Album creation date (empty in combined mode) |
| `{album_updated}` | Album last update date (empty in combined mode) |
| `{asset_count}` | Number of memory assets fetched |
| `{assets}` | Formatted list of assets (using asset item template) |
| `{common_date}` | Common date if all assets share same date |
| `{common_location}` | Common location if all assets share same location |
### Testing Memory Mode
To test without waiting for the scheduled time, fire this event:
- **Event type**: `immich_album_watcher_test_memory_mode`
To target a specific automation, set its Automation ID in config and include it in the event data:
- **Event data**: `{"automation_id": "your-automation-id"}`
## Author
Alexei Dolgolyov (dolgolyov.alexei@gmail.com)
Reference in New Issue View Git Blame Copy Permalink