Module: Image Slideshow

The MMM-ImageSlideshow module is designed to display images, one at a time on a fixed interval, from one or many directories. These images can be shown in order or at random, one directory at a time or all at time. The image heights and widths can be fixed or scaled and the images can be made to be shown in grayscale.

This fork has additional 'switches' offering alternate control over the displayed image.
Notably:

The image name and path can be displayed
The image can be scaled down to fit within a region, whilst maintaining image aspect ratio (aka - best image size for display region)

Dependencies / Requirements

This module requires no special dependencies. The only requirement is that the image directories path are fixed paths accessible to the Magic Mirror instance.

Operation

This module will take in a list of directory paths, one or more, containing image files. The module will display those images in either alphabetical or random order, across either each path one at time or across all the paths at once. Once all the images have been shown, it will loop back and start again.

Extra configurations include setting the amount of time an image is shown for, rendering the images in grayscale, selecting which file extensions are valid, and using a fixed image height and/or width.

Using the module

Note - Raspberry Pi focussed: Use Git to download this extension to Magic Mirror. Make sure Git is installed on your system.
In the command line/terminal, e.g.
sudo apt install git

Next, go to the modules directory of the your Magic Mirror e.g.
cd /home/pi/MagicMirror/modules

Run (for this repository):
git clone https://github.com/OneOfTheInfiniteMonkeys/MMM-ImageSlideshow.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.

When installed, to use this module you need to add an entry to the modules array in the config/config.js file. (RASPI path is /home/pi/MagicMirror/config/config.js) :

modules: [
	{
		module: 'MMM-ImageSlideshow',
		position: 'middle_center',
		config: {
			imageStyleString: "object-fit: scale-down; width: 800px; height: 900px;", // best image scaling within sizes
		        PathStyleText: 'nameonly',                                                // display the image file name only
			imagePaths: ['modules/MMM-ImageSlideshow/exampleImages'],                 // relative path to image files
		}
	}	
]

A different image folder may be used by changing the path entry under the entry imagePaths, held in the config.js file (excerpt shown above). If required change the array parameter on the line containing the imagePaths entry.
e.g. imagePaths: ['modules/MMM-ImageSlideshow/myimages01', 'modules/MMM-ImageSlideshow/myimages02'].
Hint: take care to use the correct punctuation and number of tabs in the config.js file.

Note - Raspberry Pi focussed: e.g. the location on a raspbery pi is typically: /home/pi/MagicMirror/config/config.js

Configuration options

The following properties can be configured:

Option Description

imageStyleString A CSS string which is applied to the image to be displayed.

Example: 'imageStyleString: "object-fit: scale-down; width: 800px; height: 900px;",'
Default value: Empty string (no effect)
This value is OPTIONAL

Where '"object-fit: scale-down;' causes an image to scale within the defined dimensions
and width: 800px; height: 900px;", defines the size in px that the image will be fitted within, without distortion.
See CSS https://www.w3schools.com/css/css3_object-fit.asp for examples

PathStyleText

A string of either 'none', 'nameonly', 'nameonlyandindex','nameonlyindexandtotal', 'fullname', 'fullpath', 'index' or 'indexandtotal' to control the image path/name text content displayed.

Example: 'nameonly'
Default value: 'none'
This value is OPTIONAL

The following are options for this parameter:

'none'	No text is displayed
'nameonly'	Image name (no text following . character)
'nameonlyandindex'	Shows image name and image index number
'nameonlyindexandtotal'	Shows image name and total number of images
'fullname'	Shows image name with file extension
'fullpath'	Shows full image path and image name
'index'	Shows image index
'indexandtotal'	Shows image index and total number of images

ImgTitleTextPos An integer value of 0 or 1 to control positioning of image path/name text.

Example: 0
Default value: 0
This value is OPTIONAL

Where 0 places the image path/name text above the image, 1 places the image path/name text below the image

ImgTitleTextStyle A CSS text format string. See /home/pi/MagicMirror/css/main.css etc. Default value is 'bright small light'.

Example: 'bright medium light'
Default value: 'bright small light'
This value is OPTIONAL

imagePaths Array value containing strings. Each string should be a path to a directory where image files can be found.

Example: ['modules/MMM-ImageSlideshow/example1'],
This value is REQUIRED

slideshowSpeed Integer value, the length of time to show one image before switching to the next, in milliseconds.

Example: 6000
Default value: 10000
This value is OPTIONAL

delayUntilRestart Integer value, the length of time to restart the slideshow after the last image has been shown, in milliseconds. The module will go blank will waits to restart. This value defaults to zero, meaning no delay until restarting.

Example: 6000
Default value: 0
This value is OPTIONAL

fixedImageWidth Integer value, sets a fixed pixel width for all the images to be shown. If set to 0, the image's actual width is used.

Example: 250
Default value: 0
This value is OPTIONAL

fixedImageHeight Integer value, sets a fixed pixel height for all the images to be shown. If set to 0, the image's actual height is used.

Example: 300
Default value: 0
This value is OPTIONAL

randomizeImageOrder Boolean value, if true will randomize the order of the images, if false will use an alphabetical sorting by filename.

Example: true
Default value: false
This value is OPTIONAL

treatAllPathsAsOne Boolean value, if true will treat all the paths specified in imagePaths as one path. Otherwise, if false, images will only be shown from one path at a time in the order of imagePaths, until all the images in that path are exhausted, before continuing to the next path.

Example: true
Default value: false
This value is OPTIONAL

makeImagesGrayscale Boolean value, if true images will be rendered in grayscale (i.e black and white) instead of color. If false they will be rendered as just they are without change.

Example: true
Default value: false
This value is OPTIONAL

validImageFileExtensions String value, a list of image file extensions, seperated by commas, that should be included. Files found without one of the extensions will be ignored.

Example: 'png,jpg'
Default value: 'bmp,jpg,gif,png'
This value is OPTIONAL

OneOfTheInfiniteMonkeys / MMM-ImageSlideshow

Module: Image Slideshow

Dependencies / Requirements

Operation

Using the module

Configuration options

About

Languages