Skip to content

Configuration Options

Jump to bottom
Todd Lucas edited this page May 10, 2024 · 39 revisions

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 is installed, configured, and up to date.

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

General Options

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

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).

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.

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 card title 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: 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

Preset Section Options

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

presetBrowserItemsHideSource Media Browser Hide Source

Hide source titles displayed for Preset media browser items.

  • type: boolean
  • required: false
  • default: false

YAML Example

presetBrowserItemsHideSource: false

presetBrowserItemsHideTitle Media Browser Hide Titles

Hide titles displayed for Preset 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 Preset 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 Preset media browser section form.

  • type: string
  • required: false
  • default: none

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

This value supports 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 Preset media browser section form.

  • type: string
  • required: false
  • default: none

Omit this parameter to hide the section title 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" Presets

presetBrowserTitle: '"{player.name}" Presets'

Recently Played Section Options

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

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 section sub-title display area.

This value supports 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 section title 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" Recently Played

recentBrowserTitle: '"{player.name}" Recently Played'

Pandora Section Options

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

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 section sub-title display area.

This value supports Title Formatter Options.

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

pandoraBrowserSubTitle: refreshed on {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 section title 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" Pandora

pandoraBrowserTitle: '"{player.name}" Pandora'

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 the special titles of default or empty preset. 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).

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 replace with equivalent values from various sources.

  • {player.name} media player friendly name (e.g. "LivingRoom Soundbar").
  • {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.
  • {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.

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}
Clone this wiki locally