Immich Kiosk

Important

This project is not affiliated with Immich

Warning

Like the Immich project, this project is currently in beta and may experience breaking changes.

What is Immich Kiosk?

Immich Kiosk is a lightweight slideshow for running on kiosk devices and browsers that uses Immich as a data source.

Requirements

A reachable Immich server that is running version v1.117.0 or above.
A browser from this supported list or higher.

Key features

Simple installation and updates via Docker.
Lightweight, responsive frontend for smooth performance.
Display random images from your Immich collection, or curate specific albums and people.
Fully customizable appearance with flexible transitions.
Add a live clock with adjustable formats.
Define default settings for all devices through environment variables or YAML config files.
Configure device-specific settings using URL parameters.

Image shot by Damon Golding

Example 1

You have a two Raspberry Pi's. One hooked up to a LCD screen and the other you connect to your TV. You install a fullscreen browser OS or service on them (I use DietPi).

You want the pi connected to the LCD screen to only show images from your recent holiday, which are stored in a album on Immich. It's an older pi so you want to disable CSS transitions, also we don't want to display the time of the image.

Using this URL http://{URL}?album={ALBUM_ID}&transtion=none&show_time=false would achieve what we want.

On the pi connected to the TV you want to display a random image from your library but only images of two specific people. We want the image to cover the whole screen (knowing some cropping will happen) and we want to use the fade transition.

Using this URL http://{URL}?image_fit=cover&transition=fade&person=PERSON_1_ID&person=PERSON_2_ID would achieve what we want.

Example 2

Fanyang Meng created a digital picture frame using a Raspberry Pi Zero 2 W and Kiosk. You can read the blog post about the process here.

This example includes instructions on how to autoboot a Raspberry Pi directly into Immich Kiosk.

Installation

There are two main ways to install Kiosk: Docker or Binary.

Docker (recommended)

Option 1: Add Kiosk to your exsiting Immich compose stack.

Add the kiosk service to your Immich docker-compose.yaml file.

Follow from step 3 in option 2 to create the config.yaml file.

Option 2: Create a separate compose file for Kiosk.

Create a directory of your choice (e.g. ./immich-kiosk) to hold the docker-compose.yaml and config file.
```
mkdir ./immich-kiosk
cd ./immich-kiosk
```

Download docker-compose.yaml.

wget -O docker-compose.yaml https://raw.githubusercontent.com/damongolding/immich-kiosk/refs/heads/main/docker-compose.yaml

Set TZ to a TZ identifier from this list

Create the config.yaml file.

You may use environment variables if preferred.

Create config dir and download config.yaml file.

mkdir ./config
wget -O ./config/config.yaml https://raw.githubusercontent.com/damongolding/immich-kiosk/refs/heads/main/config.example.yaml

Modify config.yaml file.

Only the immich_url and immich_api_key are required fields.
Start the container
```
 docker compose up -d
```

Binary

Tip

Use something like systemd to automate starting the Kiosk binary.

Download the binary file Vist the latest release and scroll to the assets at the bottom of the release notes. Download the archive file that matches your machines architecture and unarchive.

Create config dir and download config.yaml file.

mkdir ./config
wget -O ./config/config.yaml url

Modify config.yaml file.

Only the immich_url and immich_api_key are required fields.
Start Kiosk
```
./kiosk
```

Docker Compose

Note

You can use both a yaml file and environment variables but environment variables will overwrite settings from the yaml file Set TZ to a TZ identifier from this list

When using a `config.yaml` config file

services:
  immich-kiosk:
    image: damongolding/immich-kiosk:latest
    container_name: immich-kiosk
    environment:
      TZ: "Europe/London"
    volumes:
      # Mount the directory with config.yaml inside
      - ./config:/config
    restart: always
    ports:
      - 3000:3000

When using environment variables

Tip

You do not need to specifiy all of these. If you want the default behaviour/value you can omit it from you compose file.

services:
  immich-kiosk:
    image: damongolding/immich-kiosk:latest
    container_name: immich-kiosk
    environment:
      TZ: "Europe/London"
      # Required settings
      KIOSK_IMMICH_API_KEY: "****"
      KIOSK_IMMICH_URL: "****"
      # External url for image links/QR codes
      KIOSK_IMMICH_EXTERNAL_URL: ""
      # Clock
      KIOSK_SHOW_TIME: false
      KIOSK_TIME_FORMAT: 24
      KIOSK_SHOW_DATE: false
      KIOSK_DATE_FORMAT: YYYY/MM/DD
      # Kiosk behaviour
      KIOSK_REFRESH: 60
      KIOSK_DISABLE_SCREENSAVER: false
      KIOSK_OPTIMIZE_IMAGES: false
      # Asset sources
      KIOSK_SHOW_ARCHIVED: false
      KIOSK_ALBUM: "ALBUM_ID,ALBUM_ID,ALBUM_ID"
      KIOSK_EXCLUDED_ALBUMS: "ALBUM_ID,ALBUM_ID,ALBUM_ID"
      KIOSK_PERSON: "PERSON_ID,PERSON_ID,PERSON_ID"
      # UI
      KIOSK_DISABLE_UI: false
      KIOSK_FRAMELESS: false
      KIOSK_HIDE_CURSOR: false
      KIOSK_FONT_SIZE: 100
      KIOSK_BACKGROUND_BLUR: true
      KIOSK_THEME: fade
      KIOSK_LAYOUT: single
      # Sleep mode
      # KIOSK_SLEEP_START: 22
      # KIOSK_SLEEP_END: 7
      # Transistion options
      KIOSK_TRANSITION: none
      KIOSK_FADE_TRANSITION_DURATION: 1
      KIOSK_CROSS_FADE_TRANSITION_DURATION: 1
      # Image display settings
      KIOSK_SHOW_PROGRESS: false
      KIOSK_IMAGE_FIT: contain
      KIOSK_IMAGE_EFFECT: smart-zoom
      KIOSK_IMAGE_EFFECT_AMOUNT: 120
      KIOSK_USE_ORIGINAL_IMAGE: false
      # Image metadata
      KIOSK_SHOW_IMAGE_TIME: false
      KIOSK_IMAGE_TIME_FORMAT: 24
      KIOSK_SHOW_IMAGE_DATE: false
      KIOSK_IMAGE_DATE_FORMAT: YYYY-MM-DD
      KIOSK_SHOW_IMAGE_DESCRIPTION: false
      KIOSK_SHOW_IMAGE_EXIF: false
      KIOSK_SHOW_IMAGE_LOCATION: false
      KIOSK_HIDE_COUNTRIES: "HIDDEN_COUNTRY,HIDDEN_COUNTRY"
      KIOSK_SHOW_IMAGE_ID: false
      KIOSK_SHOW_MORE_INFO: true
      KIOSK_SHOW_MORE_INFO_IMAGE_LINK: true
      KIOSK_SHOW_MORE_INFO_QR_CODE: true
      # Kiosk settings
      KIOSK_WATCH_CONFIG: false
      KIOSK_FETCHED_ASSETS_SIZE: 1000
      KIOSK_HTTP_TIMEOUT: 20
      KIOSK_PASSWORD: ""
      KIOSK_CACHE: true
      KIOSK_PREFETCH: true
      KIOSK_ASSET_WEIGHTING: true
      KIOSK_PORT: 3000
    ports:
      - 3000:3000
    restart: always

When checking `config.yaml` into a repository

It is recommended to avoid checking-in any secrets.

Create a docker-compose.env file.
```
touch docker-compose.env
```
Remove secrets from config.yaml (and docker-compose.yaml) - generally immich_url and immich_api_key.

Include your secrets in docker-compose.env.

KIOSK_IMMICH_API_KEY=SECRET_KEY
KIOSK_IMMICH_URL=SECRET_URL

Update docker-compose.yaml to include env_file:.

services:
  immich-kiosk:
    env_file:
      - docker-compose.env

Add docker-compose.env to .gitignore.

Configuration

See the file config.example.yaml for an example config file

yaml	ENV	Value	Default	Description
immich_api_key	KIOSK_IMMICH_API_KEY	string	""	The API for your Immich server.
immich_url	KIOSK_IMMICH_URL	string	""	The URL of your Immich server. MUST include a port if one is needed e.g. `http://192.168.1.123:2283`.
immich_external_url	KIOSK_IMMICH_EXTERNAL_URL	string	""	The public URL of your Immich server used for generating links and QR codes in the additional information overlay. Useful when accessing Immich through a reverse proxy or different external URL. Example: "https://photos.example.com". If not set, falls back to immich_url.
show_time	KIOSK_SHOW_TIME	bool	false	Display clock.
time_format	KIOSK_TIME_FORMAT	12 \| 24	24	Display clock time in either 12 hour or 24 hour format. Can either be 12 or 24.
show_date	KIOSK_SHOW_DATE	bool	false	Display the date.
date_format	KIOSK_DATE_FORMAT	string	DD/MM/YYYY	The format of the date. default is day/month/year. See date format for more information.
refresh	KIOSK_REFRESH	int	60	The amount in seconds a image will be displayed for.
disable_screensaver	KIOSK_DISABLE_SCREENSAVER	bool	false	Ask browser to request a lock that prevents device screens from dimming or locking. NOTE: I haven't been able to get this to work constantly on IOS.
optimize_images	KIOSK_OPTIMIZE_IMAGES	bool	false	Whether Kiosk should resize images to match your browser screen dimensions for better performance. NOTE: In most cases this is not necessary, but if you are accessing Kiosk on a low-powered device, this may help.
show_archived	KIOSK_SHOW_ARCHIVED	bool	false	Allow assets marked as archived to be displayed.
album	KIOSK_ALBUM	[]string	[]	The ID(s) of a specific album or albums you want to display. See Albums for more information.
excluded_albums	KIOSK_EXCLUDED_ALBUMS	[]string	[]	The ID(s) of a specific album or albums you want to exclude. See Exclude albums for more information.
person	KIOSK_PERSON	[]string	[]	The ID(s) of a specific person or people you want to display. See People for more information.
disable_ui	KIOSK_DISABLE_UI	bool	false	A shortcut to set show_time, show_date, show_image_time and image_date_format to false.
frameless	KIOSK_FRAMELESS	bool	false	Remove borders and rounded corners on images.
hide_cursor	KIOSK_HIDE_CURSOR	bool	false	Hide cursor/mouse via CSS.
font_size	KIOSK_FONT_SIZE	int	100	The base font size for Kiosk. Default is 100% (16px). DO NOT include the % character.
background_blur	KIOSK_BACKGROUND_BLUR	bool	true	Display a blurred version of the image as a background.
theme	KIOSK_THEME	fade \| solid	fade	Which theme to use. See Themes for more information.
layout	KIOSK_LAYOUT	single \| splitview	single	Which layout to use. See Layouts for more information.
sleep_start	KIOSK_SLEEP_START	string	""	Time (in 24hr format) to start sleep mode. See Sleep mode for more information.
sleep_end	KIOSK_SLEEP_END	string	""	Time (in 24hr format) to end sleep mode. See Sleep mode for more information.
custom_css	N/A	bool	true	Allow custom CSS to be used. See Custom CSS for more information.
transition	KIOSK_TRANSITION	none \| fade \| cross-fade	none	Which transition to use when changing images.
fade_transition_duration	KIOSK_FADE_TRANSITION_DURATION	float	1	The duration of the fade (in seconds) transition.
cross_fade_transition_duration	KIOSK_CROSS_FADE_TRANSITION_DURATION	float	1	The duration of the cross-fade (in seconds) transition.
show_progress	KIOSK_SHOW_PROGRESS	bool	false	Display a progress bar for when image will refresh.
image_fit	KIOSK_IMAGE_FIT	cover \| contain \| none	contain	How your image will fit on the screen. Default is contain. See Image fit for more info.
image_effect	KIOSK_IMAGE_EFFECT	zoom \| smart-zoom	""	Add an effect to images.
image_effect_amount	KIOSK_IMAGE_EFFECT_AMOUNT	int	120	Set the intensity of the image effect. Use a number between 100 (minimum) and higher, without the % symbol.
use_original_image	KIOSK_USE_ORIGINAL_IMAGE	bool	false	Use the original image. NOTE: If the original is not a png, gif, jpeg or webp Kiosk will fallback to using the preview.
show_image_time	KIOSK_SHOW_IMAGE_TIME	bool	false	Display image time from METADATA (if available).
image_time_format	KIOSK_IMAGE_TIME_FORMAT	12 \| 24	24	Display image time in either 12 hour or 24 hour format. Can either be 12 or 24.
show_image_date	KIOSK_SHOW_IMAGE_DATE	bool	false	Display the image date from METADATA (if available).
image_date_format	KIOSK_IMAGE_DATE_FORMAT	string	DD/MM/YYYY	The format of the image date. default is day/month/year. See date format for more information.
show_image_description	KIOSK_SHOW_IMAGE_DESCRIPTION	bool	false	Display image description from METADATA (if available).
show_image_exif	KIOSK_SHOW_IMAGE_EXIF	bool	false	Display image Fnumber, Shutter speed, focal length, ISO from METADATA (if available).
show_image_location	KIOSK_SHOW_IMAGE_LOCATION	bool	false	Display the image location from METADATA (if available).
hide_countries	KIOSK_HIDE_COUNTRIES	[]string	[]	List of countries to hide from image_location
show_more_info	KIOSK_SHOW_MORE_INFO	bool	true	Enables the display of additional information about the current image(s)
show_more_info_image_link	KIOSK_SHOW_MORE_INFO_IMAGE_LINK	bool	true	Shows a link to the original image (in Immich) in the additional information overlay
show_more_info_qr_code	KIOSK_SHOW_MORE_INFO_QR_CODE	bool	true	Displays a QR code linking to the original image (in Immich) in the additional information overlay
weather	N/A	[]WeatherLocation	[]	Display the current weather. See weather for more information.

Additional options

The below options are NOT configurable through URL params. In the config.yaml file they sit under kiosk (demo below and in example config.yaml)

immich_url: "****"
immich_api_key: "****"
// all your other config options

// 👇 Additional options
kiosk:
  password: ""
  cache: true
  prefetch: true

yaml	ENV	Value	Default	Description
port	KIOSK_PORT	int	3000	Which port Kiosk should use. NOTE: that is port will need to be reflected in your compose file, e.g. `KIOSK_PORT:HOST_PORT`
watch_config	KIOSK_WATCH_CONFIG	bool	false	Should Kiosk watch config.yaml file for changes. Reloads all connect clients if a change is detected.
fetched_assets_size	KIOSK_FETCHED_ASSETS_SIZE	int	1000	The number of assets (data) requested from Immich per api call. min=1 max=1000.
http_timeout	KIOSK_HTTP_TIMEOUT	int	20	The number of seconds before an http request will time out.
password	KIOSK_PASSWORD	string	""	Please see FAQs for more info. If set, requests MUST contain the password in the GET parameters, e.g. `http://192.168.0.123:3000?password=PASSWORD`.
cache	KIOSK_CACHE	bool	true	Cache selective Immich api calls to reduce unnecessary calls.
prefetch	KIOSK_PREFETCH	bool	true	Pre-fetch assets in the background, so images load much quicker when refresh timer ends.
asset_weighting	KIOSK_ASSET_WEIGHTING	bool	true	Balances asset selection when multiple sources are used, e.g. multiple people and albums. When enabled, sources with fewer assets will show less often.

Changing settings via URL

You can configure settings for individual devices through the URL. This feature is particularly useful when you need different settings for different devices, especially if the only input option available is a URL, such as with kiosk devices.

Example:

https://{URL}?refresh=120&background_blur=false&transition=none

The above would set refresh to 120 seconds (2 minutes), turn off the background blurred image and remove all transitions for this device/browser.

Albums

Getting an albums ID from Immich

Open Immich's web interface and click on "Albums" in the left hand navigation.
Click on the album you want the ID of.
The url will now look something like this http://192.168.86.123:2283/albums/a04175f4-97bb-4d97-8d49-3700263043e5.
The album ID is everything after albums/, so in this example it would be a04175f4-97bb-4d97-8d49-3700263043e5.

How multiple albums work

When you specify multiple albums and/or people, Immich Kiosk creates a pool of all the requested person and album IDs. For each image refresh, Kiosk randomly selects one ID from this pool and fetches an image associated with that album or person.

There are three ways you can set multiple albums:

Note

These methods are applied in order of precedence. URL queries take the highest priority, followed by environment variables, and finally the config.yaml file. Each subsequent method overwrites the settings from the previous ones.

via config.yaml file

album:
  - ALBUM_ID
  - ALBUM_ID

via ENV in your docker-compose file use a , to separate IDs

environment:
  KIOSK_ALBUM: "ALBUM_ID,ALBUM_ID,ALBUM_ID"

via url quires:

http://{URL}?album=ALBUM_ID&album=ALBUM_ID&album=ALBUM_ID

Special album keywords

`all`

Will use all albums. e.g. http://{URL}?album=all

`shared`

Will use only shared albums. e.g. http://{URL}?album=shared

`favorites` or `favourites`

Will use only favourited assets. e.g. http://{URL}?album=favorites or http://{URL}?album=favourites

Exclude albums

This feature allows you to prevent specific albums from being displayed in the slideshow, even when using broad album selection methods like all or shared.

Note

Excluded albums take precedence over album selection methods. If an album is in both the selected albums and excluded albums lists, it will be excluded.

Getting an albums ID from Immich

Open Immich's web interface and click on "Albums" in the left hand navigation.
Click on the album you want the ID of.
The url will now look something like this http://192.168.86.123:2283/albums/a04175f4-97bb-4d97-8d49-3700263043e5.
The album ID is everything after albums/, so in this example it would be a04175f4-97bb-4d97-8d49-3700263043e5.

There are three ways you can exclude albums:

Note

These methods are applied in order of precedence. URL queries take the highest priority, followed by environment variables, and finally the config.yaml file. Each subsequent method overwrites the settings from the previous ones.

via config.yaml file

excluded_albums:
  - ALBUM_ID
  - ALBUM_ID

via ENV in your docker-compose file use a , to separate IDs

environment:
  KIOSK_EXCLUDED_ALBUMS: "ALBUM_ID,ALBUM_ID,ALBUM_ID"

via url quires:

Note

it is exclude_album= and not excluded_albums=

http://{URL}?exclude_album=ALBUM_ID&exclude_album=ALBUM_ID&exclude_album=ALBUM_ID

People

Getting a person's ID from Immich

Open Immich's web interface and click on "Explore" in the left hand navigation.
Click on the person you want the ID of (you may have to click "view all" if you don't see them).
The url will now look something like this http://192.168.86.123:2283/people/a04175f4-97bb-4d97-8d49-3700263043e5.
The persons ID is everything after people/, so in this example it would be a04175f4-97bb-4d97-8d49-3700263043e5.

How multiple people work

When you specify multiple people and/or albums, Immich Kiosk creates a pool of all the requested album and person IDs. For each image refresh, Kiosk randomly selects one ID from this pool and fetches an image associated with that person or album.

There are three ways you can set multiple people ID's:

Note

These methods are applied in order of precedence. URL queries take the highest priority, followed by environment variables, and finally the config.yaml file. Each subsequent method overwrites the settings from the previous ones.

via config.yaml file

person:
  - PERSON_ID
  - PERSON_ID

via ENV in your docker-compose file use a , to separate IDs

environment:
  KIOSK_PERSON: "PERSON_ID,PERSON_ID,PERSON_ID"

via url quires

http://{URL}?person=PERSON_ID&person=PERSON_ID&person=PERSON_ID

Image fit

This controls how the image will fit on your screen. The options are:

Contain (the default)

The image keeps its aspect ratio, but is resized to fit the whole screen. If the image is smaller than your screen, there will be some fuzzyness to your image.

Cover

The image will cover the whole screen. To achieve this the image will mostly likely have some clipping/cropping and if the image is smaller than your screen, there will be some fuzzyness to your image.

None

The image is centered and displayed "as is". If the image is larger than your screen it will be scaled down to fit your screen.

Image effects

zoom

Note

Image fit is set to cover automatically when this effect is used.

This effect zooms in or out to add movement to your images, with the center of the image as the focal point.

smart-zoom

Note

Image fit is set to cover automatically when this effect is used. If the image has multiple faces, Kiosk calculates the center of all faces to use as the focal point.

Smart zoom works like the regular zoom but focuses on faces and includes both zooming and panning.

Tip

To achieve a "Ken Burns" style effect change the image_effect_amount to somewhere between 200-400.

Date format

Note

Some characters, such as / and : are not allowed in URL params. So while you can set the date layout via URL params, I would suggest setting them via config.yaml or environment variables.

You can use the below values to create your preferred date layout.

Value	Example output
YYYY	2024
YY	24
MMMM	August
MMM	Aug
MM	08
M	8
DDDD	Monday
DDD	Mon
DD	04
D	4

Date layout examples

These examples assume that today's date is the 22nd of August 2024.

"YYYY-MM-DD" => "2024-08-22"
"YYYY/MM/DD" => "2024/08/22"
"YYYY:MM:DD" => "2024:08:22"
"YYYY MM DD" => "2024 08 22"
"YYYY MMM (DDD)" => "2024 Aug (Thur)"
"DDDD DD MMMM YYYY" => "Thursday 22 August 2024"

Themes

Fade (the default)

Soft gradient background for the clock and image metadata.

Solid

Solid background for the clock and image metadata.

Layouts

Single (the default)

Display one image.

Splitview

Note

Kiosk attempts to determine the orientation of each image. However, if an image lacks EXIF data, it may be displayed in an incorrect orientation (e.g., a portrait image shown in landscape format).

When a portrait image is fetched, Kiosk automatically retrieves a second portrait image* and displays them side by side vertically. Landscape and square images are displayed individually.

* If Kiosk is unable to retrieve a second unique image, the first image will be displayed individually.

Splitview landscape

Note

Kiosk attempts to determine the orientation of each image. However, if an image lacks EXIF data, it may be displayed in an incorrect orientation (e.g., a portrait image shown in landscape format).

When a landscape image is fetched, Kiosk automatically retrieves a second landscape image* and displays them stacked horizontally. portrait and square images are displayed individually.

* If Kiosk is unable to retrieve a second unique image, the first image will be displayed individually.

Sleep mode

Enabling Sleep Mode:

Setting both sleep_start and sleep_end using the 24 hour format will enable sleep mode.

During Sleep Mode:

Kiosk will display a black screen and can optionally shows a faint clock if show_time or show_date and enabled.

Examples

Setting sleep_start=22 and sleep_end=7 will enable sleep mode from 22:00 (10pm) to 07:00 (7am).
Setting sleep_start=1332 and sleep_end=1508 will enable sleep mode from 13:32 (1:32pm) to 15:08 (3:08pm).

Custom CSS

Note

Custom CSS is applied after all other styles, allowing you to override any default styles.

Warning

Be cautious when using custom CSS, as it may interfere with the normal functioning of Kiosk if not implemented correctly. While I'm happy to help with general Kiosk issues, I may not be able to provide specific support for problems related to custom CSS implementations.

Custom CSS allows you to further customize Kiosk's appearance beyond the built-in themes and settings.

To use custom CSS:

Create a file named custom.css in the same directory as your docker-compose.yml file.
Add your custom CSS rules to this file.
Mount the custom.css file in your container by adding the following line to the volumes section of your docker-compose.yml:

volumes:
  - ./config:/config
  - ./custom.css:/custom.css

Restart your Kiosk container for the changes to take effect.

Tip

Ensure that the path to your custom.css file is relative to your docker-compose.yml file.

The custom CSS will apply to all devices connected to Kiosk by default.

To disable custom CSS for a specific device, add custom_css=false to the URL parameters e.g. http://{URL}?custom_css=false

Weather

Note

To use the weather feature, you’ll need an API key from OpenWeatherMap.

Tip

OpenWeatherMap limits API usage to 60 calls per hour. Since the kiosk refreshes weather data every 10 minutes, you can monitor up to 6 locations with a single API key.

Setting Up Weather Locations

You can configure multiple locations in the config.yaml file, and choose which one to display using the URL query weather=NAME.

Weather Location Configuration Options:

Value	Description
name	The location’s display name (used in the URL query).
lat	Latitude of the location.
lon	Longitude of the location.
api	OpenWeatherMap API key.
unit	Units of measurement (`standard`, `metric`, or `imperial`).
lang	Language code for weather descriptions (see the full list here).
default	Set this location as the default (when no location is specified)

Example Configuration

Here’s an example of how to add London and New York to the config.yaml file. These locations would be selectable via the URL, like this: http://{URL}?weather=london or http://{URL}?weather=new-york.

 weather:
  - name: london
    lat: 51.5285262
    lon: -0.2663999
    api: API_KEY
    unit: metric
    lang: en
    default: true

  - name: new-york
    lat: 40.6973709
    lon: -74.1444838
    api: API_KEY
    unit: imperial
    lang: en

Navigation Controls

You can interact with Kiosk in three ways: touch, mouse, or keyboard.

Touch & Click Zones

Kiosk's display is divided into interactive zones:

Left Side: Previous image(s)
Center top: Pause/Play and Toggle Menu
Right Side: Next image(s)

Keyboard Shortcuts

Key	Action
_ Spacebar	Play/Pause and Toggle Menu
→ Right Arrow	Next Image(s)
← Left Arrow	Previous Image(s)
i Key	Play/Pause and Toggle Menu and display more info overlay

Redirects

Redirects provide a simple way to map short, memorable paths to longer URLs. It's particularly useful for creating friendly URLs that redirect to more complex endpoints with query parameters.

How they Work

Configuration

Redirects are defined in the config.yaml file under the kiosk.redirects section:

Each redirect consists of:

name: The short path that users will use
url: The destination URL where users will be redirected to
type: Optional field that controls URL behavior:
- internal: Keeps the URL unchanged during redirection (useful for maintaining browser history)
- external: Allows URL changes during redirection (default if omitted)

Examples

kiosk:
  redirects:
    - name: london
      url: /?weather=london

    - name: sheffield
      url: /?weather=sheffield
      type: internal

    - name: our-wedding
      url: /?weather=london&album=51be319b-55ea-40b0-83b7-27ac0a0d84a3

Source URL	Redirects to
http://{URL}/london	/?weather=london
http://{URL}/sheffield	http://{URL}/sheffield
http://{URL}/our-wedding	/?weather=london&album=51be319b-55ea-40b0-83b7-27ac0a0d84a3

PWA

Note

IOS does not allow PWA's to prevent the screen from going to sleep. A work around is to lauch Kiosk then enable the guided access feature.

IOS

Open Safari and navigate to Kiosk.
Tap on the share icon in Safari's navigation bar.
Scroll till you see "Add to Home Screen" and tap it.
Tap on the newly added Kiosk icon on your home screen!

Webhooks

Tip

To include the clientName in your webhook payload, append client=YOUR_CLIENT_NAME to your URL parameters.

Kiosk can notify external services about certain events using webhooks. When enabled, Kiosk will send HTTP POST requests to your specified webhook URL(s) when these events occur.

Enabling Webhooks

Add webhook configuration to your config.yaml:

Tip

You can have multiple webhooks for different urls and events.

webhooks:
  - url: "https://your-webhook-endpoint.com"
    event: asset.new
    secret: "my_webhook_secret" # Optional secret for securing webhooks

When a secret is provided, Kiosk will generate a SHA-256 HMAC signature using the webhook payload and include it in the X-Kiosk-Signature-256 header. This allows you to verify that webhook request came from your Kiosk instance, following the same validation pattern as GitHub webhooks.

To validate webhooks on your server, you should:

Get the signature from the X-Kiosk-Signature-256 header
Generate a HMAC hex digest using your secret and the raw request body
Compare the signatures using a constant-time comparison function

Available Events

Event	Description
`asset.new`	Triggered when a new image is requested from Kiosk
`asset.previous`	Triggered when a previous image is requested from Kiosk
`asset.prefetch`	Triggered when Kiosk prefecthes asset data from Immich
`cache.flushed`	Triggered when the cache is manually cleared
`user.webhook.trigger.info_overlay`	Triggered when the "trigger webhook" button is clicked in the image details overlay

Webhook Payload

Field	Type	Description
`event`	string	The type of event, e.g., "asset.new".
`timestamp`	string (ISO)	The time the event occurred, in ISO 8601 format.
`deviceID`	string (UUID)	Unique identifier for the device.
`clientName`	string	Name of the client device.
`assetCount`	int	Number of assets related to the event.
`assets`	array	Array of asset objects.
`config`	object	Configuration options for the application.
`meta`	object	Metadata about the source and version of the system.

Example payload

{
    "event": "asset.new",
    "timestamp": "2024-11-19T11:03:07Z",
    "deviceID": "ed08beb1-6de7-4592-9827-078c3ad91ae4",
    "clientName": "dining-room-pi",
    "assetCount": 1,
    "assets": [
         {
             "id": "bb4ce63b-b80d-430f-ad37-5cfe243e08b1",
             "type": "IMAGE",
             "originalMimeType": "image/jpeg",
             "localDateTime": "2013-04-06T23:45:54Z"
             /* ... other properties omitted for brevity */
         }
     ],
     "config": {
         /* ... configuration fields omitted for brevity */
     },
     "meta": {
         "source": "immich-kiosk",
         "version": "0.13.1"
     }
}

Home Assistant

Note

These examples are community Kiosk implementations. I am unable to provide support for Home Assistant via issues.

While I did not create Kiosk with Home Assistant in mind. I thought it would be useful to add Kiosk implementations I have come across.

Using Kiosk to add a slideshow in Home Assistant.

Open up the dahsboard you want to add the slideshow to in edit mode.
Hit "add card" and search "webpage".
Enter the your Immich Kiosk url in the URL field e.g. http://192.168.0.123:3000
If you want to have some specific settings for the slideshow you can add them to the *URL

* I would suggest disabling all the UI i.e. http://192.168.0.123:3000?disable_ui=true

Using Kiosk to set Immich images as Home Assistant dashboard background

Navigate to the dashboard with the view you wish to add the image background to.
Enter edit mode and click the ✏ next to the view you want to add the image to.
Select the "background" tab and toggle on "Local path or web URL" and enter your url* with path /image e.g. http://192.168.0.123:3000/image.

* If you want to specify an album or a person you can also add that to the url e.g. http://192.168.0.123:3000/image?album=ALBUM_ID

Using Immich Kiosk as an image source for Wallpanel in Home Assistant:

  wallpanel:
    enabled: true
    image_fit: cover
    idle_time: 10
    screensaver_entity: input_boolean.kiosk
    screensaver_stop_navigation_path: /dashboard-kiosk
    fullscreen: true
    display_time: 86400
    image_url: >-
      http://{immich-kiosk-url}/image?person=PERSON_1_ID&person=PERSON_2_ID
    cards:
      - type: vertical-stack
        cards:
          - type: custom:weather-card
            details: true
            forecast: true
            hourly_forecast: false
            name: Weather
            entity: weather.pirateweather
            current: true
            number_of_forecasts: '6'
          - type: custom:horizon-card
            darkMode: true
            showAzimuth: true
            showElevation: true

More documentation about WallPanel here: https://github.com/j-a-n/lovelace-wallpanel

Using Kiosk on Google Cast Devices

Create a photo slideshow in Home Assistant and display it on any Google Cast device (like Chromecast or Nest Hub).

Follow this community guide to get started: Immich Kiosk Mode

FAQ

Q: What is the difference between ImmichFrame and ImmichKiosk?
A:The main differences between ImmichFrame and ImmichKiosk are in how they are set up and how they interact with Immich:

ImmichFrame: For individual devices
- Installed on each device you want to use.
- The device connects directly to Immich.
- Data is processed on the device itself.
ImmichKiosk: For multiple devices
- Installed once on a central server.
- Devices connect to it via a web browser, and it connects to Immich.
- Data is processed by the Kiosk server.

In short, ImmichFrame is a 'one device, one installation, direct connection' setup, while ImmichKiosk is 'one installation, multiple devices, indirect connection.'"

Q: What is the no wifi icon?
A: This icon shows when the front end can't connect to the back end.

Q: What is this icon in the menu?
A: Clicking this icon tells Kiosk to delete all cached data and refresh the current device.

Q: Can I use this to set Immich images as my Home Assistant dashboard background?
A: Yes! Just navigate to the dashboard with the view you wish to add the image background to. Enter edit mode and click the ✏ next to the view you want to add the image to. Then select the "background" tab and toggle on "Local path or web URL" and enter your url with path /image e.g. http://192.168.0.123:3000/image. If you want to specify an album or a person you can also add that to the url e.g. http://192.168.0.123:3000/image?album=ALBUM_ID

Q: Do I need to a docker service for each client?
A: You only need one docker service (or binary running) that your devices(s) will connect to.

Q: Do I have to use port 3000?
A: Nope. Just change the host port in your docker compose file i.e. - 3000:3000 to - PORT_YOU_WANT:3000

Q: How do I set/use a password?
A: 👇

Warning

This feature is meant for edgecase scenarios and offers very little in terms of protection. If you are aiming to expose Kiosk beyond your local network, please investigate more secure alternatives.

via config.yaml file

kiosk:
  password: 12345

via ENV in your docker-compose file

environment:
  KIOSK_PASSWORD: "12345"

Then to access Kiosk you MUST add the password param in your URL e.g. http://{URL}?password=12345

TODO / Roadmap

Support

If this project has been helpful to you and you wish to support me, you can do so with the button below 🙂.

Help

If you have found a bug or have an issue you can submit it here.

If you'd like to chat or need some informal help, feel free to find me in the Kiosk channel on the Immich discord server.

Contributing

Prerequisites

Want to help improve Immich Kiosk? Great! Here's what you'll need to get started:

First, make sure you have these tools installed on your computer:

Go - The main programming language we use
Taskfile - Helps automate common tasks
Node.js - For running the frontend
pnpm - Package manager for the frontend

Ready to contribute? Here's how:

Fork the repository and create a new branch for your changes
```
git checkout -b feature/my-feature
```
Run task install to set up your development environment
Make your changes! Just remember to:
- Follow the existing code style
- Add tests if you're adding new features
- Test your changes with task test
- Check code quality with task lint

Commit your changes with a helpful message

git commit -m "feat: description of your change"

Push your changes to GitHub
```
git push origin feature/my-feature
```
Create a Pull Request to the main branch
- Tell us what your changes do and why you made them
- Link to any related issues
- Add screenshots if you changed anything visual

Guidelines

We try to keep things organized, so please:

Follow Go best practices
Write clear commit messages following conventional commits
Keep changes focused and manageable in size
Update docs if you change how things work
Add tests for new features

Your changes will need to pass our automated checks before being merged.

Need help? We're here for you!

Open an issue on GitHub
Chat with us in the Discord channel

Name		Name	Last commit message	Last commit date
Latest commit History 1,082 Commits
.github		.github
assets		assets
frontend		frontend
internal		internal
.dockerignore		.dockerignore
.gitattributes		.gitattributes
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
banner.go		banner.go
config.example.yaml		config.example.yaml
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
taskfile.docker.yml		taskfile.docker.yml
taskfile.frontend.yml		taskfile.frontend.yml
taskfile.yml		taskfile.yml

License

damongolding/immich-kiosk

Folders and files

Latest commit

History

Repository files navigation

Immich Kiosk

Table of Contents

What is Immich Kiosk?

Requirements

Key features

Example 1

Example 2

Installation

Docker (recommended)

Option 1: Add Kiosk to your exsiting Immich compose stack.

Option 2: Create a separate compose file for Kiosk.

Binary

Docker Compose

When using a config.yaml config file

When using environment variables

When checking config.yaml into a repository

Configuration

Additional options

Changing settings via URL

Albums

Getting an albums ID from Immich

How multiple albums work

Special album keywords

all

shared

favorites or favourites

Exclude albums

Getting an albums ID from Immich

People

Getting a person's ID from Immich

How multiple people work

Image fit

Contain (the default)

Cover

None

Image effects

zoom

smart-zoom

Date format

Date layout examples

Themes

Fade (the default)

Solid

Layouts

Single (the default)

Splitview

Splitview landscape

Sleep mode

Enabling Sleep Mode:

During Sleep Mode:

Examples

Custom CSS

Weather

Setting Up Weather Locations

Weather Location Configuration Options:

Example Configuration

Navigation Controls

Touch & Click Zones

Keyboard Shortcuts

Redirects

How they Work

Configuration

Examples

PWA

IOS

Webhooks

Enabling Webhooks

Available Events

Webhook Payload

Example payload

Home Assistant

Using Kiosk to add a slideshow in Home Assistant.

Using Kiosk to set Immich images as Home Assistant dashboard background

Using Immich Kiosk as an image source for Wallpanel in Home Assistant:

When using a `config.yaml` config file

When checking `config.yaml` into a repository

`all`

`shared`

`favorites` or `favourites`