Repository navigation
Configuration Reference
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:
- values saved in
config.json(everything you change in the UI); - environment variables /
.env(IMMICH_URL,FRAIMIC_HOST... seed the first run); - 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.
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 |
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). Withavoid_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.hemisphereflips the seasons; the timezone isscheduler.timezone).on_this_daysearcheswindow_daysaround today's date in each of the lastyears_backyears;taken_after/taken_beforegive a fixed date range. No album IDs are needed. -
Precedence for scheduled refreshes and
POST /api/refresh: the pinnedscheduler.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,/uploadand/smart-searchdisplay immediately, restart the refresh timer and never touch the playlist or your settings. Add"ephemeral": trueso a temporary push (a movie poster, a song) is not remembered as the rule to replay, and"hold_minutes": 150so no scheduled refresh replaces it before then (hold_untilinGET /api/status). A manualPOST /api/refreshignores 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/contextFor 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_boostLocked 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_keyWith 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.
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.*.)
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.
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 everypoll_interval_s), or immediately when Home Assistant callsPOST /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 |
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 throughPOST /api/display/immich(pushed to the frame; previews withpush_to_fraimic=falsedo 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 inscheduler.source_ruleto 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"]}}}}'
paramstakes the fields ofPOST /api/display/immich(exceptpush_to_fraimicandignore_history,ephemeral,hold_minutes), or ofPOST /api/display/tmdbfor"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(24hHH:MM, may cross midnight, e.g.22:00->07:00) in the timezoneTZ(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