EspFrame Smart Photo Filters for Immich
Open the device web UI at http://<device-ip>/ and use Filters. Start with the seven Filter by switches, then open only the groups you need. To use On This Day memories, open the Memories panel and turn on Show Memories Only. Dates, albums, people, tags, favorites, ratings, and location retain their saved values when switched off. Changes apply automatically shortly after you change a control.
| Setting | Default | Format | Description |
|---|---|---|---|
| Photo Source (legacy compatibility) | All Photos | Select | Legacy compatibility source value; enable Memories from the dedicated Memories panel and use the Filters panel for the remaining photo sources. |
| Memories Window | ±2 Days | Same Day, ±1 Day, ±2 Days, ±3 Days, or ±7 Days | When Memories is enabled, search this calendar-day window across prior years. |
| Fallback to All Photos | On | Toggle | When Memories has no result or fails, show an unfiltered All Photos result. |
| Filter by Albums | False | Toggle | Enable filtering by any selected album while preserving the list when disabled. |
| Filter by People | False | Toggle | Enable filtering by any selected person while preserving the list when disabled. |
| Filter by Tags | False | Toggle | Enable filtering by any selected tag while preserving the list when disabled. |
| Filter by Favorites | False | Toggle | Enable favorite filtering while preserving the selected favorite mode when disabled. |
| Filter by Rating | False | Toggle | Enable minimum rating filtering while preserving the selected rating when disabled. |
| Filter by Location | False | Toggle | Enable country, state or province, and city filtering as one group. |
| Inclusion Groups | Match all enabled groups | Select | Require every enabled album, people, and tag group, or rotate evenly through one enabled group per request. |
| Album Matching | Any selected album | Select | Legacy compatibility value; the Filters panel always uses any selected album. |
| Person Matching | Any selected person | Select | Legacy compatibility value; the Filters panel always uses any selected person. |
| Legacy Tag Matching | Any selected tag | Select | Legacy compatibility value; the Filters panel always uses any selected tag. |
| Favorites | Any | Select | Include any photo, require favorites, or exclude favorites. |
| Minimum Rating | Any | Select | Require at least the selected Immich rating; available with Immich 3.2 or newer. |
| Country | Exact text, up to 96 characters | Require an exact Immich country value. | |
| State or Province | Exact text, up to 96 characters | Require an exact state or province value. | |
| City | Exact text, up to 96 characters | Require an exact city value. | |
| Album Order | Random albums | Select | Choose whether multiple albums are sampled randomly or cycled in the order shown in the Albums list. |
| Source | Extra setup | Best for |
|---|---|---|
| All Photos | None | Whole library |
| Favorites | Mark favorites in Immich | Curated highlights |
| Album | One or more album UUIDs | Specific albums |
| Person | One or more person UUIDs | Photos of specific people |
| Tag | One or more tag UUIDs | Photos with specific Immich tags |
| Memories | Immich memory.read permission | On This Day photos from prior years |
| Custom | Combine any controls | A composed smart filter |
All Photos
Shows photos sampled across your entire Immich library. Set Source to All Photos; leave Albums, People, and Tags empty.
Favorites
Shows only photos marked with the heart in Immich, sampled across the full favorites list. Set Source to Favorites. Ensure at least some photos are favorited.
Album
Shows photos from one or more Immich albums. Get the UUID: open the album in Immich — the URL is .../albums/<uuid>. Paste one UUID into Albums, then optionally add a short description in What is it?. Use Add an album to add another album if needed.
The descriptions are saved with the IDs so the web UI can show friendly labels later. They do not affect which photos Immich returns.
Album photos are sampled through paged Immich search, using legacy page numbers or structured cursors as appropriate, so large albums are not limited to the first small batch of results. Shared albums are sampled across photos added by every contributor, not only the account used by the frame's API key.
When you add more than one album, Album Order can either keep sampling albums randomly or cycle through the Albums list from top to bottom. Use the move buttons beside each album to set the list order. Photos inside each selected album are still chosen randomly.
Each frame makes its own random photo selections and shuffles cached photo batches locally. Two frames can use the same albums or tags without sharing a fixed photo sequence. No extra shuffle setting is needed. Random selections can repeat, and frames can occasionally show the same photo; this does not guarantee different photos in every room or a full album pass before repeats.
Person
Shows photos where specific people (faces) appear. Requires face recognition in Immich. Get the UUID: open the person under People — the URL is .../person/<uuid>. Paste one UUID into People, then optionally add the person's name in Who is it?. Use Add a person to add another person if needed. With several IDs, each new image is chosen from one of those people at random, so you see photos featuring any of them (not only photos where everyone appears together). Your API key needs person.read.
The names are saved with the IDs so the web UI can show friendly labels later. They do not need to match the name stored in Immich.
Person photos use Immich's random search across the selected person. When you add several people, EspFrame chooses one person for each photo instead of asking Immich for photos containing every selected person.
Tag
Shows photos assigned to one or more Immich tags. Get the UUID: open the tag in Immich — the URL is typically .../tags/<uuid>. Paste one UUID into Tags, then optionally add a short description in What tag is it?. Use Add a tag to add another tag if needed. Your API key needs tag.read.
Multiple selected tags use Any selected tag, so the slideshow includes photos from across the selected tags. Albums and people use the same any-selected behavior. The old matching settings remain stored for compatibility but are no longer shown in the web UI.
Memories / On This Day
Turn on Show Memories Only in the Memories panel to show photos from the same calendar day in prior years, using Immich's On This Day memories. The frame searches the selected day plus or minus the configured Memories Window: Same Day, ±1 Day, ±2 Days, ±3 Days, or ±7 Days. The default is ±2 Days.
Configured Memories window: Same Day through ±7 Days; default ±2 Days; matched across prior years.
Memories is an exclusive source. While it is enabled, all saved content filters—date, albums, people, tags, favorites, ratings, location, inclusion/exclusion rules, and album order—are ignored. Their values are preserved while Memories is active. Selecting Custom restores the composed filter; selecting a legacy preset such as All Photos, Favorites, Album, Person, or Tag applies that source's documented preset. Orientation, display mode, metadata, and portrait pairing are independent display options and remain available.
If no memory is found, or Immich cannot answer the memory request, Fallback to All Photos shows an unfiltered photo instead. Turn fallback off to keep the frame on its current photo and show the empty-state message when the selected window has no result. The frame needs the memory.read API permission for this source.
Fallback behavior: Falls back to unfiltered All Photos when the selected Memories window has no result or the Memories request fails.
Album, Person, and Tag ID limits
The device stores each of Album IDs, Album Labels, Person IDs, Person Labels, Tag IDs, and Tag Labels as a single text field with a 255 character maximum. For IDs, that is about six full UUIDs plus commas. The web UI blocks longer lists and shows an error so values are not silently cut short.
Saving multiple IDs uses an HTTP POST body for the value, so the request stays within URL length limits and avoids errors such as 414 URI Too Long.
Immich compatibility
EspFrame discovers the server version from Immich's public server-version endpoint. Immich 3.2 and newer support minimum ratings and exclusions. On older or unknown versions those controls show a clear compatibility message, saved values remain intact, and the frame refuses to silently omit an active unsupported rule.
The deprecated Photos: Source Home Assistant entity remains for one compatibility release as a preset adapter. Memories is supported as an active source again; selecting it disables the saved content filters without deleting their values. Selecting a legacy source resets the smart filter to that preset, while a composed filter reports Custom.
Date Filtering
Use Filters → Filter by Date in the web UI to limit photos by when they were taken. You can use either fixed dates, such as a specific holiday range, or a rolling range, such as the last 6 months.
Date filter changes save automatically shortly after you change a control. You do not need to click an Apply button.
Date filtering is ignored while Show Memories Only is enabled; the Memories Window controls the calendar-day search instead. Your date-filter settings remain saved for when you turn Memories off.
| Setting | Default | Format | Description |
|---|---|---|---|
| Filter by Date | Off | Toggle | Turns date filtering on or off. When off, saved date values are ignored. |
| Mode | Fixed Range | Select | Choose whether to use fixed dates or a relative range ending today. |
| From | (empty) | YYYY-MM-DD | In fixed mode, only show photos taken on or after this date. Leave empty for no lower bound. |
| Until | (empty) | YYYY-MM-DD | In fixed mode, only show photos taken on or before this date. Leave empty for no upper bound. |
| Last | 1 | Number | In relative mode, the amount of time to include. |
| Unit | Years | Months or Years | In relative mode, whether the amount is counted in months or years. |
Fixed mode and relative mode are mutually exclusive, so relative ranges do not combine with the fixed From or Until dates.
Fixed Range
Use Fixed Range when you want a specific window of time. For example:
- Set From to
2024-12-01and Until to2024-12-31to show photos taken during December 2024. - Leave From empty and set Until to
2020-12-31to show photos taken up to the end of 2020. - Set From to
2023-01-01and leave Until empty to show photos from 2023 onwards.
Relative Range
Use Relative Range when you want the filter to move forward automatically over time. Set Last to a number and choose Months or Years.
Examples:
- Last
6, UnitMonthsshows photos from the last 6 months. - Last
1, UnitYearsshows photos from the last year. - Last
2, UnitYearsshows photos from the last 2 years.
The relative range ends on today, using the frame's configured time. Set Timezone under Clock so "today" matches your local day.
TIP
Use relative mode for ranges like the last 6 months, last 1 year, or last 2 years so the lower bound moves forward automatically.
Portrait Pairing
Use Portrait Pairing to display compatible portrait photos side-by-side on landscape screens.
| Setting | Default | Description |
|---|---|---|
| Portrait Pairing | On | Pairs compatible portrait photos side-by-side on landscape screens. |
| Show Paired Portraits Only | Off | Skip portrait photos unless both images in a compatible pair are ready; landscape photos are unaffected. |
| Pairing Range | Same Day | Choose whether portrait companions can be taken on the same day or up to one or two calendar days either side. |
Portrait pairing is disabled while the screen is in portrait rotation.
Pairing Range always checks the same calendar day first. EspFrame first samples up to 20 assets and chooses the compatible portrait closest to the primary photo's capture time. With ±1 Day or ±2 Days, it broadens the search only when it cannot find a same-day companion. If those fast samples miss, EspFrame paginates through every eligible asset until it finds a compatible portrait, so large or shared albums do not produce false "no companion" results. The range is kept inside any date filter you have configured, and the companion uses the exact album, person, or tag chosen for the primary photo.
Turn on Show Paired Portraits Only to skip a portrait when a complete pair cannot be loaded. Landscape photos continue to display normally. While EspFrame searches for another eligible photo, the last successfully displayed photo stays on screen.
Photo Display
Use Photo Display to control how photos are fitted to the screen.
| Setting | Default | Description |
|---|---|---|
| Display Photos | Any | Choose any photo, portrait-only photos, or landscape-only photos. Portrait-only is useful when the frame is mounted vertically. |
| Display Mode | Crop to fit | Crop to fit fills the screen and may crop edges; Show full image letterboxes without cropping. |
| Transition | Cross Fade | Animation used when the photo changes. Random picks a different transition for each photo. |
| Transition Speed | Fast | How long each transition takes: Fast (0.5s), Normal (1s), or Slow (1.5s). |
Transition options: Cross Fade blends the old photo into the new one; Fade to Black and Fade to White fade out to a solid colour before the new photo fades in; Slide moves the new photo in over the old one, and runs in the opposite direction when you swipe back. When a portrait photo is joined by its pair, the pair cross-fades in instead of moving.
Metadata
Use Metadata in the Immich section of the web UI to control the photo information shown over the current image.
| Setting | Default | Description |
|---|---|---|
| Location | On | Shows the photo location when Immich has location data for the image. |
| Date | On | Shows the photo date. |
| Date Format | Date Taken | Choose whether the date uses the photo's taken date or a relative age. |
| Date Taken Format | 1 January, 2026 | Choose the display style used when Date Format is set to Date Taken. |
Frequency
Use Frequency in the web UI to control slideshow timing and disconnect handling.
| Setting | Default | Description |
|---|---|---|
| Slideshow Interval | 15 seconds | How long each photo is shown before advancing (10 seconds to 24 hours). |
| Connection Timeout | 10 minutes | How long the frame waits without successfully displaying a new photo before showing the connection-failed screen (30 seconds to 30 minutes). |
Increase Connection Timeout if you have a slow server or large photo library and see false disconnects.
Before showing the connection-failed screen, EspFrame retries temporary Immich errors. If Immich returns an API key error, the frame shows Invalid API Key; otherwise it shows Unable to connect to Immich.
