Immich Screensaver for Windows

Immich Screensaver is a Windows screensaver that pulls photos straight from your own Immich server – with real multi-monitor support: every selected screen gets its own fullscreen window showing a different photo, instead of stretching a single image across the whole desktop. Album selection, random order, crossfade and a clock overlay are all configured on a dedicated settings page. The program is written in Lazarus 4 / Free Pascal 3.2.2 and the source code is available under the MIT licence on GitHub.

Why build a screensaver?

Immich has become the obvious answer to the question of how to host your own photo collection instead of handing it to a cloud provider. For Windows, though, Immich does not ship a screensaver – and the built-in Windows screensaver only knows local folders, not APIs. If your library lives on your own server, you would first have to mirror it onto the machine a second time.

On top of that there is the multi-monitor behaviour: for screensavers, Windows treats several displays as one large surface. With two or three monitors you end up with a single photo spread across all of them and the bezels cutting right through the subject. Those are exactly the two problems Immich Screensaver solves.

What the screensaver does

• Multiple monitors: every selected screen shows its own photo in its own fullscreen window

• Album selection: albums are loaded straight from Immich, pick any combination – or nothing at all, which runs the entire library

• Random or sequential: both orders are available

• Display modes: fill (crop), fit (letterbox) or stretch

• Crossfade: smooth transitions between images, with a configurable duration

• Clock and date: an optional overlay you can place in any of the four corners

• Smooth playback: images are prefetched on a background thread, so the network never blocks the animation

• Stored per user: the settings live in %APPDATA%\ImmichScreensaver\

Requirements

• Windows, 64-bit (x86_64)

• a reachable Immich instance and an API key – you create one in Immich under Account Settings → API Keys

• the two OpenSSL DLLs libssl-1_1-x64.dll and libcrypto-1_1-x64.dll next to the .scr file so HTTPS works – both are already included in the repository

Installation

Get the source code via Git:

git clone https://github.com/xchimx/ImmichScreensaver.git

After that it is three steps:

• download or build ImmichScreensaver.scr and place it – together with both DLLs – in a permanent folder, for example C:\Tools\ImmichScreensaver\

• right-click the .scr file → Install, or select it under Settings → Personalization → Lock screen → Screen saver

• open the settings and enter your server URL and API key

One note if you copy the .scr into C:\Windows\System32\: the two DLLs have to be findable there as well – or somewhere on the PATH.

Settings

There are three ways to reach the settings page: the Settings button in the Windows screensaver dialog, a right-click on the .scr file → Configure, or straight from the command line:

ImmichScreensaver.scr /c

Configurable are the server URL, the API key (with a button to test the connection), the interval, random order, display mode, full resolution, crossfade including its duration, clock and date including position, plus the multi-select lists for albums and monitors. For both multi-selects the rule is the same: nothing checked means everything – the whole library, or all monitors.

Command line parameters

• /s – runs the screensaver in fullscreen

• /c – opens the settings page

• no parameter – also opens the settings page, because Windows' "Configure" verb passes no arguments

• /p – preview, not supported, exits immediately

So to test fullscreen mode, start it with /s. Any mouse movement, click or key press ends the screensaver – after a short grace period, so it does not close itself immediately on startup.

Where the configuration lives

The settings end up in an INI file at %APPDATA%\ImmichScreensaver\immich_config.ini. A template is included in the repository as immich_config.ini.example. Important if you fork the code: your real immich_config.ini contains your API key. It is excluded via .gitignore and should stay that way.

Why Lazarus and Free Pascal?

A Windows screensaver is nothing more than an executable with a .scr extension that reacts to a handful of command line parameters. Free Pascal compiles that into a native Win64 binary which runs without a framework runtime – next to the .scr all you need are the two OpenSSL DLLs for the HTTPS connection to the Immich server. For a program that sits on the machine in the background and has to spin up at any moment, that is a pleasantly lean foundation.

Building requires Lazarus 4 and FPC 3.2.2:

lazbuild --build-mode=Release ImmichScreensaver.lpi

The result is ImmichScreensaver.scr – a post-build step copies the ImmichScreensaver.scr.exe produced by FPC to that name, because FPC always appends .exe. There is also a debug mode which builds ImmichScreensaver-debug.exe.

The OpenSSL detail

One thing that is easy to trip over with Free Pascal: for HTTPS, FPC 3.2.2 on 64-bit Windows loads exactly two file names, libssl-1_1-x64.dll and libcrypto-1_1-x64.dll. So it has to be the 1.1.1 series – OpenSSL 3.x is not loaded, because its file names are different.

Both DLLs ship with the repository in version 1.1.1w, so normally you do not have to do anything about it. If you prefer to obtain them yourself, prebuilt Win64 binaries are available from FireDaemon or Overbyte ICS. Worth knowing: OpenSSL 1.1.1 reached end of life in September 2023, and 1.1.1w is the last public release. The bundled DLLs are © The OpenSSL Project and remain under the OpenSSL / SSLeay dual licence, whose text is included in the third-party folder.

Conclusion

If your photos already live on your own Immich server, Immich Screensaver is the shortest route to seeing them on your Windows desktop as well – without keeping a second copy of the library, and without dragging one photo across three monitors. You can find the source code on GitHub; the project is MIT licensed, and issues and pull requests are welcome. You will find my other open-source projects here, and if you are looking for support with a project of your own: here are my services around web development from Kassel.

This project is not affiliated with the Immich project. Immich is developed at immich.app.

Source: github.com