MMM-OnSpotify for MagicMirror² is a highly configurable module designed to display your current Spotify listening activity on your MagicMirror display (including podcasts, and when available, audiobooks). This module offers extensive customization options, allowing you to tailor the display to your preferences. It extracs the color data from the cover art and creates custom palettes to theme itself (and other modules!).

The module includes an Authentication Service that guide you through the configuration of an Spotify App. MMM-OnSpotify does not use any third party service, its an independent app, just the Spotify Web API.

Note

All the data stays in your mirror. If you have multiple mirrors, the Authentication Service guides you on creating a new Spotify App per mirror.

onSpotifyCtr.mp4

Canvas-Support.mp4

Installation

Step 1: Clone the module and install dependencies

cd ~/MagicMirror/modules
git clone https://github.com/Fabrizz/MMM-OnSpotify.git
cd MMM-OnSpotify
npm install

Step 2: Create a Spotify App and authorize the app

Warning

You cannot use MMM-NowPlayingOnSpotify (or other module) credentials, as the API scopes are different.

To help you creating the Spotify App, we start the Authentication Service, that guides you on each step of the process:

npm run auth
> [Authorization Service] Open http://localhost:8100/ to configure your mirror. 

Once you finish, you are all set with the basic configuration. Scroll down to see all the different theming options for the module.

Once the Authorization Service is running, you can access it from your Raspberry Pi going to http://localhost:8100/. You can also access it remotely using http://<IP>:8100/. Note that using the device where you have MagicMirror² installed is recommended, as you are going to copy and paste the tokens and module configuration in MM².

Module Configuration

The configuration section is divided in groups, scroll down or click what to see below:

[NEW] CANVAS | Theming other modules | General | Polling Intervals | Theming | Homekit | Lyrics

Extended full configuration object:

{
    module: "MMM-OnSpotify",
    position: "bottom_right",
    config: {
        // Spotify authentication (Authentication Service)
        clientID: "key",
        clientSecret: "key",
        accessToken: "key",
        refreshToken: "key",
        // General module options [SEE BELOW]
        advertisePlayerTheme: true,
        displayWhenEmpty: "both",
        userAffinityUseTracks: false,
        prefersLargeImageSize: false,
        hideTrackLengthAndAnimateProgress: false,
        showDebugPalette: false,
        userDataMaxAge: 14400,
        userAffinityMaxAge: 36000,
        deviceFilter: [],
        deviceFilterExclude: false,
        filterNoticeSubtitle: true,
        language: config.language,
        // Update intervals [SEE BELOW]
        isPlaying: 1,
        isEmpty: 2,
        isPlayingHidden: 2,
        isEmptyHidden: 4,
        onReconnecting: 4,
        onError: 8,
        // Animations [SEE BELOW]
        mediaAnimations: false,
        fadeAnimations: false,
        scrollAnimations: false,
        textAnimations: true,
        transitionAnimations: true,
        spotifyVectorAnimations: false,
        // Spotify Code (EXPERMIENTAL)
        spotifyCodeExperimentalShow: true,
        spotifyCodeExperimentalUseColor: true,
        spotifyCodeExperimentalSeparateItem: true,
        // Canvas
        experimentalCanvas: false,
        experimentalCanvasEffect: 'cover',
        experimentalCanvasAlbumOverlay: false,
        // Theming General
        roundMediaCorners: true,
        roundProgressBar: true,
        showVerticalPipe: true, 
        useColorInProgressBar: true,
        useColorInTitle: true,
        useColorInUserData: true,
        showBlurBackground: true,
        blurCorrectionInFrameSide: false,
        blurCorrectionInAllSides: false,
        alwaysUseDefaultDeviceIcon: false,
        experimentalCSSOverridesForMM2: false, // [SEE BELOW]
    },
},

Theming 3rd Party Modules:

/* Keys */
text background palette_vibrant palette_vibrantlight palette_vibrantdark palette_muted palette_mutedlight palette_muteddark brand_spotify

/* Example */
experimentalCSSOverridesForMM2: [
	["--color-text-dimmed", "palette_vibrantlight"],
	["--ONSP-OVERRIDES-ICONS-COLOR", "palette_vibrantlight"], /* View custom.css */
],

Tip

You can use other variables that are not from OnSpotify, just replace palette_vibrantlight with whatever variable you like, it gets wrapped on a var(x) function automatically.

General options:

Key	Description
advertisePlayerTheme true	If the module should send notifications when the theme status changes.
displayWhenEmpty "both"	What to display when the player is empty. Options are: - user: Displays user card - affinity: Shows user top albums/songs - both: Combines the user card and affinity data - logo: Displays the Spotify logo - none: Display only when playing
userAffinityUseTracks false	If you have selected to show your affinity data on idle, you can choose between showing tracks or albums.
prefersLargeImageSize false	If you prefer to use higher resolution images. Not recommended for normal use.
hideTrackLengthAndAnimateProgress false	Depending on your internet conection or your selected polling rate, you may want to hide the actual seconds and animate the progress bar.
showDebugPalette false	Shows the Vibrant output as a palette in the web console.
userDataMaxAge 14400	(Seconds) The time in seconds of user data TTL. If set to 0, its updated everytime that the player goes to idle, as user data rarely changes, this allows a middle ground between updating always and only on boot
userAffinityMaxAge 36000	(Seconds) The time in seconds of affinity data TTL. If set to 0, its updated everytime that the player goes to idle, as user data rarely changes, this allows a middle ground between updating always and only on boot
deviceFilter list[]	List of device names to filter from the module, by default, its an inclusion list, you can change this using deviceFilterExclude (making it an exclusion list). When a filtered device plays displayWhenEmpty shows. Example: ["Sonos Bedroom", "DESKTOP-ABCD123"]
deviceFilterExclude false	Inverts the deviceFilter list, making it exclude devices
filterNoticeSubtitle true	Changes the subtitle of displayWhenEmpty, to not show a false status if the deviceFilter is set
language config.language	Changes the language in which titles of songs are shown. When it is not set, it depends on config.language. Example: en-US (Or false if you prefer the default api response)

Polling Intervals:

Key	Description
isPlaying 1	Default interval when something is playing in Spotify.
isEmpty 2	Interval when the player is idle.
isPlayingHidden 2	Interval when the module is hidden from another module and there is something playing in Spotify.
isEmptyHidden 3	Interval when the module is hidden and the player is idle.
onReconnecting 4	Interval when there is an error fetching from the Spotify API.
onError 8	After trying to reconnect for a long time, the module enters an error state where the polling is rate is longer than "onReconnecting".

Theming:

See also: Disabling all color based theming

Important

• If you are using a RPI5 Not tested, any insight is helpful!
• If you are using a RPI4 I recommend to keep the default theming settings. (enabling some animations should not be a problem)
• If you are using a RPI3 or below, I recommend turning off the animations and the blurred background, as its GPU intensive.
• If you using a higher power device (RPI5), you can turn on all the animations, the fade, text and transition animations look really good!

Animations

Key	Description
mediaAnimations false	Control the cover crossfade, this animation type waits for the image to be dowmloaded to do the fade between new/old media. (See the warning for RPIs above)
fadeAnimations false	Controls the fade effects between module status changes. Not too GPU intensive. (See the warning for RPIs above)
scrollAnimations false	Controls text scrolling for long music/podcast names/artist/show. (See the warning for RPIs above)
textAnimations true	Control the animation of text on music/podcast change, also affects the "current device" text. (See the warning for RPIs above)
transitionAnimations true	Controls the transition between color changes, GPU intensive, but looks really good. (See the warning for RPIs above) (It also affects other modules if you are using experimentalCSSOverridesForMM2 default CSS config.)
spotifyVectorAnimations false	Control the animation of the Spotify code, It look really good, as it transitions seamless. (See the warning for RPIs above)

Spotify Code

Key	Description
spotifyCodeExperimentalShow true	Shows the Spotify Code (SpotifyScannable) for the current Song/Podcast/Audiobook. This is an experimental feature, as the API is not documented. SVG elements from the Spotify CDN are sanitized and parsed to allow animations (spotifyVectorAnimations).
spotifyCodeExperimentalUseColor true	As shown on the image above, color the Spotify Code bar using cover art colors.
spotifyCodeExperimentalSeparateItem true	Separates or joins the Spotify Code Bar to the cover art. Also respects roundMediaCorners and spotifyCodeExperimentalUseColor.

Canvas

Key	Description
experimentalCanvas false	Shows the Spotify Canvas if available. This is an experimental feature, as this API is not documented and private.
experimentalCanvasEffect cover	Control how is the canvas is going to be displayed. Options are: - cover: The Canvas is clipped to have the same height as the album cover. Recommended for low-power devices and if the module is not in a bottom_* position. - scale: Scale up/down the module to fit the entire Canvas without clipping it.
experimentalCanvasAlbumOverlay true	Show the cover art inside the Spotify Canvas.

General Theming options

Key	Description
roundMediaCorners true	If cover art (and Spotify Code) should have rounded corners.
roundProgressBar true	If you want a rounded progress bar.
showVerticalPipe true	Shows or hides the vertical bar (or pipe) in the module header.
useColorInProgressBar true	Use color in the progress bar. If showBlurBackground is enabled, the background behaviour differs to balance it.
useColorInTitle true	Use color in the title, artist and bar.
useColorInUserData true	Only when displayWhenEmpty: "user" is selected.
showBlurBackground true	Renders the background for the module (Heavy GPU use).
blurCorrectionInFrameSide false	Fixes the color blur in the frame side of the module, making it look like there is no gap between the actual border and the display. View ilustration below.
blurCorrectionInAllSides false	Same as blurCorrectionInFrameSide, but applies the correction on all of the borders for a more subtle effect.
alwaysUseDefaultDeviceIcon false	The device icon changes depending on the player type. If you don’t like this behaviour you can disable it.
experimentalCSSOverridesForMM2 false	An array containing CSS overrides, OnSpotify manages the status depending on what is displayed on the screen and lets you customize other modules. See above

See also: Disabling all color based theming

MMM-LiveLyrics

View more on the MMM-LiveLyrics repository. This module uses web scrapping to get the Lyrics from Genius. Not recommended for basic usage.

MMM-HomeKit

Control your mirror (and other modules) using Apple Homekit protocol! (Also compatible with HomeAssistant or other automation systems with simulated HK controllers)

>>> MMM-HomeKit repository <<<

• Control your screen on/off, brightness
• Set the mirror accent color
• Turn on/off on-screen lyrics
• Send notifications
• With native HK accessories

To learn how to use OnSpotify and HomeKit provided accent colors together, read the guide in the MMM-HomeKit repository.

Notification API

key	Description
THEME_PREFERENCE	↑ Sent to signal other modules that color data is available.
NOW_PLAYING	↑ When the player state changes, the module sends a notification so other modules can, for example, show lyrics.
DEVICE_CHANGE	↑ Everytime the Spotify Connect target changes, this notification is fired.
ONSPOTIFY_NOTICE	↑ This notification signals other modules that OnSpotify is available.
ONSPOTIFY_GET	↓ Returns a ONSPOTIFY_NOTICE
GET_PLAYING	↓ Return a NOW_PLAYING notification, regardles of the state of the player. (Used by MMM-LiveLyrics)

Migrating from MMM-NowPlayingOnSpotify

You cannot migrate from NowPlayingInSpotify, as the scopes included in the NPOS auth do not enable searching for user data or viewing user generated data.

Enabling every animation and the included CSS override:

{
    module: "MMM-OnSpotify",
    position: "bottom_right",
    config: {
        clientID: "key",
        clientSecret: "key",
        accessToken: "key",
        refreshToken: "key",
	
	mediaAnimations: true,
	fadeAnimations: true,
	textAnimations: true,
	transitionAnimations: true,
	spotifyVectorAnimations: true,
    scrollAnimations: true,
        experimentalCSSOverridesForMM2: [
			["--color-text-dimmed", "palette_vibrantlight"],
			["--ONSP-OVERRIDES-ICONS-COLOR", "palette_vibrantlight"],
		],
    },
},

Other:

Caution

Using Dynamic Theming notifications is deprecated, use CSS variables and overrides.

• You can disable all the color related theming and use the module as is. You need to disable all the color related fields:
  advertisePlayerTheme, useColorInProgressBar, useColorInTitle, useColorInTitleBorder, showBlurBackground, useColorInUserData, spotifyCodeExperimentalUseColor, experimentalCSSOverridesForMM2. Of course you can still use the Spotify Code (White/Gray). Disabling all theming options also stop the module from loading the Vibrant lib.

• The API for Spotify Codes is not public, as its part of the Spotify CDN (scannables.scdn.co). The API could change without notice. Many libraries rely on it and using it does not go againts the ToS.

• Contributions wanted! Add features or your language using translations/yourLanguage.json. Currently we have translations for: Spanish, English, German

With <3 by Fabrizio | fabriz.co | Star this repository!