Configuration Options

Most of the configuration of the card can be done via the Card Editor UI, though there are a few options that must be configured manually. The options documented below will indicate how they can be edited (manual or UI); assume UI editing is available unless otherwise specified.

There are a few assumptions to be made when perusing this document:

You should be familiar with how to edit (and possibly create) an HA dashboard.
You should be familiar with how to add a new card using the UI card-picker, or how to configure a dashboard card manually via YAML.
The SpotifyPlus integration is installed, configured, and up to date.

Use the following index to get to where you want to be.

Pick a Card
General Options
Player Section Options
Devices Section Options
UserPreset Section Options
Recently Played Section Options
Playlist Favorites Section Options
Album Favorites Section Options
Artist Favorites Section Options
Track Favorites Section Options
Audiobook Favorites Section Options
Episode Favorites Section Options
Show Favorites Section Options
Search Media Section Options
Manual Configuration Options
- customImageUrls
Title Formatter Options
Debug Support

Card Picker

Use the standard Home Assistant card picker to add the card to the dashboard. Click on the "By Card" search option, and narrow the list of cards by typing "Spotify" in the search cards entry field.

The card picker tile will look like this:

Click on the Custom: SpotifyPlus Card entry to add the card to your dashboard, and enter the configuration editor to start configuring the card. By default, all card sections will be enabled.

Start by selecting the Media Player Entity Id of the SpotifyPlus media player that is configured. If the media player list is empty, then it denotes there is no SpotifyPlus Media Player(s) configured, OR that none is active / enabled. Please refer to the SpotifyPlus integration wiki for instructions on how to install and configure the SpotifyPlus media player(s).

General Options

These options control the overall look and feel of the card.

How it Looks

`sections`

Controls which sections of the card will be visible. Values are case-sensitive.

type: string array
required: false
default: [player]

The following values are allowed:

player Media Player controls and information.
albumfavorites Album Favorites section will be displayed.
artistfavorites Artist Favorites section will be displayed.
audiobookfavorites Audiobook Favorites section will be displayed.
devices Spotify Connect Devices section will be displayed.
episodefavorites Episode Favorites section will be displayed.
playlistfavorites Playlist Favorites section will be displayed.
recents Recently Played section will be displayed.
searchmedia Search Media section will be displayed.
showfavorites Show Favorites section will be displayed.
trackfavorites Track Favorites section will be displayed.
userpresets User Presets section will be displayed.

The player section will be enabled if no section(s) is specified.

YAML Example - All Sections
This will enable all sections of the card.

sections:
  - player
  - albumfavorites
  - artistfavorites
  - audiobookfavorites
  - devices
  - episodefavorites
  - playlistfavorites
  - recents
  - searchmedia
  - showfavorites
  - trackfavorites
  - userpresets

YAML Example - Media Player Section
This will enable only the Media Player section of the card.

sections:
  - player

`entity_id`

SpotifyPlus media player entity id that will be used to retrieve data from Spotify, as well as control the Spotify Player.

type: string
required: true
default: none

This must be a SpotifyPlus integration media player, as it knows how to communicate with the Spotify Web API (other media players do not).

The Card Editor Preview area will display a Start by configuring a media player entity welcome message until this option is set with a valid value. No other sections of the card can be configured until this option is set.

YAML Example

entity: media_player.spotifyplus_myusername

`title`

Title that is displayed at the top of the card, above the section area.

type: string
required: false
default: none

Omit this parameter to hide the display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the Spotify user account display name.
Renders the following: SpotifyPlus Card "Your Name"

title: SpotifyPlus Card - "{player.sp_user_display_name}"

`footerIconSize`

Size of the icons in the Footer area.

type: string
required: false
default: '1.75rem'

YAML Example

footerIconSize: '3.0rem'

`width`

Width of the card, as expressed in 'rem' units.

type: number | string
required: false
default: 35.15

The numeric (rem units) format is good for Masonry dashboard types, where the card must be positioned alongside other cards in the space.

A value of "fill" can also be used to utilize 100% of the available horizontal space. This is good for Panel dashboard types, where you want the whole space filled up with the card contents.

YAML Example
Renders the card with a width of 40.5rem units.

width: 40.5

Renders the card with a width of 100%.

width: fill

`height`

Height of the card, as expressed in 'rem' units.

type: number | string
required: false
default: 35.15

The numeric (rem units) format is good for Masonry dashboard types, where the card must be positioned alongside other cards in the space.

A value of "fill" can also be used to utilize 100% of the available vertical space. This is good for Panel dashboard types, where you want the whole space filled up with the card contents.

YAML Example
Renders the card with a height of 40.5rem units.

height: 40.5

Renders the card with a height of 100%.

height: fill

Player Section Options

These options control the look and feel of the Player section of the card. This section is divided into 3 subsections: header status, media controls, and volume controls.

Player Section Header Status Options

The following document the options for the Header Status area of the Player section. This area contains the progress bar, the section title text, and 2 lines of sub-title text. All text fields can be customized using Title Formatter Options.

How it Looks

`playerHeaderTitle`

Title displayed in the header area of the Player section form.

type: string
required: false
default: none

Omit this parameter to hide the display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the name of the media player.
Renders the following: "Bose-ST10-1" Player

playerHeaderTitle: '"{player.name}" Player'

`playerHeaderArtistTrack`

Artist and Track info displayed in the header area of the Player section form.

type: string
required: false
default: none

Omit this parameter to hide the display area.

This value supports Title Formatter Options.

YAML Example
Display the currently playing artist and media track title.
Renders the following: Resurrection Band - Lovespeak

playerHeaderArtistTrack: '{player.media_artist} - {player.media_title}'

`playerHeaderAlbum`

Album info displayed in the header area of the Player section form.

type: string
required: false
default: none

Omit this parameter to hide the display area.

This value supports Title Formatter Options.

YAML Example
Display the currently playing media album name.
Renders the following: Ampendectomy

playerHeaderAlbum: '{player.media_album_name}'

`playerHeaderNoMediaPlayingText`

Text to display in the header area of the Player section form when no media is currently playing.

type: string
required: false
default: none

Omit this parameter to display the default 'No Media Playing' value.

This value supports Title Formatter Options.

YAML Example
Display the specified text if no media is currently playing.

playerHeaderNoMediaPlayingText: 'No Media is Currently Playing'

`playerHeaderBackgroundColor`

Color value for the Player header area background gradient, in #HHRRGGBB format.
Specify 'transparent' to remove the background gradient effect.

type: string
required: false
default: '#000000bb'

YAML Example

playerHeaderBackgroundColor: transparent

`playerHeaderHideProgressBar`

Hide progress bar in the header area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerHeaderHideProgressBar: false

`playerHeaderHide`

Hide header area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerHeaderHide: false

Player Section Media Control Options

The following document the options for the Media Controls area of the Player section.

How it Looks

`playerControlsIconSize`

Size of the icons in the Player controls area. This also includes the volume mute and power on / off icons.

type: string
required: false
default: '1.75rem'

YAML Example

playerControlsIconSize: '3.0rem'

`playerControlsHideShuffle`

Hide shuffle button in the controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerControlsHideShuffle: false

`playerControlsHideTrackPrev`

Hide previous track button in the controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerControlsHideTrackPrev: false

`playerControlsHidePlayPause`

Hide play / pause button in the controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerControlsHidePlayPause: false

`playerControlsHideTrackNext`

Hide next track button in the controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerControlsHideTrackNext: false

`playerControlsHideRepeat`

Hide repeat button in the controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerControlsHideRepeat: false

`playerControlsHideFavorites`

Hide favorite actions control button in the controls area.

type: boolean
required: false
default: false

YAML Example

playerControlsHideFavorites: false

`playerControlsHidePlayQueue`

Hide play queue control button in the controls area.

type: boolean
required: false
default: false

YAML Example

playerControlsHidePlayQueue: false

`playerControlsHide`

Hide media controls area of the Player section form. This hides all media controls, as well as the volume slider, mute button, and power button.

type: boolean
required: false
default: false

YAML Example

playerControlsHide: false

Player Section Volume Control Options

The following document the options for the Volume Controls area of the Player section.

How it Looks

`playerControlsBackgroundColor`

Color value for the Player controls area background gradient, in #HHRRGGBB format.
Specify 'transparent' to hide the background area.

type: string
required: false
default: '#000000bb'

YAML Example

playerControlsBackgroundColor: transparent

`playerVolumeControlsHideMute`

Hide mute button in the volume controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerVolumeControlsHideMute: false

`playerVolumeControlsHidePower`

Hide power button in the volume controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerVolumeControlsHidePower: false

`playerVolumeControlsHideSlider`

Hide volume slider control in the volume controls area of the Player section form.

type: boolean
required: false
default: false

YAML Example

playerVolumeControlsHideSlider: false

Devices Section Options

These options control the look and feel of the Devices section of the card.

How it Looks

`deviceBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of Spotify Connect Zeroconf devices found.
Renders the following: Spotify Connect Devices (5 items)

deviceBrowserTitle: Spotify Connect Devices ({medialist.itemcount} items)

`deviceBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click an item to select the device; click-hold for device info

deviceBrowserSubTitle: click an item to select the device; click-hold for device info

`deviceBrowserItemsPerRow`

Number of items to display in a single row of the section browser list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

deviceBrowserItemsPerRow: 4

`deviceBrowserItemsHideTitle`

Hide title displayed for the section browser list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

deviceBrowserItemsHideTitle: false

`deviceBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser list items.

type: boolean
required: false
default: false

YAML Example

deviceBrowserItemsHideSubTitle: true

UserPreset Section Options

These options control the look and feel of the UserPreset section of the card.

How it Looks

`userPresetBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of userpresets found.
Renders the following: User Presets for Todd L (26 items)

userPresetBrowserTitle: User Presets for {player.sp_user_display_name} ({medialist.itemcount} items)

`userPresetBrowserSubTitle`

Sub-Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click an item to select the device; click-hold for device info

userPresetBrowserSubTitle: click an item to select the device; click-hold for device info

`userPresetBrowserItemsPerRow`

Number of items to display in a single row of the section browser list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

userPresetBrowserItemsPerRow: 4

`userPresetBrowserItemsHideTitle`

Hide title displayed for the section browser list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

userPresetBrowserItemsHideTitle: false

`userPresetBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser list items.

type: boolean
required: false
default: false

YAML Example

userPresetBrowserItemsHideSubTitle: true

`userPresetsFile`

The path to a file stored on the local HA file system that contains UserPresetItem entries that represent the content to play. The data in this file is stored in JSON file format.

type: string, relative url
required: false
default: none

Omit this parameter to not define any user presets in a file.

Use this option if you wish to share your presets among multiple card definitions.

I suggest that you place this file in your HA configration directory (e.g. where configuration.yaml resides) www folder (e.g. /config/www/soundtouchplus/userpresets.json). Note that you can create the www folder if it does not exist. Also note that you must use the /local/ prefix in lieu of the /config/www/ prefix. It's weird I know, but it's the way HA looks for things in the local file system under the www folder.

YAML Example
Loads user presets from the /config/www/soundtouchplus/userpresets.json location. Note the prefix use of /local/ instead of /config/www/.

userPresetsFile: /local/soundtouchplus/userpresets.json

JSON File Example
The following tries to document the various Spotify media types that are available to play content from: playlist, artist, album, track, show (podcast), show episode, audiobook, and audiobook episode (chapter).

[
  {
    "name": "Daily Mix 1 (Playlist)",
    "subtitle": "Various Artists",
    "image_url": "https://dailymix-images.scdn.co/v2/img/ab6761610000e5ebcd3f796bd7ea49ed7615a550/1/en/default",
    "uri": "spotify:playlist:37i9dQZF1E39vTG3GurFPW",
    "type": "playlist"
  },
  {
    "name": "Mercy Me (Artist)",
    "subtitle": "Artist",
    "image_url": "https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b",
    "uri": "spotify:artist:6APm8EjxOHSYM5B4i3vT3q",
    "type": "artist"
  },
  {
    "name": "Unseen: The Lion and the Lamb (Album)",
    "subtitle": "Seventh Day Slumber",
    "image_url": "https://i.scdn.co/image/ab67616d0000b2734bfd0e91bf806bc73d736cfd",
    "uri": "spotify:album:0LhYYU14RU6IPQ9vVMu3Yk",
    "type": "album"
  },
  {
    "name": "I Still Believe (Track)",
    "subtitle": "Building 429",
    "image_url": "https://i.scdn.co/image/ab67616d0000b27391efaaa4c9b4b311ddc428b0",
    "uri": "spotify:track:3EtOah8NqZ1FqpQR837v0z",
    "type": "track"
  },
  {
    "name": "The Ramsey Show (Podcast)",
    "subtitle": "Podcast",
    "image_url": "https://i.scdn.co/image/ab6765630000ba8a2ace5767b603de7ee32657de",
    "uri": "spotify:show:5exfRPDNCBHmntEkJrlLmX",
    "type": "show"
  },
  {
    "name": "Don't Let Others Try To Define Your Success (Podcast Episode)",
    "subtitle": "The Ramsey Show",
    "image_url": "https://i.scdn.co/image/ab6765630000ba8a2ace5767b603de7ee32657de",
    "uri": "spotify:episode:1sVbvs5emEiMYiNgZKu9UT",
    "type": "episode"
  },
  {
    "name": "Elfstones of Shannara (Audiobook)",
    "subtitle": "Terry Brooks",
    "image_url": "https://i.scdn.co/image/ab676663000022a8d0264ae7ad91341a2859b281",
    "uri": "spotify:show:74aydHJKgYz3AIq3jjBSv1",
    "type": "show"
  },
  {
    "name": "Chapter 2 (Audiobook Episode)",
    "subtitle": "Elfstones of Shannara",
    "image_url": "https://i.scdn.co/image/ab676663000022a8d0264ae7ad91341a2859b281",
    "uri": "spotify:episode:7sVra5uQv7ce9KFXY7lCzJ",
    "type": "episode"
  }
]

`userPresets`

UserPresetItem entries that represent the content to play.

type: array of IUserPresetItem objects
required: false
default: none

Omit this parameter to not define any user presets in the card configuration.

YAML Example
The following tries to document the various Spotify media types that are available to play content from: playlist, artist, album, track, show (podcast), show episode, audiobook, and audiobook episode (chapter).

userPresets:
  - name: "Daily Mix 1 (Playlist)"
    subtitle: "Various Artists"
    image_url: "https://dailymix-images.scdn.co/v2/img/ab6761610000e5ebcd3f796bd7ea49ed7615a550/1/en/default"
    uri: "spotify:playlist:37i9dQZF1E39vTG3GurFPW"
    type: "playlist"
  - name: "Mercy Me (Artist)"
    subtitle: "Artist"
    image_url: "https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b"
    uri: "spotify:artist:6APm8EjxOHSYM5B4i3vT3q"
    type: "artist"
  - name: "Unseen: The Lion and the Lamb (Album)"
    subtitle: "Seventh Day Slumber"
    image_url: "https://i.scdn.co/image/ab67616d0000b2734bfd0e91bf806bc73d736cfd"
    uri: "spotify:album:0LhYYU14RU6IPQ9vVMu3Yk"
    type: "album"
  - name: "I Still Believe (Track)"
    subtitle: "Building 429"
    image_url: "https://i.scdn.co/image/ab67616d0000b27391efaaa4c9b4b311ddc428b0"
    uri: "spotify:track:3EtOah8NqZ1FqpQR837v0z"
    type: "track"
  - name: "The Ramsey Show (Podcast)"
    subtitle: "Podcast"
    image_url: "https://i.scdn.co/image/ab6765630000ba8a2ace5767b603de7ee32657de"
    uri: "spotify:show:5exfRPDNCBHmntEkJrlLmX"
    type: "show"
  - name: "Don't Let Others Try To Define Your Success (Podcast Episode)"
    subtitle: "The Ramsey Show"
    image_url: "https://i.scdn.co/image/ab6765630000ba8a2ace5767b603de7ee32657de"
    uri: "spotify:episode:1sVbvs5emEiMYiNgZKu9UT"
    type: "episode"
  - name: "Elfstones of Shannara (Audiobook)"
    subtitle: "Terry Brooks"
    image_url: "https://i.scdn.co/image/ab676663000022a8d0264ae7ad91341a2859b281"
    uri: "spotify:show:74aydHJKgYz3AIq3jjBSv1"
    type: "show"
  - name: "Chapter 2 (Audiobook Episode)"
    subtitle: "Elfstones of Shannara"
    image_url: "https://i.scdn.co/image/ab676663000022a8d0264ae7ad91341a2859b281"
    uri: "spotify:episode:7sVra5uQv7ce9KFXY7lCzJ"
    type: "episode"

Recently Played Section Options

These options control the look and feel of the Recently Played section of the card.

How it Looks

`recentBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Recently Played by Todd L (25 items)

recentBrowserTitle: Recently Played by {player.sp_user_display_name} ({medialist.itemcount} items)

`recentBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

recentBrowserSubTitle: click a tile item to play the content; click-hold for actions

`recentBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

recentBrowserItemsPerRow: 4

`recentBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

recentBrowserItemsHideTitle: false

`recentBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

recentBrowserItemsHideSubTitle: true

Playlist Favorites Section Options

These options control the look and feel of the Playlist Favorites section of the card.

How it Looks

`playlistFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Playlist Favorites for Todd L (35 items)

playlistFavBrowserTitle: Playlist Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`playlistFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

playlistFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`playlistFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

playlistFavBrowserItemsPerRow: 4

`playlistFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

playlistFavBrowserItemsHideTitle: false

`playlistFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

playlistFavBrowserItemsHideSubTitle: true

`playlistFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

playlistFavBrowserItemsSortTitle: true

Album Favorites Section Options

These options control the look and feel of the Album Favorites section of the card.

How it Looks

`albumFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Album Favorites for Todd L (35 items)

albumFavBrowserTitle: Album Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`albumFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

albumFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`albumFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

albumFavBrowserItemsPerRow: 4

`albumFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

albumFavBrowserItemsHideTitle: false

`albumFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

albumFavBrowserItemsHideSubTitle: true

`albumFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

albumFavBrowserItemsSortTitle: true

Artist Favorites Section Options

These options control the look and feel of the Artist Favorites section of the card.

How it Looks

`artistFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Artist Favorites for Todd L (35 items)

artistFavBrowserTitle: Artist Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`artistFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

artistFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`artistFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

artistFavBrowserItemsPerRow: 4

`artistFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

artistFavBrowserItemsHideTitle: false

`artistFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

artistFavBrowserItemsHideSubTitle: true

`artistFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

artistFavBrowserItemsSortTitle: true

Track Favorites Section Options

These options control the look and feel of the Track Favorites section of the card.

How it Looks

`trackFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Track Favorites for Todd L (35 items)

trackFavBrowserTitle: Track Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`trackFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

trackFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`trackFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

trackFavBrowserItemsPerRow: 4

`trackFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

trackFavBrowserItemsHideTitle: false

`trackFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

trackFavBrowserItemsHideSubTitle: true

`trackFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

trackFavBrowserItemsSortTitle: true

Audiobook Favorites Section Options

These options control the look and feel of the Audiobook Favorites section of the card.

How it Looks

`audiobookFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Audiobook Favorites for Todd L (35 items)

audiobookFavBrowserTitle: Audiobook Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`audiobookFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

audiobookFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`audiobookFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

audiobookFavBrowserItemsPerRow: 4

`audiobookFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

audiobookFavBrowserItemsHideTitle: false

`audiobookFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

audiobookFavBrowserItemsHideSubTitle: true

`audiobookFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

audiobookFavBrowserItemsSortTitle: true

Episode Favorites Section Options

These options control the look and feel of the Episode Favorites section of the card.

How it Looks

`episodeFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Episode Favorites for Todd L (35 items)

episodeFavBrowserTitle: Episode Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`episodeFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

episodeFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`episodeFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

episodeFavBrowserItemsPerRow: 4

`episodeFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

episodeFavBrowserItemsHideTitle: false

`episodeFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

episodeFavBrowserItemsHideSubTitle: true

`episodeFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

episodeFavBrowserItemsSortTitle: true

Show Favorites Section Options

These options control the look and feel of the Show Favorites section of the card.

How it Looks

`showFavBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Show Favorites for Todd L (35 items)

showFavBrowserTitle: Show Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`showFavBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

showFavBrowserSubTitle: click a tile item to play the content; click-hold for actions

`showFavBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

showFavBrowserItemsPerRow: 4

`showFavBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

showFavBrowserItemsHideTitle: false

`showFavBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

showFavBrowserItemsHideSubTitle: true

`showFavBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

showFavBrowserItemsSortTitle: true

Search Media Section Options

These options control the look and feel of the Search Favorites section of the card.

How it Looks

`searchMediaBrowserTitle`

Title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text along with the number of media list items found.
Renders the following: Search Favorites for Todd L (35 items)

searchMediaBrowserTitle: Search Favorites for {player.sp_user_display_name} ({medialist.itemcount} items)

`searchMediaBrowserSubTitle`

Sub-title displayed at the top of the section.

type: string
required: false
default: none

Omit this parameter to hide the sub-title display area.

This value supports Title Formatter Options.

YAML Example
Display the specified text.
Renders the following: click a tile item to play the content; click-hold for actions

searchMediaBrowserSubTitle: click a tile item to play the content; click-hold for actions

`searchMediaBrowserSearchTypes`

Search media types to enable; unchecked items will not be shown in the "Search for ..." dropdown list. Values are case-sensitive.

type: string array
required: false
default: [] (all sections enabled)

The following values are allowed:

Albums Album searching enabled.
Artists Artist searching enabled.
AudioBooks AudioBook searching enabled.
Episodes Episode searching enabled.
Playlists Playlist searching enabled.
Shows Show searching enabled.
Tracks Track searching enabled.

All types are enabled if no item values are checkedd.

YAML Example - All Search Types
This will enable all search types.

searchMediaBrowserSearchTypes:
  - Albums
  - Artists
  - AudioBooks
  - Episodes
  - Playlists
  - Shows
  - Tracks

`searchMediaBrowserSearchLimit`

Maximum number of items to be returned by the search via the Search media browser section form.

type: integer
required: false
default: 50
range: 1 - 1000

Note that Spotify Web API automatically limits you to 1,000 max entries per type that can be returned with a search.

YAML Example

searchMediaBrowserSearchLimit: 150

`searchMediaBrowserUseDisplaySettings`

Use search display settings when displaying results.
If true, the search type values will be used for the ItemsPerRow, HideTitle, and HideSubTitle values.
If false, the media type values will be used for the ItemsPerRow, HideTitle, and HideSubTitle values.

type: boolean
required: false
default: false

YAML Example

searchMediaBrowserUseDisplaySettings: false

`searchMediaBrowserItemsPerRow`

Number of items to display in a single row of the section browser media list.

type: integer
required: false
default: 4
range: 1 - 6

Use a value of 1 to display the items as a vertical list.
Use a value of more than 1 to display the items in a horizontal list.

YAML Example

searchMediaBrowserItemsPerRow: 4

`searchMediaBrowserItemsHideTitle`

Hide title displayed for the section browser media list items.

type: boolean
required: false
default: false

If the Title is hidden, then the sub-title is also hidden.

YAML Example

searchMediaBrowserItemsHideTitle: false

`searchMediaBrowserItemsHideSubTitle`

Hide sub-title displayed for the section browser media list items.

type: boolean
required: false
default: false

YAML Example

searchMediaBrowserItemsHideSubTitle: true

`searchMediaBrowserItemsSortTitle`

True to sort displayed media browser item titles by name; otherwise, False to display them in the order returned from the Spotify Web API.

type: boolean
required: false
default: false

YAML Example

searchMediaBrowserItemsSortTitle: true

Manual Configuration Options

These options are configured manually by clicking on the Show Code Editor button on the card editor form.

`customImageUrls`

Collection of custom imageUrl's that can be displayed in various media browser displays. This allows the user to override the image that is supplied by the media player service, as well as provide imageUrl's for items that do not contain an image.

type: array[title: imageurl]
required: false
default: none

Some things to keep in mind when adding entries:

imageUrl titles are CaSe-SeNsItIvE.
imageUrl titles can contain special characters, but they are removed under the covers for the comparison process.
you can use "local" references for the imageUrl; any spaces in the filename are replaced with "%20".
you can use home assistant brands for the imageUrl; "logo.png" reference is replaced with "icon.png".
the "default" imageUrl title is used to supply an imageUrl for items that do not have an image.
I would suggest creating a special directory under the HA configuration directory www folder for these custom images - e.g. <configuration directory/www/images/spotifyplus_card_customimages. The images in this location can then be easily referenced using the /local/images/spotifyplus_card_customimages/filename.jpg syntax in the configuration editor.

The value array is comprised of title:value sub-items:

title is the media title to match on, or one of the special title values (see below). Any special characters in the title are removed before comparison. For example, if the media title is LiGhT rAiLs *ੈ✩‧₊˚ you would specify LiGhT rAiLs for the title value.
imageurl is the url path to the cover art image. This can reside in the config\www\ folder, can be a Home Assistant Brands icon, or a direct url to an image hosted on the web. For images found in the /config/www/..., just use a prefix of /local/... (see example below).

YAML Example
Provide custom images for the following media titles:

"My Private Playlist" - image in the Home Assistant config www folder location (e.g. /config/www/images/spotifyplus_card_customimages/my_private_playlist.png).
"Daily Mix 1" - uses Home Assistant Brands repository image for SpotifyPlus (e.g. Spotify logo).
"Daily Mix 2" - uses an external CDN url to the image (e.g. https://i.scdn.co/image/ab67616d0000b2734bfd0e91bf806bc73d736cfd).

customImageUrls:
  My Private Playlist: /local/images/spotifyplus_card_customimages/logo_spotify.png
  Daily Mix 1: https://brands.home-assistant.io/spotifyplus/icon.png
  Daily Mix 2: https://brands.home-assistant.io/spotifyplus/icon.png

The following special customImageUrls titles are also available:

customImageUrls - default

Specifies the media browser image to display when no image could be resolved. This will apply to all sections, including the Player background image if one could not be resolved. If a default custom image url is not specified, then a blank image is rendered.

YAML Example
```
customImageUrls:
  default: /local/images/spotifyplus_card_customimages/default.png
```
How it Looks
customImageUrls - playerBackground

Specifies the Player section background image to use when the player is powered on. This will override the entity_picture attribute of the media player; the background image will remain constant, and will not change as track / episodes change.

YAML Example
```
customImageUrls:
  playerBackground: /local/images/spotifyplus_card_customimages/playerBackground.jpg
```
How it Looks
customImageUrls - playerOffBackground

Specifies the Player section background image to use when the player is powered off.

YAML Example
```
customImageUrls:
  playerOffBackground: /local/images/spotifyplus_card_customimages/playerBackground.jpg
```
How it Looks

Title Formatter Options

The following keywords can be specified in various title fields, and are replaced with equivalent values from various sources.

Keywords related to playing media:
- {player.name} media player name (e.g. "LivingRoom Soundbar").
- {player.friendly_name} media player friendly name (e.g. "LivingRoom Soundbar").
- {player.media_album_name} currently playing media content album name (e.g. "It Is Well").
- {player.media_artist} currently playing media content artist (e.g. "Kutless").
- {player.media_title} currently playing media content title (e.g. "What Faith Can Do").
- {player.media_track} currently playing media content track (e.g. "What Faith Can Do").
- {player.state} media player current state (e.g. "playing", "off", etc).
- {player.sp_context_uri} Spotify uri for the currently playing context (e.g. "spotify:album:5ovMagVMhha9qq0OYDzXFm").
- {player.sp_playlist_name} Playlist name being played, if the current context is a playlist (e.g. "Daily Mix 1").
- {player.sp_playlist_name_title} Playlist name being played along with a "Playlist: " prefix, if the current context is a playlist (e.g. "Playlist: Daily Mix 1").
- {player.sp_playlist_uri} Playlist uri being played, if the current context is a playlist (e.g. "spotify:playlist:37i9dQZF1EYkqdzj48dyYq").
- {player.sp_item_type} Denotes the type of item being played: track, podcast, or audiobook.
Keywords related to active device:
- {player.source} media player source name (e.g. "LivingRoom Soundbar"). This is also the Spotify Connect RemoteName of the selected source device.
- {player.source_noaccount} same as {player.source} value.
- {player.sp_device_id} Spotify device identifier that is currently active (e.g. "5d4931f9d0684b625d702eaa24137b2c1d99539c").
- {player.sp_device_name} Spotify device name that is currently active (e.g. "Bose-ST10-2").
Keywords related to active Spotify user account:
- {player.sp_user_country} Country code for the active Spotify user account (e.g. "US").
- {player.sp_user_display_name} Display name for the active Spotify user account (e.g. "Todd L").
- {player.sp_user_email} Email address for the active Spotify user account (e.g. "[email protected]").
- {player.sp_user_id} User-id for the active Spotify user account (e.g. "31l77fh76whjfr7987fhebpfhqke").
- {player.sp_user_product} Product code for the active Spotify user account (e.g. "premium").
- {player.sp_user_uri} Uri for the active Spotify user account (e.g. "spotify:user:31l77fh76whjfr7987fhebpfhqke").
Keywords related to media list results:
- {medialist.lastupdatedon} Date and Time the media list was last refreshed.
- {medialist.itemcount} Number of items in the media list.

For date field replacements, the JavaScript toLocaleString() method is used to return the formatted date using the current locale.

YAML Example
Display the specified text along with the formatted date time of when the recently played media list was last updated on the device.
Renders the following: last updated on 5/10/2024, 10:43:20 AM

recentBrowserSubTitle: last updated on {player.soundtouchplus_recents_lastupdated}

Debug Support

Use the following instructions to enable / disable debugging support. If you are having problems with the card, the developers may ask you to enable debugging and capture the output.

All debug messages are written to the browser console.

Enable Debugging - Chrome

Use the following instructions to turn on debugging support for the card.

Open the developer tools; press F12 or right-click on the page and select "Inspect".
Open the console tab; in the developer tools, navigate to the "Console" tab.
Ensure the Verbose option in All Levels settings is checked.
Set the DEBUG environment variable: In the console, type the following command and press ENTER:
localStorage.setItem('debug', 'spotifyplus-card:*');
Refresh the page to see the debug messages appear in the console.

Disable Debugging - Chrome

Use the following instructions to turn off debugging support for the card.

Open the developer tools; press F12 or right-click on the page and select "Inspect".
Open the console tab; in the developer tools, navigate to the "Console" tab.
Reset the DEBUG environment variable; in the console, type the following command and press ENTER:
localStorage.setItem('debug', '');
Refresh the page to ensure no debug messages are logged.