Immich Kiosk

Important

An update regarding Kiosks development here

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?

I created Immich Kiosk to be a lightweight slideshow to run on kiosk devices and browsers.

Image shot by Damon Golding

Image shot by @insungpandora

Example 1

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.

Installation

Use via docker 👇

Docker Compose

Note

You can use both a yaml file and environment variables but environment variables will overwrite settings from the yaml file

When using a yaml config 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:3000

When using environment variables

services:
  immich-kiosk:
    image: damongolding/immich-kiosk:latest
    container_name: immich-kiosk
    environment:
      TZ: "Europe/London"
      KIOSK_IMMICH_API_KEY: "****"
      KIOSK_IMMICH_URL: "****"
      KIOSK_DISABLE_UI: FALSE
      KIOSK_SHOW_DATE: TRUE
      KIOSK_DATE_FORMAT: YYYY/MM/DD
      KIOSK_SHOW_TIME: TRUE
      KIOSK_TIME_FORMAT: 12
      KIOSK_REFRESH: 60
      KIOSK_DISBALE_SCREENSAVER: TRUE
      KIOSK_ALBUM: "ALBUM_ID,ALBUM_ID,ALBUM_ID"
      KIOSK_PERSON: "PERSON_ID,PERSON_ID,PERSON_ID"
      KIOSK_IMAGE_FIT: CONTAIN
      KIOSK_BACKGROUND_BLUR: TRUE
      KIOSK_TRANSITION: NONE
      KIOSK_SHOW_PROGRESS: TRUE
      KIOSK_SHOW_IMAGE_TIME: TRUE
      KIOSK_IMAGE_TIME_FORMAT: 12
      KIOSK_SHOW_IMAGE_DATE: TRUE
      KIOSK_IMAGE_DATE_FORMAT: YYYY-MM-DD
      KIOSK_PASSWORD: "****"
      KIOSK_CACHE: TRUE
    ports:
      - 3000:3000
    restart: on-failure

Configuration

See 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.
disable_ui	KIOSK_DISABLE_UI	bool	false	A shortcut to set show_time, show_date, show_image_time and image_date_format to false.
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_DISBALE_SCREENSAVER	bool	false	Ask broswer to request a lock that prevents device screens from dimming or locking.
hide_cursor	KIOSK_HIDE_CURSOR	bool	false	Hide cursor/mouse via CSS.
album	KIOSK_ALBUM	[]string	[]	The ID(s) of a specific album or albums you want to display. See FAQ: How do I set multiple albums? to see how to impliment this.
person	KIOSK_PERSON	[]string	[]	The ID(s) of a specific person or people you want to display. See FAQ: How do I set multiple people? to see how to impliment this.
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.
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.
show_progress	KIOSK_SHOW_PROGRESS	bool	false	Display a progress bar for when image will refresh.
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.

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: "****"

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

yaml	ENV	Value	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	Cache selective Immich api calls to reduce unnecessary calls. Default is true.

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

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

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.

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"
"YY M DDD" => "24 8 Thur"
"YY MMM DDDD" => "24 Aug Thursday"
"YYYY MMMM DDDD DD" => "2024 August Thursday 22"

Home Assistant

Note

These examples are community Kiosk implimentations. 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 implimentations 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 Immich Kiosk as an image source for Wallpanel in HomeAssistant:

  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

FAQ

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 get a album ID?
A: 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.

Q: How do I get a persons ID?
A: 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.

Q: How do I set multiple people?
A: 👇

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

Q: How do I set multiple albums?
A: 👇

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

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: 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

Clock/timestamp shadow redesign
Whitelist for people and albums
Exclude list
Fullscreen mode
Use favourites as image pool sauce
Display image metadata. aperture, shutter speed, ISO etc

Support

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

Name		Name	Last commit message	Last commit date
Latest commit History 374 Commits
.github		.github
assets		assets
config		config
immich		immich
public/assets		public/assets
routes		routes
utils		utils
views		views
.dockerignore		.dockerignore
.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.yml		taskfile.yml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Immich Kiosk

Table of Contents

What is Immich Kiosk?

Example 1

Installation

Docker Compose

When using a yaml config file

When using environment variables

Configuration

Additional options

Changing settings via URL

Image fit

Contain (the default)

Cover

None

Date format

Date layout examples

Home Assistant

Using Kiosk to add a slideshow in Home Assistant.

Using Immich Kiosk as an image source for Wallpanel in HomeAssistant:

FAQ

TODO / Roadmap

Support

About

Releases

Packages

Languages

License

njspix/immich-kiosk

Folders and files

Latest commit

History

Repository files navigation

Immich Kiosk

Table of Contents

What is Immich Kiosk?

Example 1

Installation

Docker Compose

When using a yaml config file

When using environment variables

Configuration

Additional options

Changing settings via URL

Image fit

Contain (the default)

Cover

None

Date format

Date layout examples

Home Assistant

Using Kiosk to add a slideshow in Home Assistant.

Using Immich Kiosk as an image source for Wallpanel in HomeAssistant:

FAQ

TODO / Roadmap

Support

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages