Skip to content

pelaxa/MMM-ImmichSlideShow

BranchesTags

Repository files navigation

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
cyclicConfigs When set to true, after reaching the last image in a configuration, the module will automatically switch to the next configuration in the immichConfigs array. This allows you to cycle through all your configured albums or modes automatically.

Example: true
Default value: false
This value is OPTIONAL
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
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
width The width of the module when possition is not fullscreen.
Example: 50vw
Default value: 480px
This value is OPTIONAL
height The height of the module when possition is not fullscreen.
Example: 50vh
Default value: 320px
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', 'album', 'search', 'random', or 'anniversary' 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. Max value allowed is 14 days.

Example: 7 for 7 days
This value is REQUIRED if mode is set to memory
albumId Either a single id, or an array of ids of the albums to show pictures from. Note that if albumId and albumName are provided, albumId will take precedence.

Example 1: 1b57d1dc-57d6-4cd4-bc1d-f8ebf759ba16
Example 2: ['1b57d1dc-57d6-4cd4-bc1d-f8ebf759ba16', '4aff9b7b-ae55-404f-81d5-27ccd93d1f9b']
This value is REQUIRED if mode is set to album and albumName is not provided.
albumName Either a single name, or an array of names of the albums to show pictures from. These names are case sensitive and should match the album name in Immich exactly. Note that if albumId and albumName are provided, albumId will take precedence.

Example 1: Family Trip 2023
Example 2: ['Family Trip 2023', 'Christmas 2024']
This value is REQUIRED if mode is set to album and albumId is not provided.
query The query object used to search for images in search, random, and anniversary mode. This is an advanced feature and the expected value here is meant to be a JSON matching what Immich currently supports.

For search mode: The query parameter contains search criteria like text queries, location filters, etc. Refer to: Immich Smart Search for more detail
Example: { "query": "animals", "city": "Montreal" }
query is REQUIRED if mode is set to search.

For random and anniversary mode: The query parameter can include filters like albumIds, personIds, favorites, etc. Refer to Immich Random Search for more detail.
Example: { "isFavorite": true, "withPeople": true }
querySize The number of images to return when in search, random, or anniversary mode. Although, this can also be specified as a size parameter in query, the value specified here overwrites that value. This value must be between 1 and 1000.

Example: 150
Default value: 100
This value is REQUIRED if mode is set to search, random, or anniversary.
anniversaryDatesBack The number of days to look back from today's date when in anniversary mode. For example, if today is July 30th and this is set to 3, it will look for images from July 27th onwards for each year in the range.

Example: 3
Default value: 3
This value is REQUIRED if mode is set to anniversary.
anniversaryDatesForward The number of days to look forward from today's date when in anniversary mode. For example, if today is July 30th and this is set to 3, it will look for images up to August 2nd for each year in the range.

Example: 3
Default value: 3
This value is REQUIRED if mode is set to anniversary.
anniversaryStartYear The starting year for the anniversary search. The module will search for images in the date range for each year from this year to anniversaryEndYear.

Example: 2020
Default value: 2020
This value is REQUIRED if mode is set to anniversary.
anniversaryEndYear The ending year for the anniversary search. The module will search for images in the date range for each year from anniversaryStartYear to this year.

Example: 2025
Default value: 2025
This value is REQUIRED if mode is set to anniversary.
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), album (the name of the album the photo belongs to, useful if you have multiple albums configured), count (The current image number and total image count. Not displayed by default after 1.4.0+). 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), except for album and count which will always display at the top.
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', 'count']
This value is OPTIONAL
dateFormat String value, indicates the format of the date in imageInfo. See momentjs for more info on specifying the format.

Example: MMMM D, YYYY HH:mm
Default value: dddd MMMM D, YYYY HH:mm
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',
			dateFormat: 'MMMM YYYY'
          },
          {
            albumId: 'xxxxxxx-yyyy-zzzz-aaaa-bbbbbbbb',
            mode: 'album',
            slideshowSpeed: 6000,
            imageInfo: ['date','since','geo','count'],
          },
          {
            mode: 'random',
            querySize: 50,
            query: {
              isFavorite: true,
              withPeople: true
            },
            imageInfo: ['date','since','people'],
            slideshowSpeed: 10000
          },
          {
            // The module will search for 100 photos taken between July 27th - August 2nd for each year from 2020 to 2025, creating 6 separate queries and combining all results.
            mode: 'anniversary',
            anniversaryDatesBack: 5,
            anniversaryDatesForward: 2,
            anniversaryStartYear: 2018,
            anniversaryEndYear: 2025,
            querySize: 50,  // Number of images to fetch for each year
            imageInfo: ['date','since','people'],
            slideshowSpeed: 20000
          }
        ],
        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.

About

No description, website, or topics provided.

Resources

Readme

License

MIT license
Activity

Stars

38 stars

Watchers

1 watching

Forks

8 forks
Report repository

Releases 26

v2.0.4 Latest
May 18, 2026
+ 25 releases

Packages

 
 
 

Contributors

Languages