Skip to content

Immich and TMDB Setup

ant1fr edited this page Nov 18, 2026 · 1 revision

Immich and TMDB Setup

Create an Immich API key

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.

Pickers

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.

Immich 3.x notes

  • Searches use POST /api/search/metadata (and /api/search/smart for CLIP phrases); album contents are read through the same metadata search with albumIds, because GET /albums/{id} no longer lists assets in Immich 3.x.
  • Asset visibility is timeline, archive, hidden or locked.

The Locked Folder rule

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.

Immich

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.

Movie and TV posters (TMDB)

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.


Home · Report an issue · Roadmap

Clone this wiki locally