Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/darickc/MMM-BackgroundSlideshow

Last synced: 3 months ago
JSON representation

Host: GitHub
URL: https://github.com/darickc/MMM-BackgroundSlideshow
Owner: darickc
License: mit
Created: 2018-08-01T14:21:40.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2024-01-03T01:39:53.000Z (10 months ago)
Last Synced: 2024-06-29T10:32:18.892Z (5 months ago)
Language: JavaScript
Size: 8.28 MB
Stars: 135
Watchers: 18
Forks: 78
Open Issues: 58
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

awesome-mmm - **MMM-BackgroundSlideshow**

README

# Module: Background Slideshow

Show a slideshow of images in the background of [MagicMirror²](https://magicmirror.builders/). Great for a photo frame from instead of a mirror.

The `MMM-BackgroundSlideshow` module is designed to display images fullscreen, 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 images can transition from one to the other and be shown with no edge (cover) or the enter image(contain).

Based on [MMM-ImageSlideshow](https://github.com/AdamMoses-GitHub/MMM-ImageSlideshow/).

## Dependencies / Requirements

This module requires no special dependencies. The only requirement is that the image directories you path to are fixed paths accessible to the MagicMirror 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, selecting which file extensions are valid, the transition speed from one image to another, the background sizing, whether or not to animate the transition from one to the other, the gradient used to make the text more readable, and the gradient opacity.

## 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 MagicMirror install. run: `git clone https://github.com/darickc/MMM-BackgroundSlideshow`. The advantage of using Git is when there is an update, you can run `git pull` and it will pull down all the updates. MagicMirror can even let you know when there are updates.

Download the zip file . Unzip contents into the modules directory of your MagicMirror install. Rename the 'MMM-BackgroundSlideshow-master' folder to 'MMM-BackgroundSlideshow'.

Once downloaded, install dependencies:

```sh
cd ~/MagicMirror/modules/MMM-BackgroundSlideshow
```

```sh
npm install
```

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

```javascript
modules: [
{
module: 'MMM-BackgroundSlideshow',
position: 'fullscreen_below',
config: {
imagePaths: ['modules/MMM-BackgroundSlideshow/exampleImages/'],
transitionImages: true,
randomizeImageOrder: true
}
}
];
```

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

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

## Notification options

The following notifications can be used:

Notification
Description

BACKGROUNDSLIDESHOW_UPDATE_IMAGE_LIST
Reload images list and start slideshow from first image. Works best when sorted by modified date descending.

BACKGROUNDSLIDESHOW_NEXT
Change to the next image, restart the timer for image changes only if already running

BACKGROUNDSLIDESHOW_PREVIOUS
Change to the previous image, restart the timer for image changes only if already running

BACKGROUNDSLIDESHOW_PAUSE
Pause the timer for image changes

BACKGROUNDSLIDESHOW_PLAY
Change to the next image and start the timer for image changes

BACKGROUNDSLIDESHOW_URL
Show an image by passing an object with a URL. Include resume=true to continue slideshow after displaying image, otherwise the image will display until another notification such as BACKGROUNDSLIDESHOW_PLAY.

Example payload: {url:'url_to_image', resume: true}

BACKGROUNDSLIDESHOW_URLS
Pass in a list of URLs to display in the background. To continue showing photos, pass in an empty array or no payload.

Example payload: {urls:['url_to_image', 'url_to_image']}

## Configuration options

The following properties can be configured:

Option
Description

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

Example: ['modules/MMM-BackgroundSlideshow/exampleImages/']

Example: ['/images/']

This value is REQUIRED

excludePaths
Array value containing strings. When scanning subdirectories for
images, directories with these names will be ignored.

Example: ['@eaDir']

Default value: ['@eaDir']

This value is OPTIONAL

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

Example: 6000 for 6 seconds

Default value: 10000 or 10 seconds

This value is OPTIONAL

resizeImages
Boolean value, if images should be resized or not. For better performance, this should be true and the height and width set to the resolution of the monitor being used

Example: true

Default value: false

This value is OPTIONAL

maxWidth
Integer value, the width the image should be resized to.

Example: 3840

Default value: 1920

This value is OPTIONAL

maxHeight
Integer value, the height the image should be resized to.

Example: 2160

Default value: 1080

This value is OPTIONAL

randomizeImageOrder
Boolean value, if true will randomize the order of the images, otherwise use sortImagesBy and sortImagesDescending sorting by filename.

Example: true

Default value: false

This value is OPTIONAL

sortImagesBy
String value, determines how images are sorted. Possible values are: name (by file name), created (by file created date), modified (by file
modified date). Only used if randomizeImageOrder is set to false.

Example: created

Default value: name

This value is OPTIONAL

sortImagesDescending
Boolean value, if true will sort images in descending order, otherwise in ascending order. Only used if randomizeImageOrder is set to false.

Example: true

Default value: false

This value is OPTIONAL

recursiveSubDirectories
Boolean value, if true it will scan all sub-directories in the imagePaths.

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.

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
String value, a list of image properties to display in the image info div, separated by commas. Possible values are : date (EXIF date from image), name (image name).
For the iamge name, the relative path from that defined in imagePaths is displayed if the recursiveSubDirectories option is set to true.

Example: date,name

Default value: name

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

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

gradient
The vertical gradient to make the text more visible. Enter gradient stops as an array.

Example: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%" ]

Default value: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%", "rgba(0, 0, 0, 0) 80%", "rgba(0, 0, 0, 0.75) 100%" ]

This value is OPTIONAL

horizontalGradient
The horizontal gradient to make the text more visible. Enter gradient stops as an array.

Example: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%" ]

Default value: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%", "rgba(0, 0, 0, 0) 80%", "rgba(0, 0, 0, 0.75) 100%" ]

This value is OPTIONAL

radialGradient
A radial gradient to make the text more visible. Enter gradient stops as an array.

Example: [ "rgba(0, 0, 0, 0.75) 0%", "rgba(0, 0, 0, 0) 40%" ]

Default value: [ "rgba(0,0,0,0) 0%", "rgba(0,0,0,0) 75%", "rgba(0,0,0,0.25) 100%"" ]

This value is OPTIONAL

gradientDirection
The direction of the gradient

Example: 'horizontal'

Default value: 'vertical'

Possible values: 'vertical', 'horizontal', 'both', 'radial'

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

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

## Developer commands

- `npm run lint` - Run linting and formatter checks.
- `npm run lint:fix` - Fix linting and formatter issues.