Skip to content

immich-screensaver.md

Latest commit

 

History

History
95 lines (72 loc) · 5.01 KB

immich-screensaver.md

File metadata and controls

95 lines (72 loc) · 5.01 KB
Raw

Immich photo screensaver

Yuvomi can replace the dashboard with photos from an Immich server after a period without keyboard, pointer, touch, or scroll activity - five minutes unless the device chooses otherwise (see Delay on each device). It requests a random set of photos, changes the photo every 20 seconds, and returns to Yuvomi on the next interaction. Photo metadata moves between corners so that the screensaver does not introduce another fixed bright area. If Immich is unavailable, Yuvomi leaves the current screen visible and tries again after a later idle period.

Before you start

Create an Immich API key with these permissions:

  • asset.read, to select random image assets;
  • asset.view, to retrieve preview-sized thumbnails.

The Immich server must be reachable from the Yuvomi server or container. A URL that works only in your browser is not sufficient. For two containers on the same Docker network, this may be an internal service URL such as http://immich-server:2283; otherwise use the HTTPS address at which Yuvomi's server can reach Immich.

Configure in Yuvomi

  1. Sign in as an administrator.
  2. Open Settings → Household → Photos and weather → Immich.
  3. Enter the Immich server URL. Both the server root and a URL ending in /api are accepted.
  4. Enter the API key.
  5. Optionally enter an Immich album UUID. Leave it empty to use the whole library.
  6. Select Test to verify the credentials and optional album filter.
  7. Select Preview to save the current values and open the real screensaver immediately.

The API key is write-only: after it is saved, the browser receives only an indication that a key exists. Leaving the field empty preserves the saved key.

The album UUID is the UUID portion of an Immich album URL. Only image assets are selected; videos are not shown by the screensaver.

Wall tablets

A paired wall tablet shows the screensaver only when an administrator switches it on for that tablet, under Settings → Household → Wall tablets → Show the photo screensaver. It is off by default: a tablet changes no settings itself, and its delay has no "never", so without this switch every wall in a household with Immich would start covering its calendar with photos.

A tablet with the switch on reads the same photos every signed-in device shows - a random selection from the configured album or, without one, from everything the API key can read, with the date, city and country of each photo - and nothing else of the screensaver: the connection, the album choice and the connection test stay with the administrators. With the switch off, the server refuses the photos to that tablet.

Delay on each device

How long a device waits before the screensaver starts is chosen on that device, under Settings → Account → Appearance → Start the screensaver after: 1, 2, 5, 10 or 15 minutes, five by default. It is stored in the browser like wall mode, so a photo frame can start after one minute while a kitchen tablet and every phone in the household keep their own delay. A new value applies at once, without a reload. There is deliberately no household setting or environment variable for it: one value for the whole household would reach every signed-in device.

Clock and full-screen photos

Two more choices sit right below the delay, and they are per device for the same reason:

  • Show the time on the screensaver - on by default. The current time, in the household's time format and zone, in the corner diagonally opposite the photo caption. It moves with the caption and turns on the full minute.
  • Fill the screen with the photo - off by default. Photos fill the whole screen instead of fitting inside it, so the edges are cropped, most of all on a portrait photo shown on a landscape screen.

Both apply the next time the screensaver starts, without a reload.

Configure through environment variables

IMMICH_URL=https://photos.example.com
IMMICH_API_KEY=your-api-key
IMMICH_SCREENSAVER_ALBUM_ID=optional-album-uuid

The album ID is optional. Non-empty environment variables take precedence over database values, and their matching controls become read-only in Settings. Restart Yuvomi after changing them.

Security and troubleshooting

  • Enable DB_ENCRYPTION_KEY to encrypt a key saved through Settings at rest. Without database encryption, Yuvomi logs a warning when it stores an Immich API key.
  • Yuvomi proxies thumbnails so the API key is never placed in image URLs or sent to the tablet.
  • Use Test first if Preview cannot load a photo. Verify the permissions, server reachability, album UUID, and that the library or album contains images.
  • A successful test with an empty album is valid, but Preview needs at least one accessible image.
  • The screensaver applies throughout the authenticated app, not only on the dashboard route.
  • A running kitchen timer on the dashboard keeps the screensaver away: the idle period starts over while the countdown runs, and the screensaver can appear again once the timer has rung.