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 [SoundTouchPlus integration](https://github.com/thlucas1/homeassistantcomponent_soundtouchplus/wiki) is installed, configured, and up to date.

Use the following index to get to where you want to be:
* [General Options](#general-options)
  * [`entity_id`](#entity_id-media-player-entity-id) Media Player Entity Id
  * [`height`](#height-card-height) Card Height
  * [`sections`](#sections-card-sections) Card Sections
  * [`title`](#title-title-text) Title Text
  * [`width`](#width-card-width) Card Width

* [Player Options](#player-section-options)

  * [Header Status Area Options](#player-header-status-area-options)

    * [`playerHeaderBackgroundColor`](#playerheaderbackgroundcolor-header-background-color) Header Background Color
    * [`playerHeaderTitle`](#playerheadertitle-section-title) Section Title
    * [`playerHeaderArtistTrack`](#playerheaderartisttrack-artist-and-track-info) Artist and Track Info
    * [`playerHeaderAlbum`](#playerheaderalbum-album-name-info) Album Name Info
    * [`playerHeaderNoMediaPlayingText`](#playerheadernomediaplayingtext-no-media-info) No Media Info
    * [`playerHeaderHideProgressBar`](#playerheaderhideprogressbar-hide-progress-bar) Hide Progress Bar
    * [`playerHeaderHide`](#playerheaderhide-hide-status-area) Hide Status Area
  
  * [Media Controls Area Options](#player-header-media-controls-area-options)

    * [`playerControlsBackgroundColor`](#playercontrolsbackgroundcolor-controls-background-color) Controls Background Color
    * [`playerControlsHidePlayPause`](#playercontrolshideplaypause-hide-play-pause-control) Hide Play Pause Control
    * [`playerControlsHideRepeat`](#playercontrolshiderepeat-hide-repeat-control) Hide Repeat Control
    * [`playerControlsHideShuffle`](#playercontrolshideshuffle-hide-shuffle-control) Hide Shuffle Control
    * [`playerControlsHideTrackNext`](#playercontrolshidetracknext-hide-next-track-control) Hide Next Track Control
    * [`playerControlsHideTrackPrev`](#playercontrolshidetrackprev-hide-previous-track-control) Hide Previous Track Control
    * [`playerControlsHide`](#playercontrolshide-hide-media-controls) Hide Media Controls

  * [Volume Controls Area Options](#player-header-volume-controls-area-options)

    * [`playerVolumeControlsHideMute`](#playervolumecontrolshidemute-hide-volume-mute-control) Hide Volume Mute Control
    * [`playerVolumeControlsHidePower`](#playervolumecontrolshidepower-hide-power-control) Hide Power Control
    * [`playerVolumeControlsHide`](#playervolumecontrolshide-hide-all-volume-controls) Hide All Volume Controls

* [Sources Section Options](#sources-section-options)
  * [`sourceBrowserItemsHideTitle`](#sourcebrowseritemshidetitle-browser-hide-titles) Browser Hide Title
  * [`sourceBrowserItemsPerRow`](#sourcebrowseritemsperrow-browser-items-per-row) Browser Items Per Row
  * [`sourceBrowserSubTitle`](#sourcebrowsersubtitle-section-sub-title) Section Sub-Title
  * [`sourceBrowserTitle`](#sourcebrowsertitle-section-title) Section Title

* [Device Preset Section Options](#device-preset-section-options)
  * [`presetBrowserItemsHideSource`](#presetbrowseritemshidesource-media-browser-hide-source) Media Browser Hide Source
  * [`presetBrowserItemsHideTitle`](#presetbrowseritemshidetitle-media-browser-hide-titles) Media Browser Hide Title
  * [`presetBrowserItemsPerRow`](#presetbrowseritemsperrow-media-browser-items-per-row) Media Browser Items Per Row
  * [`presetBrowserSubTitle`](#presetbrowsersubtitle-section-sub-title) Section Sub-Title
  * [`presetBrowserTitle`](#presetbrowsertitle-section-title) Section Title

* [User Preset Section Options](#user-preset-section-options)
  * [`userPresetBrowserItemsHideSource`](#userpresetbrowseritemshidesource-media-browser-hide-source) Media Browser Hide Source
  * [`userPresetBrowserItemsHideTitle`](#userpresetbrowseritemshidetitle-media-browser-hide-titles) Media Browser Hide Title
  * [`userPresetBrowserItemsPerRow`](#userpresetbrowseritemsperrow-media-browser-items-per-row) Media Browser Items Per Row
  * [`userPresetBrowserSubTitle`](#userpresetbrowsersubtitle-section-sub-title) Section Sub-Title
  * [`userPresetBrowserTitle`](#userpresetbrowsertitle-section-title) Section Title
  * [`userPresets`](#userpresets-user-preset-content-items) User Preset Content Items
  * [`userPresetsFile`](#userpresetsfile-user-preset-content-items-file) User Preset Content Items File

* [Recently Played Section Options](#recently-played-section-options)
  * [`recentBrowserItemsHideSource`](#recentbrowseritemshidesource-media-browser-hide-source) Media Browser Hide Source
  * [`recentBrowserItemsHideTitle`](#recentbrowseritemshidetitle-media-browser-hide-titles) Media Browser Hide Title
  * [`recentBrowserItemsPerRow`](#recentbrowseritemsperrow-media-browser-items-per-row) Media Browser Items Per Row
  * [`recentBrowserSubTitle`](#recentbrowsersubtitle-section-sub-title) Section Sub-Title
  * [`recentBrowserTitle`](#recentbrowsertitle-section-title) Section Title

* [Pandora Options](#pandora-section-options)
  * [`pandoraBrowserItemsHideTitle`](#pandorabrowseritemshidetitle-media-browser-hide-titles) Media Browser Hide Title
  * [`pandoraBrowserItemsPerRow`](#pandorabrowseritemsperrow-media-browser-items-per-row) Media Browser Items Per Row
  * [`pandoraBrowserSubTitle`](#pandorabrowsersubtitle-section-sub-title) Section Sub-Title
  * [`pandoraBrowserTitle`](#pandorabrowsertitle-section-title) Section Title
  * [`pandoraSourceAccount`](#pandorasourceaccount-section-title) Source Account

* [Manual Configuration Options](#manual-configuration-options)
  * [`customImageUrls`](#customimageurls-custom-image-urls) Custom Image URL's

* [Title Formatter Options](#title-formatter-options)

* [Troubleshooting](#troubleshooting)


## General Options

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

### How it Looks

<img src="images/ConfigurationOptions/general_editor_options.png?v01_20240919">

### `entity_id` Media Player Entity Id
SoundTouchPlus media player entity id that will be used to retrieve data from the SoundTouch device.  

- type: string
- required: true
- default: none

This must be a SoundTouchPlus integration media player, as it knows how to communicate with the SoundTouch device (other media players do not).

The Card Editor will display a `SoundTouchPlus media player entity id not configured` error message until this option is set with a valid value.

_YAML Example_  
```
entity: media_player.bose_st10_1
```  

### `height` Card 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
```  

### `sections` Card Sections
Controls which sections of the card will be visible.  

- type: string array
- required: false
- default: `[presets, recents]`

The following values are allowed:
- `presets` Presets section will be displayed.
- `recents` Recently Played section will be displayed.
- `pandorastations` Pandora Stations section will be displayed.
- `player` Media Player section (future enhancement - currently unsupported).

_YAML Example - All Sections_  
This will enable the Presets, Recently Played, and Pandora Station sections of the card.
```
sections:
  - presets
  - recents
  - pandorastations
```  

_YAML Example - Pandora Stations Section_  
This will enable only the Pandora Station section of the card.
```
sections:
  - pandorastations
```  

### `title` Title Text
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](#title-formatter-options).

_YAML Example_  
Display the specified text along with the name of the media player.  
Renders the following:  `SoundTouch Card "Bose-ST10-1"`
```
title: SoundTouch Card "{player.name}"
```  

### `width` Card 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
```  

## Player Section Options

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

### Player Header Status Area Options

The following document the options for the Header Status area of the Player section.

### How it Looks

<img src="images/ConfigurationOptions/player_header_options.png?v01_20240919">

### `playerHeaderBackgroundColor` Header Background Color
Color value for the Player header area background gradient, in #HHRRGGBB format.  
Specify 'transparent' to hide the background area.  

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

_YAML Example_  
```
playerHeaderBackgroundColor: transparent
```  

### `playerHeaderTitle` Section Title
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](#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
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](#title-formatter-options).

_YAML Example_  
Display the currently playing artist and media track title.  
Renders the following:  `Kutless - What Faith Can Do`
```
playerHeaderArtistTrack: '{player.media_artist} - {player.media_title}'
```  

### `playerHeaderAlbum` Album Name Info
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](#title-formatter-options).

_YAML Example_  
Display the currently playing media album name.  
Renders the following:  `It is Well (Expanded Edition)`
```
playerHeaderAlbum: '{player.media_album_name}'
```  

### `playerHeaderNoMediaPlayingText` No Media Info
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](#title-formatter-options).

_YAML Example_  
Display the specified text if no media is currently playing.  
```
playerHeaderNoMediaPlayingText: 'No Media is Currently Playing'
```  

### `playerHeaderHideProgressBar` Hide Progress Bar
Hide progress bar in the header area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerHeaderHideProgressBar: false
```  

### `playerHeaderHide` Hide Status Area
Hide header area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerHeaderHide: false
```  

### Player Media Controls Area Options

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

### How it Looks

<img src="images/ConfigurationOptions/player_controls_options.png?v01_20240919">

### `playerControlsHidePlayPause` Hide Play Pause Control
Hide play / pause button in the controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerControlsHidePlayPause: false
```  

### `playerControlsHideRepeat` Hide Repeat Control
Hide repeat button in the controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerControlsHideRepeat: false
```  

### `playerControlsHideShuffle` Hide Shuffle Control
Hide shuffle button in the controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerControlsHideShuffle: false
```  

### `playerControlsHideTrackNext` Hide Next Track Control
Hide next track button in the controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerControlsHideTrackNext: false
```  

### `playerControlsHideTrackPrev` Hide Previous Track Control
Hide previous track button in the controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerControlsHideTrackPrev: false
```  

### `playerControlsHide` Hide Media Controls
Hide controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerControlsHide: false
```  

### Player Header Volume Controls Area Options

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

### How it Looks

<img src="images/ConfigurationOptions/player_volume_options.png?v01_20240919">

### `playerVolumeControlsHideMute` Hide Volume Mute Control
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 Control
Hide power button in the volume controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerVolumeControlsHidePower: false
```  

### `playerVolumeControlsHide` Hide All Volume Controls
Hide volume controls area of the Player section form.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
playerVolumeControlsHide: false
```  

### `playerControlsBackgroundColor` Controls Background Color
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
```  


## Sources Section Options

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

### How it Looks

<img src="images/ConfigurationOptions/sources_options.png?v01_20240919">

### `sourceBrowserItemsHideTitle` Browser Hide Titles
Hide titles displayed for Sources browser items.

- type: boolean
- required: false
- default: false

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

_YAML Example_  
```
sourceBrowserItemsHideTitle: false
```  

### `sourceBrowserItemsPerRow` Browser Items per Row
Number of items to display in a single row of the Sources browser section form.

- type: integer
- required: false
- default: 3
- 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_  
```
sourceBrowserItemsPerRow: 3
```  

### `sourceBrowserSubTitle` Section Sub-Title
Sub-Title displayed at the top of the Sources browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the formatted date time of when the Sources list was last updated on the device.  
Renders the following:  `last updated on 5/10/2024, 10:43:20 AM`
```
sourceBrowserSubTitle: last updated on {medialist.lastupdatedon}
```  

### `sourceBrowserTitle` Section Title
Title displayed at the top of the Sources browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the name of the media player.  
Renders the following:  `"Bose-ST10-1" Sources`
```
sourceBrowserTitle: '"{player.name}" Sources'
```  


## Device Preset Section Options

These options control the look and feel of the Device Presets section of the card.

### How it Looks

<img src="images/ConfigurationOptions/preset_options_device.png?v01_20240919">

### `presetBrowserItemsHideSource` Media Browser Hide Source
Hide source titles displayed for media browser items.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
presetBrowserItemsHideSource: false
```  

### `presetBrowserItemsHideTitle` Media Browser Hide Titles
Hide titles displayed for media browser items.

- type: boolean
- required: false
- default: false

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

_YAML Example_  
```
presetBrowserItemsHideTitle: false
```  

### `presetBrowserItemsPerRow` Media Browser Items per Row
Number of items to display in a single row of the media browser section form.

- type: integer
- required: false
- default: 3
- 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_  
```
presetBrowserItemsPerRow: 3
```  

### `presetBrowserSubTitle` Section Sub-Title
Sub-Title displayed at the top of the media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the formatted date time of when a preset was last set (or cleared) on the device.  
Renders the following:  `last updated on 5/10/2024, 10:43:20 AM`
```
presetBrowserSubTitle: last updated on {player.soundtouchplus_presets_lastupdated}
```  

### `presetBrowserTitle` Section Title
Title displayed at the top of the media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the name of the media player.  
Renders the following:  `"Bose-ST10-1" Device Presets`
```
presetBrowserTitle: '"{player.name}" Device Presets'
```  


## User Preset Section Options

These options control the look and feel of the User Presets section of the card.

### How it Looks

<img src="images/ConfigurationOptions/preset_options_user.png?v01_20240919">

### `userPresetBrowserItemsHideSource` Media Browser Hide Source
Hide source titles displayed for media browser items.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
userPresetBrowserItemsHideSource: false
```  

### `userPresetBrowserItemsHideTitle` Media Browser Hide Titles
Hide titles displayed for media browser items.

- type: boolean
- required: false
- default: false

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

_YAML Example_  
```
userPresetBrowserItemsHideTitle: false
```  

### `userPresetBrowserItemsPerRow` Media Browser Items per Row
Number of items to display in a single row of the media browser section form.

- type: integer
- required: false
- default: 3
- 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: 3
```  

### `userPresetBrowserSubTitle` Section Sub-Title
Sub-Title displayed at the top of the media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the formatted date time of when the media list was retrieved from the configuration.  
Renders the following:  `last updated on 5/10/2024, 10:43:20 AM`
```
userPresetBrowserSubTitle: last updated on { medialist.lastupdatedon }
```  

### `userPresetBrowserTitle` Section Title
Title displayed at the top of the media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the name of the media player.  
Renders the following:  `"Bose-ST10-1" User Presets`
```
userPresetBrowserTitle: '"{player.name}" User Presets'
```  

### `userPresets` User Preset Content Items
Media content item entries that represent the content to play.

- type: array of ContentItemParent objects.
- required: false
- default: none

Omit this parameter to not define any user presets.

_YAML Example_  
The following tries to document the various popular sources that are available to play content from.  
This is by no means a complete list.  
Substitute your user-specific information in the various items (e.g. "yourSpotifySourceAccount" with your Spotify user-id value, "yourPandoraUserId" with your Pandora user-id value, etc).
```
userPresets:
  - ContentItem:
      Name: K-Love Radio
      ContainerArt: 'http://cdn-profiles.tunein.com/s33828/images/logog.png?t=637986894890000000'
      Location: '/v1/playback/station/s33828'
      Source: TUNEIN
      TypeValue: stationurl
  - ContentItem:
      Name: Spotify Playlist Daily Mix 1
      ContainerArt: 'https://dailymix-images.scdn.co/v2/img/ab6761610000e5ebcd3f796bd7ea49ed7615a550/1/en/default'
      Location: 'spotify:playlist:37i9dQZF1E39vTG3GurFPW'
      Source: SPOTIFY
      SourceAccount: yourSpotifySourceAccount
      TypeValue: uri
  - ContentItem:
      Name: Spotify Artist Mercy Me
      ContainerArt: 'https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b'
      Location: 'spotify:artist:6APm8EjxOHSYM5B4i3vT3q'
      Source: SPOTIFY
      SourceAccount: yourSpotifySourceAccount
      TypeValue: uri
  - ContentItem:
      Name: Spotify Album Welcome to the New
      ContainerArt: 'https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b'
      Location: 'spotify:album:6vc9OTcyd3hyzabCmsdnwE'
      Source: SPOTIFY
      SourceAccount: yourSpotifySourceAccount
      TypeValue: uri
  - ContentItem:
      Name: Track I Still Believe
      ContainerArt: 'https://i.scdn.co/image/ab67616d0000b27391efaaa4c9b4b311ddc428b0'
      Location: 'spotify:track:3EtOah8NqZ1FqpQR837v0z'
      Source: SPOTIFY
      SourceAccount: yourSpotifySourceAccount
      TypeValue: uri
  - ContentItem:
      Name: Spotify Episode We Can Do Hard Things
      ContainerArt: 'https://i.scdn.co/image/ab6765630000ba8a31936fcc7887c8a10ba9af9d'
      Location: 'spotify:episode:3tWDribcG7X5Q6KBx8xupp'
      Source: SPOTIFY
      SourceAccount: yourSpotifySourceAccount
      TypeValue: uri
  - ContentItem:
      Name: Spotify Podcast K-Love On The Mic
      ContainerArt: 'https://i.scdn.co/image/206f1a5d5e27e9516a5c0cdb06ee3ae079a78ac9'
      Location: 'spotify:show:39EidgdUzHLZ1Wab01NiGk'
      Source: SPOTIFY
      SourceAccount: yourSpotifySourceAccount
      TypeValue: uri
  - ContentItem:
      Name: Pandora Zach Williams Radio
      ContainerArt: 'https://content-images.p-cdn.com/images/68/88/0d/fb/aed34095a11118d2aa7b02a2/_500W_500H.jpg'
      Location: '126740707481236361'
      Source: PANDORA
      SourceAccount: yourPandoraUserId
  - ContentItem:
      Name: NAS Album
      ContainerArt: http://192.168.1.1:10243/WMPNSSv4/2050238549/0_N18xMTRlOGRlOS00MDE5.jpg?albumArt=true
      Location: '7_11412345'
      Source: STORED_MUSIC
      SourceAccount: 'd09708a1-5953-44bc-a413-123456789012/0'
  - ContentItem:
      Name: DLNA Album
      ContainerArt: http://192.168.1.1:8085/v1/albums/983/image?_=1&amp;w=62
      Location: 'album:983'
      Source: LOCAL_MUSIC
      SourceAccount: '3f205110-4a57-4e91-810a-ad949d25abb2'
      TypeValue: album
```  

### `userPresetsFile` User Preset Content Items File
Media content item entries that represent the content to play, stored in a JSON file format.  Use this option if you wish to share your presets among multiple card definitions.

- type: array of ContentItemParent objects in JSON format
- required: false
- default: none

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

_YAML Example_  
This will look for the file in your HA configration directory (e.g. where configuration.yaml resides) `www` folder: `/config/www/soundtouchplus/userpresets.json`.
```
userPresetsFile: /local/soundtouchplus/userpresets.json
```
_JSON File Example_  
The following tries to document the various popular sources that are available to play content from.  
This is by no means a complete list.  
Substitute your user-specific information in the various items (e.g. "yourSpotifySourceAccount" with your Spotify user-id value, "yourPandoraUserId" with your Pandora user-id value, etc).
```
[
  {
    "ContentItem": {
      "Name": "K-Love Radio",
      "ContainerArt": "http://cdn-profiles.tunein.com/s33828/images/logog.png?t=637986894890000000",
      "Location": "/v1/playback/station/s33828",
      "Source": "TUNEIN",
      "TypeValue": "stationurl"
    }
  },
  {
    "ContentItem": {
      "Name": "Playlist Daily Mix 1",
      "ContainerArt": "https://dailymix-images.scdn.co/v2/img/ab6761610000e5ebcd3f796bd7ea49ed7615a550/1/en/default",
      "Location": "spotify:playlist:37i9dQZF1E39vTG3GurFPW",
      "Source": "SPOTIFY",
      "SourceAccount": "yourSpotifySourceAccount",
      "TypeValue": "uri"
    }
  },
  {
    "ContentItem": {
      "Name": "Artist Mercy Me",
      "ContainerArt": "https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b",
      "Location": "spotify:artist:6APm8EjxOHSYM5B4i3vT3q",
      "Source": "SPOTIFY",
      "SourceAccount": "yourSpotifySourceAccount",
      "TypeValue": "uri"
    }
  },
  {
    "ContentItem": {
      "Name": "Album Welcome to the New",
      "ContainerArt": "https://i.scdn.co/image/ab67616d0000b27316c019c87a927829804caf0b",
      "Location": "spotify:album:6vc9OTcyd3hyzabCmsdnwE",
      "Source": "SPOTIFY",
      "SourceAccount": "yourSpotifySourceAccount",
      "TypeValue": "uri"
    }
  },
  {
    "ContentItem": {
      "Name": "Track I Still Believe",
      "ContainerArt": "https://i.scdn.co/image/ab67616d0000b27391efaaa4c9b4b311ddc428b0",
      "Location": "spotify:track:3EtOah8NqZ1FqpQR837v0z",
      "Source": "SPOTIFY",
      "SourceAccount": "yourSpotifySourceAccount",
      "TypeValue": "uri"
    }
  },
  {
    "ContentItem": {
      "Name": "Episode We Can Do Hard Things",
      "ContainerArt": "https://i.scdn.co/image/ab6765630000ba8a31936fcc7887c8a10ba9af9d",
      "Location": "spotify:episode:3tWDribcG7X5Q6KBx8xupp",
      "Source": "SPOTIFY",
      "SourceAccount": "yourSpotifySourceAccount",
      "TypeValue": "uri"
    }
  },
  {
    "ContentItem": {
      "Name": "Podcast K-Love On The Mic",
      "ContainerArt": "https://i.scdn.co/image/206f1a5d5e27e9516a5c0cdb06ee3ae079a78ac9",
      "Location": "spotify:show:39EidgdUzHLZ1Wab01NiGk",
      "Source": "SPOTIFY",
      "SourceAccount": "yourSpotifySourceAccount",
      "TypeValue": "uri"
    }
  },
  {
    "ContentItem": {
      "Name": "Zach Williams Radio",
      "ContainerArt": "https://content-images.p-cdn.com/images/68/88/0d/fb/aed34095a11118d2aa7b02a2/_500W_500H.jpg",
      "Location": "126740707481236361",
      "Source": "PANDORA",
      "SourceAccount": "yourPandoraUserId"
    }
  },
  {
    "ContentItem": {
      "Name": "NAS Album",
      "ContainerArt": "http://192.168.1.1:10243/WMPNSSv4/2050238549/0_N18xMTRlOGRlOS00MDE5.jpg?albumArt=true",
      "Location": "7_11412345",
      "Source": "STORED_MUSIC",
      "SourceAccount": "d09708a1-5953-44bc-a413-123456789012/0"
    }
  },
  {
    "ContentItem": {
      "Name": "DLNA Album",
      "ContainerArt": "http://192.168.1.1:8085/v1/albums/983/image?_=1&amp;w=62",
      "Location": "album:983",
      "Source": "LOCAL_MUSIC",
      "SourceAccount": "3f205110-4a57-4e91-810a-ad949d25abb2",
      "TypeValue": "album"
    }
  }
]
```


## Recently Played Section Options

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

### How it Looks

<img src="images/ConfigurationOptions/recently_played_options.png?v01_20240919">

### `recentBrowserItemsHideSource` Media Browser Hide Source
Hide source titles displayed for Recently Played media browser items.

- type: boolean
- required: false
- default: false

_YAML Example_  
```
recentBrowserItemsHideSource: false
```  

### `recentBrowserItemsHideTitle` Media Browser Hide Titles
Hide titles displayed for Recently Played media browser items.

- type: boolean
- required: false
- default: false

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

_YAML Example_  
```
recentBrowserItemsHideTitle: false
```  

### `recentBrowserItemsPerRow` Media Browser Items per Row
Number of items to display in a single row of the Recently Played media browser section form.

- type: integer
- required: false
- default: 3
- 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: 3
```  

### `recentBrowserSubTitle` Section Sub-Title
Sub-Title displayed at the top of the Recently Played media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_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}
```  

### `recentBrowserTitle` Section Title
Title displayed at the top of the Recently Played media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the name of the media player.  
Renders the following:  `"Bose-ST10-1" Recently Played`
```
recentBrowserTitle: '"{player.name}" Recently Played'
```  


## Pandora Section Options

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

### How it Looks

<img src="images/ConfigurationOptions/pandora_options.png?v01_20240919">

### `pandoraBrowserItemsHideTitle` Media Browser Hide Titles
Hide titles displayed for Pandora media browser items.

- type: boolean
- required: false
- default: false

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

_YAML Example_  
```
pandoraBrowserItemsHideTitle: false
```  

### `pandoraBrowserItemsPerRow` Media Browser Items per Row
Number of items to display in a single row of the Pandora media browser section form.

- type: integer
- required: false
- default: 3
- 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_  
```
pandoraBrowserItemsPerRow: 9
```  

### `pandoraBrowserSubTitle` Section Sub-Title
Sub-Title displayed at the top of the Pandora media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the formatted date time of when the media list was last refreshed.  
Renders the following:  `refreshed on 5/10/2024, 10:43:20 AM`
```
pandoraBrowserSubTitle: refreshed on {medialist.lastupdatedon}
```  

### `pandoraBrowserTitle` Section Title
Title displayed at the top of the Pandora media browser section form.

- type: string
- required: false
- default: none

Omit this parameter to hide the display area.  

This value supports [Title Formatter Options](#title-formatter-options).

_YAML Example_  
Display the specified text along with the name of the media player.  
Renders the following:  `"Bose-ST10-1" Pandora`
```
pandoraBrowserTitle: '"{player.name}" Pandora'
```  

### `pandoraSourceAccount` Source Account
Source account (e.g. Pandora username) used to connect to the Pandora music service.  

- type: string
- required: true
- default: none

This account MUST be defined in the SoundTouch device source list.

_YAML Example_  
```
pandoraSourceAccount: 'JohnSmith@yahoo.com'
```  


## Manual Configuration Options

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

### `customImageUrls` Custom Image URL's
Provides custom images to display for media items based upon a matching title name.   

Also provides custom images for media items that have no covert art image url, as well as empty preset slots.

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

The value array is comprised of `title:value` sub-items:
- `title` is the track title to match on, or one of the special titles values (see below).  Any special characters in the title are removed before comparison.  For example, if the track 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).

The following special titles are available, and apply to various [section content](Card-Features#section-content):
- `default` - media browser image to display when no image is present.
- `empty preset` - media browser image to display for empty presets in the Preset section.
- `playerBackground` - background image to display for the Player section when the player is powered on.  This will override the entity_picture attribute of the media player.
- `playerOffBackground` - background image to display for the Player section when the player is powered off.  

_YAML Example_  
Provide custom images for the following track titles:
- "My Private Playlist" - image in the Home Assistant config www folder location (e.g. `/config/www/images/soundtouchplus_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`).
- "default" - image in the Home Assistant config www folder location (e.g. `/config/www/images/soundtouchplus_card_customimages/default.png`)
- "empty preset" - image in the Home Assistant config www folder location (e.g. `/config/www/images/soundtouchplus_card_customimages/empty_preset.png`)

```
customImageUrls:
  default: /local/images/soundtouchplus_card_customimages/default.png
  empty preset: /local/images/soundtouchplus_card_customimages/empty_preset.png
  My Private Playlist: /local/images/soundtouchplus_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
```  


## Title Formatter Options

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

- `{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, varies by music service (e.g. "01", "What Faith Can Do", etc).
- `{player.source}` media player current source name (e.g. "Spotify (youraccount)").
- `{player.source_noaccount}` media player current source name (e.g. "Spotify").
- `{player.soundtouchplus_presets_lastupdated}` Date and Time the preset list was last refreshed from the device.
- `{player.soundtouchplus_recents_lastupdated}` Date and Time the recents list was last refreshed from the device.
- `{player.soundtouchplus_recents_cache_lastupdated}` Date and Time the recents list cache was last refreshed from the local file system.
- `{player.state}` media player current state (e.g. "playing", "off", etc).
- `{config.pandorasourceaccount}` - Pandora source account named defined in the configuration.
- `{medialist.lastupdatedon}` Date and Time the media list was last refreshed from the device; only used for services that don't have a media player `lastupdatedon` attribute.
- `{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}
```  


## Troubleshooting

This section tries to document common problems that you might encounter while configuring the card.

Use the following index to get to where you want to be:
* [Error - Entity id not configured](#error---entity-id-not-configured)
* [Error - Pandora user account not configured](#error---pandora-user-account-not-configured)


### Error - Entity id not configured
The `SoundTouchPlus media player entity id not configured` message appears when the entity id value has not been set to a valid SoundTouchPlus integration media player entity id value.  

To fix, select a value from the [Media Player Entity Id](#entity_id-media-player-entity-id) selection box, or supply a valid `entity_id` option keyword.

<img src="images/ConfigurationOptions/error_entityid_not_configured.png?v01_20240919">

### Error - Pandora user account not configured
The `Pandora user account not configured` message appears in the Pandora section's media list when a valid Pandora user account value has not been set.  If entered manually, the user account value must match what is configured on the SoundTouch device.

To fix, select a value from the [Pandora Source Account](#pandorasourceaccount-source-account) selection box, or supply a valid `pandoraSourceAccount` option keyword.

<img src="images/ConfigurationOptions/error_pandora_user_not_configured.png?v01_20240919">