Skip to content

Configuration Reference

ant1fr edited this page Nov 18, 2026 · 2 revisions

Configuration Reference

How settings are stored

Settings live in /data/config.json (JSON, not YAML), edited from Settings in the web UI or with GET / PUT /api/config. Precedence, highest first:

  1. values saved in config.json (everything you change in the UI);
  2. environment variables / .env (IMMICH_URL, FRAIMIC_HOST... seed the first run);
  3. built-in defaults.

POST /api/config/reset removes the saved values so the environment applies again. GET /api/config/schema returns the JSON schema the UI is built from. Secrets (Immich and TMDB keys) are masked in every response and left unchanged when you send the mask back.

All settings

Generated from the application's models, so it matches the code of the release.

Setting Type Default Description
immich section
immich.accounts dict[str, ImmichAccountConfig] {} Immich accounts by name (IMMICH_URL/IMMICH_API_KEY seed one named 'default')
immich.persons list[str] [] Default person names filter
immich.always_include list[str] [] Person names merged into every selection (e.g. children without a Home Assistant presence), unless a request overrides them
immich.match_mode Literal['any', 'all'] "any" Match photos containing any or all of the persons
immich.person_aliases dict[str, dict[str, list[str]]] {} Canonical person name -> account name -> person IDs or names in that account (disambiguates duplicate or differently named people)
immich.album str "" Default album name filter (empty = all)
immich.favorites_only bool false Only pick favorite assets
immich.exclude_archived bool true Skip archived assets
immich.anti_repeat_days int 30 Do not show the same photo again within N days
immich.burst_cooldown_hours float 2.0 After a photo was shown, skip photos taken within this many hours of it (rapid-fire shots of one moment); 0 = off
immich.burst_cooldown_days int 3 How long a shown photo blocks others from its burst (days); 0 = off. Shorter than anti_repeat_days so other photos of the same trip can appear later
immich.people_cache_ttl_s int 3600 How long the people list is cached (0 = off)
immich.search_candidates int 40 Candidates fetched per search before picking one
tmdb section
tmdb.api_key pydantic.types.SecretStr "" TMDB API key (v3) or read access token (v4)
tmdb.language str "fr-FR" Preferred poster/metadata language and region, e.g. fr-FR or en-US (regional posters first, then same language, textless, English)
tmdb.image_size Literal['auto', 'w780', 'w1280', 'original'] "auto" Poster resolution to download. auto = the smallest size covering the poster's on-panel size that is a real downscale of the original (never a TMDB-side upscale), else the original
tmdb.ephemeral_ttl_minutes int 180 How long an ephemeral poster stays before the previous image returns
tmdb.hold_minutes `int None` null
tmdb.fallback_title_card bool true Render a title card when no poster can be found (else answer 404)
music section
music.enrich_artwork bool true Look up a high-resolution cover (Deezer, then MusicBrainz / Cover Art Archive) when none is provided or it cannot be downloaded
music.default_style Literal['sleeve', 'vinyl'] "sleeve" Album template style: sleeve, or vinyl (a record peeks out)
music.show_track_title bool false Print the track title under the cover. Off: artist and album only, so the frame stays still while an album plays (tracks of one album are deduplicated)
music.default_ttl_minutes int 10 Cover lifetime when the request gives no duration or ttl
music.ttl_grace_seconds int 30 Added to the remaining track time so the cover outlives short gaps
music.deezer_enabled bool true Search covers on Deezer (no key)
music.musicbrainz_enabled bool true Fall back to MusicBrainz / Cover Art Archive
music.lookup_cache_size int 256 Cover lookups remembered in memory (0 = off)
fraimic section
fraimic.host str "fraimic.local" Frame hostname, IP or base URL (http:// is assumed when omitted)
fraimic.power_mode Literal['continuous', 'deepsleep'] "continuous" continuous = always reachable; deepsleep = queue until the frame wakes up
fraimic.panel Literal['133', '315'] "133" Panel model: 133 (13.3") or 315 (31.5")
fraimic.upload_path str "/api/image" Frame endpoint receiving .bin
fraimic.status_path str "/api/info" Frame endpoint used as ping
fraimic.poll_interval_s int 30 Deepsleep: seconds between availability checks
fraimic.request_timeout_s float 60.0 HTTP timeout for frame requests
display section
display.orientation Literal['portrait', 'landscape'] "portrait" How the frame is hung
display.landscape_rotation Literal[90, 270] 90 Landscape only: degrees (counter-clockwise) to rotate the composed image into the panel's native portrait buffer; use 270 if the image appears upside down
display.default_fit Literal['smart_crop', 'contain'] "smart_crop" Fit mode for photos (posters always use contain)
display.contain_background Literal['blur', 'black', 'white'] "blur" Padding style used by the contain fit mode
display.safe_margin_px int 0 Inset (pixels) kept clear on every side so subjects stay out of the frame's mat/bezel; the margin is filled with the contain background style
eink section
eink.profile Literal['auto', 'official', 'photo', 'soft', 'vivid', 'natur "auto" auto = chosen per image from its content (photo, poster, album cover, title card) and cheap statistics; official = the values below (defaults = official converter); photo = softer preset for photographs; soft / vivid = gamut-safe tone and chroma curves (lifted shadows / richer colors); natural = no enhancement. Everything but official overrides brightness, contrast, saturation, sharpness and edge_filters
eink.brightness float 1.1 1.0 = unchanged
eink.contrast float 1.2 1.0 = unchanged
eink.saturation float 1.2 1.0 = unchanged
eink.sharpness float 1.0 1.0 = unchanged
eink.edge_filters bool true Apply the official edge-enhance / smooth / sharpen chain
eink.dither Literal['auto', 'atkinson', 'atkinson-classic', 'fs', 'floyd "auto" auto = chosen per image (fs-serpentine for detailed photos and posters, stucki for smooth skies and gradients, atkinson-classic for graphics and covers); atkinson = the official converter's 4-neighbour variant; fs = Floyd-Steinberg; fs-serpentine = FS with alternating scan direction; stucki = wide 12-neighbour kernel; blue-noise = ordered blue-noise threshold (fastest, grainy)
scheduler section
scheduler.enabled bool false Enable autonomous periodic refresh
scheduler.interval_hours float 6.0 Hours between automatic refreshes
scheduler.quiet_hours_start `str None` null
scheduler.quiet_hours_end `str None` null
scheduler.timezone str "UTC" IANA timezone of the quiet hours, e.g. Europe/Paris
scheduler.source_rule `SourceRule None` null
scheduler.skip_if_pending bool true Skip a scheduled refresh while the previous image still waits for the frame (deepsleep), so an image the frame never showed is not replaced
scheduler.retry_minutes int 15 First retry delay after a failed refresh; doubles on each failure, capped by interval_hours
smart_mix section
smart_mix.enabled bool false Pick the next scheduled photo from the entries (a pinned scheduler.source_rule still wins)
smart_mix.entries list[SmartMixEntry] [] Weighted playlist entries
smart_mix.max_attempts int 3 Entries tried per refresh when one has no candidate or fails
smart_mix.avoid_consecutive bool true Do not pick the same entry twice in a row when others exist
smart_mix.hemisphere Literal['north', 'south'] "north" Used to map months to {season}
smart_mix.discovery_share float 0.15 Random Discovery: chance that a scheduled refresh shows a random photo of the whole library (quality gate and Family Mode still apply) instead of an entry
family section
family.enabled bool false Apply the filters below (POST /api/context can override)
family.members list[str] [] Immich recognized people; only photos with at least one of them are used (empty = the whole library)
family.require_member bool true Enforce members (false keeps only the private exclusions)
family.private_albums list[str] [] Album names or IDs whose photos are never shown
family.private_people list[str] [] People whose photos are never shown
ambient section
ambient.weather_queries dict[str, str] {"sunny": "bright sunny day outdoors", "rainy": "cozy rai... Weather keyword -> CLIP search phrase added to the mix while it is live
ambient.boost_weight float 3.0 Weight of each ambient candidate in the mix
ambient.default_ttl_minutes int 180 Lifetime of a context field without ttl_minutes
quality section
quality.enabled bool true Check photos before downloading them
quality.candidates_checked int 8 Max candidates inspected per request
quality.min_dimension int 600 Reject images whose short side is below this (px)
quality.blank_luma_mean float 15.0 Reject near-black frames (mean luma below)
quality.blank_luma_std float 8.0 Reject flat frames (luma std-dev below)
quality.screenshot_flat_share float 35.0 No camera EXIF and this % of pixels one bright color
quality.screenshot_flat_luma float 128.0 Luma above which the flat color counts as bright
quality.screenshot_aspect float 1.9 No camera EXIF and aspect at least this (phone screen)
quality.screenshot_max_dimension int 1300 ... and short side at most this (px)
quality.document_colorfulness float 15.0 No camera EXIF, colorfulness below this ...
quality.document_white_share float 15.0 ... and at least this % of near-white pixels

Highlights

Smart Mix and Smart Search

Smart Mix is a weighted playlist of source rules for scheduled refreshes, so the frame shows a varied rotation (family, favorites, "this season", memories...) instead of one filter. It knows nothing about providers: each entry wraps a rule (kind + params, the body of the matching display endpoint), and the runner registered for that kind plays it. Adding a provider later needs no change to the configuration.

curl -X PUT http://localhost:8080/api/config -H 'Content-Type: application/json' -d '{
  "scheduler": {"enabled": true, "interval_hours": 3},
  "smart_mix": {"enabled": true, "entries": [
    {"label": "Family", "kind": "immich", "weight": 5,
     "params": {"persons": ["Alice", "Bob"], "match_mode": "any"}},
    {"label": "This season", "kind": "immich", "weight": 2,
     "params": {"mode": "search", "clip_queries": ["{season} landscape", "{month_name} light"]}},
    {"label": "On this day", "kind": "immich", "weight": 1,
     "params": {"on_this_day": {"window_days": 3, "years_back": 10}}}
  ]}
}'
  • Weights are relative. Each refresh orders the enabled entries by weighted random sampling and tries them in turn: if one has no candidate (nothing left in the anti-repeat history, an empty album) or fails, the next one is tried, up to smart_mix.max_attempts (default 3). With avoid_consecutive (default) the entry shown last is tried last.
  • Context placeholders. {season}, {month}, {month_name} and {year} in string params are expanded each time the entry runs (smart_mix.hemisphere flips the seasons; the timezone is scheduler.timezone). on_this_day searches window_days around today's date in each of the last years_back years; taken_after / taken_before give a fixed date range. No album IDs are needed.
  • Precedence for scheduled refreshes and POST /api/refresh: the pinned scheduler.source_rule, then the Smart Mix (enabled with at least one enabled entry), then the last non-ephemeral manual display. Mix refreshes never overwrite that last display, so turning the mix off restores the previous behavior.
  • Direct pushes always win. POST /api/display/immich, /upload and /smart-search display immediately, restart the refresh timer and never touch the playlist or your settings. Add "ephemeral": true so a temporary push (a movie poster, a song) is not remembered as the rule to replay, and "hold_minutes": 150 so no scheduled refresh replaces it before then (hold_until in GET /api/status). A manual POST /api/refresh ignores the hold.

Smart Search is the same idea for one-off pushes: describe what you want, never an ID.

curl -X POST http://localhost:8080/api/display/smart-search -H 'Content-Type: application/json' \
  -d '{"query": "rainy sunday", "persons": ["Alice"], "hold_minutes": 120}'
curl -X POST .../api/display/smart-search -H 'Content-Type: application/json' \
  -d '{"on_this_day": true}'

query / queries are CLIP phrases (placeholders allowed), combined freely with persons, match_mode, accounts, on_this_day, taken_after / taken_before, fit, push_to_fraimic and ignore_history. Smart-search pushes are ephemeral by default ("ephemeral": false stores one as the rule to replay).

A context boost shapes the next scheduled refreshes for a while, without displaying anything now: it joins the playlist with its own weight (default 3), or replaces it with "exclusive": true, until ttl_minutes pass.

curl -X POST .../api/smart-mix/context -H 'Content-Type: application/json' \
  -d '{"queries": ["cozy rainy day"], "weight": 5, "ttl_minutes": 240, "label": "rain"}'
curl -X DELETE .../api/smart-mix/context

For another source, send kind and params instead of queries. Unknown kinds are rejected: GET /api/smart-mix lists the supported ones.

Endpoint Purpose
POST /api/display/smart-search Contextual search and immediate (ephemeral) push
POST /api/smart-mix/context Temporary boost or override of the playlist (409 when the mix is disabled)
DELETE /api/smart-mix/context Remove the boost
GET /api/smart-mix Playlist with each entry's probability, resolved placeholders, live boost and supported kinds

/api/smart-mix requires the API key for every method when APP_API_KEY is set. GET /api/status reports scheduler.smart_mix, hold_until, and the entry shown by the last refresh (last_run.entry_label).

# Home Assistant: push a contextual photo on demand, boost the mix while it rains
rest_command:
  frame_smart_search:
    url: http://smart-frame.lan:8080/api/display/smart-search
    method: POST
    content_type: application/json
    payload: '{"query": "{{ query }}", "hold_minutes": {{ hold | default(120) }}}'
    timeout: 60
    headers:
      X-API-Key: !secret smart_frame_api_key
  frame_rain_boost:
    url: http://smart-frame.lan:8080/api/smart-mix/context
    method: POST
    content_type: application/json
    payload: '{"queries": ["cozy rainy day"], "weight": 5, "ttl_minutes": 240, "label": "rain"}'
    headers:
      X-API-Key: !secret smart_frame_api_key

automation:
  - alias: Frame - rainy day mood
    trigger:
      - platform: state
        entity_id: weather.home
        to: rainy
    action:
      - service: rest_command.frame_rain_boost

Family Mode, Random Discovery and ambient context

Locked Folder (always on). Photos in Immich's Locked Folder are never selected by any pipeline (Smart Mix, Random Discovery, smart search, refresh), with Family Mode on or off.

Family Mode (family settings, Settings → Family Mode) filters every Immich selection over the whole library, automatically, with no per-photo curation:

Setting Effect
enabled Apply the filters (a live family_mode in /api/context overrides it).
members Recognized people (Immich faces): keep photos showing at least one of them. Empty = the whole library.
require_member false keeps the members list but only applies the exclusions below.
private_albums Album names or IDs: every photo in them is excluded (membership cached for immich.people_cache_ttl_s).
private_people People whose photos are never shown.

Random Discovery (smart_mix.discovery_share, 0 to 0.5, default 0.15): each scheduled refresh first rolls this share. On a hit it shows a random photo of the whole library (ignoring the default persons/album filters) with the quality gate enforced, so screenshots, low-resolution shots, documents and blank frames are skipped, and Family Mode and the Locked Folder rule applied. If nothing suitable is found, the weighted entries are used. Memes have no reliable detector: the screenshot rule (no camera EXIF plus a flat or phone-shaped image) catches many but not all.

Ambient context (POST/GET/DELETE /api/context, API key): short-lived facts from Home Assistant. Every field expires on its own (ttl_minutes, default ambient.default_ttl_minutes = 180) and is stored in scheduler_state.json, so it survives a restart. A field is either the bare value or {"value" | "values": ..., "ttl_minutes": n}; an empty list or text clears a field, DELETE /api/context?field=presence clears one.

Field Effect
family_mode (bool) Forces Family Mode on or off while live.
presence (names) Adds a candidate showing any of these people (weight ambient.boost_weight).
boost_people (names) Same, for people to favour.
boost_tags (phrases) Adds a CLIP search candidate (beach, birthday...).
weather (keyword) Adds the CLIP phrase of ambient.weather_queries (sunny, rainy, cloudy, snowy, stormy, foggy, clear-night; edit the map to taste).
season Replaces the calendar season in {season} placeholders.

Candidates only matter while the Smart Mix is the active rule. The dashboard shows the live context with its expiries. /api/smart-mix/context stays available for one-off rule boosts.

rest_command:
  frame_guests_over:
    url: http://smart-frame.lan:8080/api/context
    method: POST
    content_type: application/json
    payload: '{"family_mode": {"value": true, "ttl_minutes": 360}}'
    headers:
      X-API-Key: !secret smart_frame_api_key
  frame_context_home:
    url: http://smart-frame.lan:8080/api/context
    method: POST
    content_type: application/json
    payload: '{"presence": {{ presence | tojson }}, "weather": "{{ weather }}", "ttl_minutes": 120}'
    headers:
      X-API-Key: !secret smart_frame_api_key

Zeroconf / mDNS

With ZEROCONF_ENABLED=true (default) the engine advertises _smartframe._tcp.local. with TXT records version, path (ROOT_PATH, / when empty) and auth (open, key or password). Any error is logged and ignored. Docker's default bridge network drops multicast: to be discoverable, run the container with network_mode: host (and drop the ports: mapping; set PORT instead). Home Assistant only discovers this service type through an integration that declares it, which does not exist yet: add the engine manually with its URL.

eInk pipeline

Images are fitted to the panel (smart_crop around faces, or contain on a blurred / black / white background), enhanced and dithered onto the 6-color Spectra 6 palette with the official tuned color metric. Landscape mode rotates the image into the panel's portrait buffer before dithering, like the official --fit rotate, so its .bin is byte-identical too. HEIC/HEIF (iPhone) images decode natively. Every .bin is checked against the panel specification before it is stored (exact size, only valid palette codes, the 0x11 padding of the 31.5" IC4/IC8 blocks).

Automatic look (default). Nobody should have to tune a profile or a dithering algorithm per image: eink.profile and eink.dither default to auto, and the engine decides from the kind of image (photo, movie poster, album cover, title card) and a few cheap statistics of a 256 px thumbnail (a few milliseconds):

Image Profile Dithering
Title card natural atkinson-classic
Graphic: an album cover with very few colors or large flat areas, a poster with very few colors official atkinson-classic
Album cover soft atkinson-classic (flat lettering must not smear)
Poster with bright highlights or strong contrast photo (deep blacks, rich colors, natural skin) fs-serpentine
Flat or muted poster vivid fs-serpentine
Dark photo soft (lifted shadows) fs-serpentine
Bright photo without blacks (snow, beach, fog) vivid (keeps the whites) fs-serpentine
Low-contrast photo soft fs-serpentine
Photo with large smooth regions (sky, fog) photo stucki
Other photos photo fs-serpentine

A photo is never treated as a graphic, however flat its background: a night shot with a big black sky or a snowfield is still a photograph.

An explicit value always wins and auto only fills in the rest. GET /api/status reports what was used and why in current_image.render (profile, dither, reasons).

eink.profile Look
auto Chosen per image (above)
official The official converter: the eink brightness / contrast / saturation / sharpness / edge_filters fields (defaults +10% / +20% / +20%, edge-enhance, smooth, sharpen)
photo Softer preset tuned on a real panel: no edge filters, saturation 0.85, sharpness 0.8
soft Gamut-safe curve: lifted shadows, restrained highlights, no clipping
vivid Gamut-safe curve: stronger contrast, richer color, gradual highlight roll-off
natural No enhancement

soft and vivid work on luminance in floating point and compress chroma toward it only where it would leave the RGB gamut (one scale for all channels, so hue is kept instead of clipping individual channels); adapted from the MIT-licensed stillroom converter (© Fraimic).

eink.dither Algorithm 13.3"
atkinson The official converter's 4-neighbour Atkinson, byte-identical to it 0.7 s
atkinson-classic Original 6-neighbour Atkinson (3/4 of the error): crisp edges, clean flats 0.8 s
fs Floyd-Steinberg 0.7 s
fs-serpentine Floyd-Steinberg with alternating scan direction: no directional "worm" patterns 0.05 s
stucki Wide 12-neighbour kernel: smoother skies and gradients 0.06 s
blue-noise Ordered blue-noise threshold (a bundled tileable tile): film-grain look, no diffusion 0.03 s

Error diffusion is sequential, but the plain kernels run along anti-diagonals in vectorized NumPy (about 0.7 s instead of ~40 s). Serpentine scanning cannot be vectorized that way, so fs-serpentine and stucki run as numba-compiled loops (x86 timings; a Raspberry Pi is roughly 5-10x slower and still well under a second). The kernels are compiled at Docker build time (NUMBA_CACHE_DIR=/app/.numba_cache; outside Docker the cache goes to DATA_DIR/.numba_cache). If numba cannot be imported, stucki falls back to the NumPy path and fs-serpentine to fs, with a warning. floyd_steinberg is still accepted as an alias of fs.

Compare the previous look with auto side by side on your own photos with python scripts/quality_ab.py (see Development).

If a mat or bezel hides the panel edges, set display.safe_margin_px (default 0): the picture is inset by that many pixels on every side and the margin is filled with display.contain_background.

Generated files (./data/cache/):

File Endpoint Content
current.jpg GET /api/current.jpg Enhanced composition, before dithering (HA Generic Camera)
current_dithered.png GET /api/current_dithered.png Exact 6-color preview of the panel
current.bin GET /api/current.bin Frame buffer sent to the frame (960,000 / 2,304,000 bytes)
preview.jpg, preview_dithered.png GET /api/preview.jpg, GET /api/preview_dithered.png The latest render, including push_to_fraimic=false ones
base.* - The last pushed non-ephemeral image, restored after an ephemeral image

current.* always matches what the frame shows (or will show once a sleeping frame wakes up). A render with push_to_fraimic=false only updates preview.*, so a template can be inspected without touching the frame or Home Assistant's camera; POST /api/fraimic/push?from_preview=true then sends it. (Before this release, push_to_fraimic=false replaced current.*.)

Composition templates

Posters and album covers are never cropped. Instead of a fit mode they use a template that lays the artwork out for the frame (portrait or landscape, 13.3" or 31.5"), always with the official eInk profile:

  • poster - the full poster centered over a blurred, darkened backdrop made from the poster itself, with a thin light border and a soft shadow.
  • album - the full square cover (non-square art is padded, not cropped) with the title, artist and album underneath (portrait) or beside it (landscape), on a flat background color sampled from the cover. style: "vinyl" slides a record out of the sleeve.
  • title_card - a clean typographic card, used when no artwork can be found.

Artwork that still has to be enlarged skips the edge-enhance / sharpen chain, which would only amplify its blur and JPEG blocks.

Text uses the bundled Inter font (never Pillow's bitmap default), wraps and shrinks to fit, ends with an ellipsis when it really is too long, and is drawn in pure black or white, whichever contrasts more with the background. It is rendered without anti-aliasing, so glyphs stay a single panel color after dithering instead of picking up colored fringes.

Frame delivery

The frame is driven through its local REST API (GET /api/info, POST /api/image).

  • continuous (mains powered): every new image is pushed immediately; failures are retried with exponential backoff.
  • deepsleep (battery): the image is queued in ./data/queue/ and pushed as soon as the frame answers (probed every poll_interval_s), or immediately when Home Assistant calls POST /api/fraimic/wakeup.
Endpoint Purpose
POST /api/display/upload Upload an image (multipart file, optional fit, push_to_fraimic, ephemeral, hold_minutes)
POST /api/fraimic/push Force push the current image now (200 delivered, 202 queued); ?from_preview=true sends the latest preview
POST /api/fraimic/wakeup Frame is awake: flush the queue (202, or ?wait=true for the outcome)
GET /api/fraimic/info Last known battery / Wi-Fi / firmware (?refresh=true queries the frame)
GET /api/status Frame telemetry, queue state, current image metadata and scheduler state

Scheduler

The frame can update itself without Home Assistant. The scheduler replays the active rule every scheduler.interval_hours hours (REFRESH_INTERVAL_HOURS, default 6, minimum 0.25) once scheduler.enabled is on (SCHEDULER_ENABLED=true):

  • Active rule, in order of precedence: (1) the rule pinned in scheduler.source_rule; (2) the Smart Mix playlist, when enabled and non-empty; (3) the last non-ephemeral request made through POST /api/display/immich (pushed to the frame; previews with push_to_fraimic=false do not count), so showing "Alice and Bob at the beach" once keeps rotating through those photos with the anti-repeat history. Pin a fixed rule in scheduler.source_rule to override the others:

    curl -X PUT http://localhost:8080/api/config -H 'Content-Type: application/json'     -d '{"scheduler": {"enabled": true, "source_rule":
           {"kind": "immich", "params": {"mode": "favorites", "persons": ["Alice"]}}}}'

    params takes the fields of POST /api/display/immich (except push_to_fraimic and ignore_history, ephemeral, hold_minutes), or of POST /api/display/tmdb for "kind": "tmdb" rules. The last rule is kept in ./data/scheduler_state.json, so displaying a photo never rewrites your settings.

  • Timer. Any display (a manual photo, an upload, a refresh) restarts the interval, so a picture chosen by hand stays up for a full interval. A refresh that became due while the app was down runs about 30 s after startup.

  • Quiet hours. QUIET_HOURS_START / QUIET_HOURS_END (24h HH:MM, may cross midnight, e.g. 22:00 -> 07:00) in the timezone TZ (IANA, e.g. Europe/Paris; the container otherwise runs in UTC). A refresh due inside the window runs when it ends; daylight saving changes are handled.

  • Failures. If Immich is down or nothing matches, the refresh is retried after scheduler.retry_minutes (default 15), doubling each time, capped by the interval.

  • Sleeping frames. With scheduler.skip_if_pending (default on), a scheduled refresh is skipped while the previous image still waits in the deep-sleep queue, so an image the frame never showed is not replaced.

Endpoint Purpose
POST /api/refresh Replay the active rule now and push the result (ignores quiet hours; 409 when there is nothing to replay or a refresh is running)
GET /api/status scheduler: next_run_at, in_quiet_hours, last_run (ok/failed/skipped and why), consecutive_failures, active_rule (pinned, smart_mix or last), hold_until, smart_mix
# Home Assistant: a "next photo" button
rest_command:
  frame_next_photo:
    url: http://smart-frame.lan:8080/api/refresh
    method: POST
    timeout: 60   # selecting, downloading and dithering a photo takes a few seconds
    headers:
      X-API-Key: !secret smart_frame_api_key   # when APP_API_KEY or ADMIN_PASSWORD is set

Home · Report an issue · Roadmap

Clone this wiki locally