Module: Immich Slide Show

This is 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). The configuration is also mostly matching MMM-Background.

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.

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.

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: {
      apiKey: '<Your API key>',
      immichUrl: '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

Configuration options

The following properties can be configured:

Option	Description
`immichUrl`	The base URL of your Immich installation. 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
`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 original date of the image based on Exif data), modified (by modified 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
`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
`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
`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), and people (the name of the people in the picture). The values can be provided as an array of strings or as a space separated list string. Example: `'date name'` or `[ 'date', 'name']` Default value: `['date', 'since']` 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
`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 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
`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

Creating an API Key

To get an API Key:

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

Allram/MMM-ImmichSlideShow