Important
An update regarding Kiosks development here
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?
- Installation
- Docker Compose
- Configuration
- Home Assistant
- FAQ
- TODO / Roadmap
- Support
Immich Kiosk is a lightweight slideshow for running on kiosk devices and browsers that uses Immich as a data source.
Image shot by Damon Golding
You have a two spare Raspberry Pi's laying around. 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.
Use via docker 👇
Note
You can use both a yaml file and environment variables but environment variables will overwrite settings from the yaml file
services:
immich-kiosk:
image: damongolding/immich-kiosk:latest
container_name: immich-kiosk
environment:
TZ: "Europe/London"
volumes:
- ./config.yaml:/config.yaml
restart: on-failure
ports:
- 3000:3000services:
immich-kiosk:
image: damongolding/immich-kiosk:latest
container_name: immich-kiosk
environment:
TZ: "Europe/London"
# Required settings
KIOSK_IMMICH_API_KEY: "****"
KIOSK_IMMICH_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
# Asset sources
KIOSK_SHOW_ARCHIVED: FALSE
KIOSK_ALBUM: "ALBUM_ID,ALBUM_ID,ALBUM_ID"
KIOSK_PERSON: "PERSON_ID,PERSON_ID,PERSON_ID"
# UI
KIOSK_DISABLE_UI: FALSE
KIOSK_HIDE_CURSOR: FALSE
KIOSK_BACKGROUND_BLUR: TRUE
# 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
# 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_EXIF: FALSE
KIOSK_SHOW_IMAGE_LOCATION: FALSE
# Kiosk settings
KIOSK_PASSWORD: ""
KIOSK_CACHE: TRUE
KIOSK_PRE_FETCH: TRUE
ports:
- 3000:3000
restart: on-failureSee the file config.example.yaml for an example config file
| yaml | ENV | Value | Default | Description |
|---|---|---|---|---|
| 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_api_key | KIOSK_IMMICH_API_KEY | string | "" | The API for your Immich server. |
| 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. |
| 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 Multiple Albums for more info and how to do this |
| person | KIOSK_PERSON | []string | [] | The ID(s) of a specific person or people you want to display. See Multiple People to see how to implement this. |
| disable_ui | KIOSK_DISABLE_UI | bool | false | A shortcut to set show_time, show_date, show_image_time and image_date_format to false. |
| hide_cursor | KIOSK_HIDE_CURSOR | bool | false | Hide cursor/mouse via CSS. |
| background_blur | KIOSK_BACKGROUND_BLUR | bool | true | Display a blurred version of the image as a background. |
| 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. |
| 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_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). |
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
pre_fetch: true
| yaml | ENV | Value | Default | Description |
|---|---|---|---|---|
| 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. |
| pre_fetch | KIOSK_PRE_FETCH | bool | true | Pre fetch assets in the background so images load much quicker when refresh timer ends. |
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
Thos above would set refresh to 120 seconds (2 minutes), turn off the background blurred image and remove all transitions for this device/browser.
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.
When you add multiple albums (and/or people) at the same time, Immich-Kiosk adds all the requested album(s) ID(s) and people IDs into a "bucket". Then Immich-Kiosk grabs one at random and fetches an image related to that album or person.
There are three ways you can set multiple albums:
- 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
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.
When you add multiple people (and/or albums) at the same time, Immich-Kiosk adds all the requested album(s) ID(s) and people IDs into a "bucket". Then Immich-Kiosk grabs one at random and fetches an image related to that album or person.
There are three ways you can set multiple people ID's:
- 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
This controls how the image will fit on your screen. The options are:
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.
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.
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.
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 |
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"
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.
- 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
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
Q: What is the no wifi icon?
A: This icon shows when the front end can't connect to the back end .
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: Nope. Just one that your client(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 senarios 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: 12345via 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
- Exclude video thumbnails from being displayed
- Clock/timestamp shadow redesign
- Whitelist for people and albums
- Exclude list
- Use favourites as image pool sauce
If this project has been helpful to you and you wish to support me, you can do so with the button below 🙂.
