Module: Immich Slide Show

A MagicMirror module based on MMM-BackgroundSlideshow that works with Immich.

The MMM-ImmichSlideShow module is designed to display images fullscreen, one at a time on a fixed interval, from Immich. These images can be shown in order or at random. The images can transition from one to the other and be shown with no edge (cover) or the entire image (contain). Several configurations can be made all at once and dynamically activated via API calls using MMM-Remote-Control.

Dependencies / Requirements

This module requires no special dependencies besides a working Immich instance.

Operation

This module will require the URL of your Immich instance and your API Key at a minimum. The module will display images from the past 7 days (default value) over the years. In either chronological, alphabetical or random order. Once all the images have been shown, it will loop back and start again after refreshing the images in case the date has changed.

Extra configurations include setting the amount of time an image is shown for, selecting which file extensions are valid, the transition speed from one image to another, the background sizing, and whether or not to animate the transition from one to the other.

Note: This module attempts to sync all of its clients (i.e. display the same image on all clients), so the images are pushed from the server to the client. Version 1.0.0+ ensures that if the server is restarted, the clients connect back.

Using the module

Use Git to download. Make sure Git is installed on your system. In the command line/terminal, go to the modules directory of the your Magic Mirror install. run: git clone https://github.com/pelaxa/MMM-ImmichSlideShow.git. The advantage of using Git is when there is an update, you can run git pull and it will pull down all the updates. Magic Mirror can even let you know when there are updates.

Or

Download the zip file https://github.com/pelaxa/MMM-ImmichSlideShow/archive/main.zip. Unzip contents into the modules directory of your Magic Mirror install. Rename the 'MMM-ImmichSlideShow-main' folder to 'MMM-ImmichSlideShow'.

Once downloaded, install dependencies:

cd ~/MagicMirror/modules/MMM-ImmichSlideShow

npm install

Add the module to the modules array in the config/config.js file:

modules: [
  {
    module: 'MMM-ImmichSlideShow',
    position: 'fullscreen_below',
    config: {
	  immichConfigs: [
		{
		  apiKey: '<Your API key>',
		  url: 'https://<Your Immich hostname/IP>:<port>',
		  mode: 'memory',
		  numDaysToInclude: 7,
		}
	  ],
	  transitionImages: true
    }
  }
];

I also recommend adding the following to the custom.css to make the text a little brighter:

.normal,
.dimmed,
header,
body {
    color: #fff;
}

Notification options

The following notifications can be used:

Notification	Description
IMMICHSLIDESHOW_UPDATE_IMAGE_LIST	Reload images list and start slideshow from first image. Works best when sorted by modified date descending.
IMMICHSLIDESHOW_NEXT	Change to the next image, restart the timer for image changes only if already running
IMMICHSLIDESHOW_PREVIOUS	Change to the previous image, restart the timer for image changes only if already running
IMMICHSLIDESHOW_PAUSE	Pause the timer for image changes
IMMICHSLIDESHOW_PLAY	Change to the next image and start the timer for image changes
IMMICHSLIDESHOW_SET_ACTIVE_CONFIG	Change the active configuration if you have more than one configuration. This API expects a post and the index of the active configuration as post body. See Example below

Example Request for Changing Active Configuration

This requires MMM-Remote-Control

curl --location 'https://myimmich.server:443/api/notification/IMMICHSLIDESHOW_SET_ACTIVE_CONFIG' \
--header 'Authorization: Bearer <MyAPiKey>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{
    "data": 0
}'

Configuration options

The following properties can be configured:

Option	Description
immichConfigs	This holds an array of immich configuration objects so that you can cahnge the configuration at runtime. This is useful if you want to show one set of pictures when you are alone of have family and a different set when you have guests. This was introduced in v1.1.0 and you will need to update your configuration to this new format. Note: So long as you provide the url and apiKey for the first configuration, it is not necessary for others, but if you do want to have a config that talks to a different Immich server, you have the option of including those as well. The way the configurations work is that the first config has to be as specific as you like, and the other configs can just provide the changes needed since they just override the properties of the first config and pick up any missing properties from it. This value is REQUIRED See Immich Configuration Options below
activeImmichConfigIndex	Integer value indicating which of the Immich configurations (immichConfigs) is active. This can be changed at run time as well and defaults to 0 if not provided. Example: 1 Default value: 0 This value is OPTIONAL
validImageFileExtensions	String value, a list of image file extensions, separated by commas, that should be included. Files found without one of the extensions will be ignored. Note that you can include HEIC as a valid extension but beware that the conversion time may be noticeable based on your server and its horsepower. Example: 'png,jpg' Default value: 'bmp,jpg,jpeg,gif,png' This value is OPTIONAL
showImageInfo	Boolean value, if true a div containing the currently displayed image information will be shown. Example: true Default value: false This value is OPTIONAL
imageCompression	A value between 0 and 1 that determines the compression level of JPEG images when images need to be converted (e.g. HEIC images) Example: 0.7 Default value: 0.7 This value is OPTIONAL
imageInfoLocation	String value, determines which corner of the screen the image info div should be displayed in. Possible values are: bottomRight, bottomLeft, topLeft, topRight Example: topLeft Default value: bottomRight This value is OPTIONAL
imageInfoNoFileExt	Boolean value, if true the file extension will be removed before the image name is displayed. Example: true Default value: false This value is OPTIONAL
transitionSpeed	Transition speed from one image to the other, transitionImages must be true. Must be a valid css transition duration. Example: '2s' Default value: '1s' This value is OPTIONAL
showProgressBar	Boolean value, if true a progress bar indicating how long till the next image is displayed is shown. Example: true Default value: false This value is OPTIONAL
backdropFilter	The filter to apply to the background when the image does not cover the entire screen. Only applies to when showBlurredImageForBlackBars is set to true This can be set to any valid CSS backdrop-filter value (e.g. 'blur(10px)') Example: 'blur(10px)' Default value: 'blur(15px) This value is OPTIONAL
backgroundColor	The color of the background when the image does not cover the entire screen. Only visible if backgrounSize is set to contain and showBlurredImageForBlackBars is not set. This can be set to a color (e.g. '#000000') or and semi-transparent color (e.g. 'rgba(0,0,0,0.5)') Example: 'rgba(0,0,0,0.5)' Default value: '#000' (i.e. black) This value is OPTIONAL
backgroundSize	The sizing of the background image. Values can be: cover: Resize the background image to cover the entire container, even if it has to stretch the image or cut a little bit off one of the edges. contain: Resize the background image to make sure the image is fully visible. Good to use with showBlurredImageForBlackBars. Example: 'contain' Default value: 'cover' This value is OPTIONAL
backgroundPosition	Determines where the background image is placed if it doesn't fill the whole screen (i.e. backgroundSize is 'contain'). Module already defaults to 'center', so the most useful options would be: 'top' 'bottom' 'left' or 'right'. However, any valid value for CSS background-position could be used. Example: 'top' Default value: 'center' This value is OPTIONAL
showBlurredImageForBlackBars	Boolean value indicating whether to display the same image in the background but blurred out (actually backdropFilter is applied) since of showing the background color. Not recommended when backgroundAnimaitonEnabled is set to true. Example: true Default value: false This value is OPTIONAL
backgroundAnimationEnabled	Boolean value, if set to true the background will scroll if the picture is larger than the screen size (e.g. for panaramic pictures). The picture will either scroll vertically or horizontally depending on which dimension extends beyond the screen size. Note: For this to work, backgroundSize must be set to cover. Example: true Default value: false This value is OPTIONAL
transitionImages	Transition from one image to the other (may be a bit choppy on slower devices, or if the images are too big). Example: true Default value: false This value is OPTIONAL
transitions	Array value containing strings defining what transitions to perform. Note: transitionImages must be set to true. Example: ['opacity', 'slideFromLeft'] Default value: ['opacity', 'slideFromRight', 'slideFromLeft', 'slideFromTop', 'slideFromBottom', 'slideFromTopLeft', 'slideFromTopRight', 'slideFromBottomLeft', 'slideFromBottomRight', 'flipX', 'flipY'] Possible values: 'opacity', 'slideFromRight', 'slideFromLeft', 'slideFromTop', 'slideFromBottom', 'slideFromTopLeft', 'slideFromTopRight', 'slideFromBottomLeft', 'slideFromBottomRight', 'flipX', 'flipY' This value is OPTIONAL
transitionTimingFunction	CSS timing function used with transitions. Note: transitionImages must be set to true. Example: 'ease-in Default value: 'cubic-bezier(.17,.67,.35,.96)' Possible values: 'ease', 'linear', 'ease-in', 'ease-out', 'ease-in-out', 'cubic-bezier(n,n,n,n)' This value is OPTIONAL
animations	Array value containing strings defining what animations to perform. Note: backgroundAnimationEnabled must be set to true. Example: 'ease-in Default value: ['slide', 'zoomOut', 'zoomIn'] Possible values: 'slide', 'zoomOut', 'zoomIn' This value is OPTIONAL
changeImageOnResume	Should the image be changed in the moment the module resumes after it got hidden? Example: true Default value: false This value is OPTIONAL

Immich Configuration Options

Option	Description
url	The base URL of your Immich installation (used to be called immichUrl prior to version 1.1.0). a /api context will be appended to this URL to access the Immich API. Example: https://myimmich.server:443 This value is REQUIRED
apiKey	The API key to use when accessing the Immich server. Without this all the calls will fail. See the Creating an API Key section. Example: MyAPiKey This value is REQUIRED
timeout	The timeout for Immich API calls in milliseconds (used to be called immichTimeout prior to version 1.1.0). Example: 10000 Default value: 6000 This value is OPTIONAL
mode	The mode of operation for the module. Valid options are 'memory' or 'album' and depending on which is chosen, additional settings are required. Example: memory for memory mode This value is REQUIRED
numDaysToInclude	The number of days to go back and collect images for. Use this to make sure you always have images to display since there could be days where no pictures were taken over the years. Example: 7 for 7 days This value is REQUIRED if mode is set to memory
albumId	The id of the album to show pictures from. Note that if albumId and albumName are provided, albumId will take precedence. Example: 1b57d1dc-57d6-4cd4-bc1d-f8ebf759ba16 This value is REQUIRED if mode is set to album and albumName is not provided.
albumName	The id of the album to show pictures from. This name is case sensitive and should match the album name in Immich exactly. Note that if albumId and albumName are provided, albumId will take precedence. Example: Family Trip 2023 This value is REQUIRED if mode is set to album and albumId is not provided.
sortImagesBy	String value, determines how images are sorted. Possible values are: name (by file name), created (by Immich created time), modified (by Immich modified time), taken (by original date of the image based on Exif data), random (by random order), none (default chronological day order, meaning all images for the 1st over the years before the images for the 2nd, etc). Example: created Default value: none This value is OPTIONAL
sortImagesDescending	Boolean value, if true will sort images in descending order, otherwise in ascending order. Example: true Default value: false This value is OPTIONAL
imageInfo	A list of image properties to display in the image info div. Possible values are : date (EXIF date from image), name (image name), since (how long ago the picture was taken), geo (the city and country where the picture was taken if available), people (the name of the people in the picture. Use people_skip instead to not show extra separators for recognized faces with no name), age (The age of the people at the time the photo was taken. Only works if people is also added), and desc (The description of the image if one is available). The values can be provided as an array of strings or as a space separated list string and the order that you provide this info is how it will display (top to bottom). Note: providing too many options here may take up a large portion of the screen. Example: 'date name people age' or [ 'date', 'name', 'people', 'age'] Default value: ['date', 'since'] This value is OPTIONAL

Configuration Example

...
modules: [
    {
      module: 'MMM-ImmichSlideShow',
      position: 'fullscreen_below',
      config: {
        immichConfigs: [
          {
            apiKey: 'xxxxxxx',
            url: 'https://myimmich.server:443',
            mode: 'memory',
            imageInfo: 'date since geo people',
          },
          {
            albumId: 'xxxxxxx-yyyy-zzzz-aaaa-bbbbbbbb',
            mode: 'album',
            slideshowSpeed: 6000,
            imageInfo: 'date since geo',
          }
        ],
        activeImmichConfigIndex: 0,
        showImageInfo: true,
        showProgressBar: true,
        sortImagesBy: 'taken',
        sortImagesDescending: true,
        validImageFileExtensions: 'jpg,jpeg,png,gif,bmp,heic',
        slideshowSpeed: 30000,
        backgroundPosition: 'top',
        backgroundAnimationEnabled:true,
        backgroundSize: 'cover',
        backgroundColor: 'rgba(0,0,0,.5)',
        bacldropFilter: 'blur(10px)',
        animations: [
          'slide'
        ]
      }
    },
	...
]

Creating an API Key

To get an API Key:

1. Login to your Immich instance
2. Click on your username in the top right cornder
3. Select Account Settings.
4. Expand the API Keys section.
5. Click New API Key to create a new API.
6. Paste the API Key into the module configuration for Magic Mirror.