Repository navigation
Immich and TMDB Setup
In Immich: Account Settings → API Keys → New API Key. Smart Frame Engine only reads: give the
key the permissions for assets (read, view), albums (read), people (read) and server info, or
simply "all" on a dedicated key. Then in the engine: Settings → Immich → Add account, enter the
URL (the address the engine can reach, e.g. http://immich:2283 on a shared Docker network or
http://192.168.1.20:2283) and the key, and press Test connection: it shows the server
version and the number of people and albums. Several accounts (yours, a partner's, a shared
library) can be combined; each has its own key.
If BLOCK_PRIVATE_URLS=true, add the Immich host to URL_ALLOWLIST.
Settings → Immich shows your people (face thumbnails) and albums as grids to tick: chosen names are written to the settings, so you never type an ID. Family Mode uses the same pickers for members, private people and private albums.
- Searches use
POST /api/search/metadata(and/api/search/smartfor CLIP phrases); album contents are read through the same metadata search withalbumIds, becauseGET /albums/{id}no longer lists assets in Immich 3.x. - Asset visibility is
timeline,archive,hiddenorlocked.
Photos in Immich's Locked Folder are never selected, by any pipeline (Smart Mix, Random Discovery, smart search, refresh), whether Family Mode is on or off. They are filtered on the search results and checked again on the full asset right before download.
Photos come from one or several Immich accounts. Pinned against
Immich 3.3.5 (/api/spec.json); payloads are parsed leniently.
# Quickstart: one account from .env (named "default")
IMMICH_URL=http://immich.lan:2283
IMMICH_API_KEY=...
# A random photo with Alice and Bob together
curl -X POST http://localhost:8080/api/display/immich -H 'Content-Type: application/json' \
-d '{"persons": ["Alice", "Bob"], "match_mode": "all"}'
# CLIP search, favorites, or an album
curl -X POST .../api/display/immich -H 'Content-Type: application/json' -d '{"mode": "search", "clip_queries": ["snowy mountains"]}'
curl -X POST .../api/display/immich -H 'Content-Type: application/json' -d '{"mode": "favorites"}'
curl -X POST .../api/display/immich -H 'Content-Type: application/json' -d '{"mode": "album", "album_name": "Holidays"}'| Request field | Meaning |
|---|---|
mode |
random (default), album, favorites or search (CLIP, needs clip_queries) |
persons, match_mode
|
Plain person names (never Home Assistant entity IDs); any or all of them |
always_include |
Names merged into every selection (e.g. a child without an HA account). Defaults to immich.always_include; send [] to switch it off |
album_name / album_id
|
Restrict to an album (names are case-insensitive) |
accounts |
Limit to some accounts |
fit, push_to_fraimic
|
Fit override, push to the frame (default true) |
ignore_history |
Allow photos shown within anti_repeat_days or taken close to one |
skip_quality_gate |
Skip the suitability check (default: skipped in album mode, checked otherwise) |
taken_after, taken_before
|
Only photos taken in this range (ISO 8601 with a timezone) |
on_this_day |
Memories: {"window_days": 3, "years_back": 10, "min_years_ago": 1} around today's date in past years (exclusive with the date range) |
ephemeral, hold_minutes
|
Temporary push: do not remember it as the rule to replay; keep it up at least this long (see Smart Mix) |
Unset filters fall back to the immich section of the settings. All modes share one
query path, so persons, albums and favorites combine freely.
Accounts. immich.accounts is a named map (url + api_key); IMMICH_URL /
IMMICH_API_KEY seed an account called default (saved settings win over .env). API keys
are masked in GET /api/config, and sending the masked view back keeps the stored key.
{"immich": {
"accounts": {"home": {"url": "http://immich.lan:2283", "api_key": "..."},
"partner": {"url": "https://photos.example.org", "api_key": "..."}},
"always_include": ["Kid"],
"person_aliases": {"Marie": {"partner": ["Maman", "0b7e1c3a-0000-0000-0000-000000000000"]}}
}}People. Names are resolved per account from GET /api/immich/people (cached for
people_cache_ttl_s, refresh with POST /api/immich/people/refresh). Two people with the
same name in one account are rejected with a hint to pin an ID in person_aliases;
unknown names get "did you mean" suggestions. person_aliases maps a canonical name to
IDs or names that exist in a given account.
Selection. Candidates of all accounts are merged, de-duplicated by content checksum
(the same photo in two accounts counts once) and filtered by the anti-repeat history
(immich.anti_repeat_days, shared across accounts), then one is picked at random. The
original is downloaded at full resolution (HEIC works); RAW files and files larger than
MAX_UPLOAD_MB use Immich's converted JPEG (fullsize, then preview).
Quality gate. Rather than force an unsuitable image onto a 6-color panel, photos are
vetted before the full-size download, using a ~250 px thumbnail and metadata (no pixels
are ever modified; about 10 ms of NumPy per candidate, and normally one candidate is
enough). Rejected: blank/near-black frames, tiny images (short side below
quality.min_dimension, default 600 px), screenshots and graphics (no camera EXIF and a
large bright flat area or a tall phone-screen shape) and document scans. Kept on purpose:
black-and-white portraits, night shots, scanned family photos and low-contrast snow
scenes. Thresholds come from a calibration on ~400 real photos (4.3% rejected) and live in
the quality settings section. If none of quality.candidates_checked (default 8)
passes, the rules relax in four steps (halve the size limit, drop the phone-shape and
document rules, keep only blank and flat-color screenshots, keep only blank) so a request
never dead-ends; the outcome is reported in the image details under suitability
(level, checked, rejected). A thumbnail that cannot be read never blocks a photo.
Burst cooldown. The history stores each photo's capture time. After a photo was
shown, others taken within immich.burst_cooldown_hours (default 2) of it are skipped for
immich.burst_cooldown_days (default 3), so rapid-fire shots of one moment are not shown
back-to-back while other photos of the same trip can still appear later (0 for either
setting disables it; ignore_history bypasses it). The exact-repeat memory stays
anti_repeat_days (default 30).
Face-aware crop. Face boxes of the requested people drive smart_crop (all faces are
the fallback), padded by 25% for hair and shoulders. When two faces are too far apart for
the crop window, the larger one is kept whole instead of slicing both. Edited Immich assets
are cropped without face boxes.
| Endpoint | Purpose |
|---|---|
POST /api/display/immich |
Select, render, deliver and record a photo |
GET /api/immich/albums |
Albums across accounts (?accounts=) |
GET /api/immich/people / POST /api/immich/people/refresh
|
Resolved people per account, ambiguity and alias mapping |
GET /api/immich/* requires the API key (or a login) when authentication is on (it lists family member
names). A LAN Immich needs URL_ALLOWLIST when BLOCK_PRIVATE_URLS=true.
POST /api/display/tmdb finds a movie or series on TMDB
(TMDB_API_KEY: a v3 API key or a v4 read access token) and shows its best poster with the
poster template.
curl -X POST http://localhost:8080/api/display/tmdb -H 'Content-Type: application/json' \
-d '{"query": "Le Fabuleux Destin d'"'"'Amélie Poulain", "media_type": "movie", "year": 2001}'
curl -X POST .../api/display/tmdb -H 'Content-Type: application/json' \
-d '{"query": "The Office", "media_type": "tv", "season": 3, "language": "en-US"}'| Request field | Meaning |
|---|---|
query (or title) |
Movie or series title |
media_type |
movie, tv or multi (both, default; auto is accepted) |
year, season
|
Release year; TV season whose poster is preferred (falls back to the series poster) |
language |
Overrides tmdb.language (default fr-FR), e.g. fr-CA
|
fallback_url, fallback_base64
|
Picture used when TMDB has nothing, e.g. the Home Assistant entity_picture (base64 is tried first) |
ephemeral, ttl_minutes, hold_minutes
|
Temporary by default: the previous image returns after ttl_minutes (default tmdb.ephemeral_ttl_minutes, 180) |
push_to_fraimic |
false only renders a preview |
Regional posters. TMDB tags posters with a language and, for regional variants, a
country (fr/FR for France, fr/CA for Québec). For fr-FR, posters are ranked:
exact language and region, then the same language (any or no region), then textless
artwork, then English, then anything else. Within a tier, posters at least as large as
their on-panel size come first (a smaller one would have to be enlarged and look soft),
then the best rated (vote_average, then vote_count).
Resolution. With tmdb.image_size: auto (default), the poster's on-panel width is
computed for the configured panel and orientation (987 px on a 13.3" portrait frame,
1296 px on a 31.5" one) and the smallest TMDB size that covers it and is a real downscale
of the original is downloaded (w780 or w1280), else the original. TMDB silently
upscales when asked for more pixels than the original has, so a bigger size is never
requested for a small original. details.poster_size and details.poster_original_width
report the choice.
Fallbacks. When TMDB is not configured, has no match or fails: fallback_base64 /
fallback_url, then ./data/assets/tmdb_fallback.png if you provide one, then a title card
(set tmdb.fallback_title_card: false to get the TMDB error instead). details.fallback
tells which one was used.
A non-ephemeral poster ("ephemeral": false) becomes the rule replayed by
POST /api/refresh, and "kind": "tmdb" entries can join the Smart Mix
({"kind": "tmdb", "params": {"query": "Amélie", "media_type": "movie"}, "weight": 1}).
POST /api/display/media is a deprecated alias.