-
Notifications
You must be signed in to change notification settings - Fork 0
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 SoundTouchPlus integration is installed, configured, and up to date.
Use the following index to get to where you want to be:
-
-
Header Status Area Options
-
playerHeaderTitle
Section Title -
playerHeaderArtistTrack
Artist and Track Info -
playerHeaderAlbum
Album Name Info -
playerHeaderNoMediaPlayingText
No Media Info -
playerHeaderHideProgressBar
Hide Progress Bar -
playerHeaderHide
Hide Status Area
-
-
Media Controls Area Options
-
playerControlsHidePlayPause
Hide Play Pause Control -
playerControlsHideRepeat
Hide Repeat Control -
playerControlsHideShuffle
Hide Shuffle Control -
playerControlsHideTrackNext
Hide Next Track Control -
playerControlsHideTrackPrev
Hide Previous Track Control -
playerControlsHide
Hide Media Controls
-
-
Volume Controls Area Options
-
playerVolumeControlsHideMute
Hide Volume Mute Control -
playerVolumeControlsHidePower
Hide Power Control -
playerVolumeControlsHide
Hide All Volume Controls
-
-
Header Status Area Options
-
-
presetBrowserItemsHideSource
Media Browser Hide Source -
presetBrowserItemsHideTitle
Media Browser Hide Title -
presetBrowserItemsPerRow
Media Browser Items Per Row -
presetBrowserSubTitle
Section Sub-Title -
presetBrowserTitle
Section Title
-
-
Recently Played Section Options
-
recentBrowserItemsHideSource
Media Browser Hide Source -
recentBrowserItemsHideTitle
Media Browser Hide Title -
recentBrowserItemsPerRow
Media Browser Items Per Row -
recentBrowserSubTitle
Section Sub-Title -
recentBrowserTitle
Section Title
-
-
-
pandoraBrowserItemsHideTitle
Media Browser Hide Title -
pandoraBrowserItemsPerRow
Media Browser Items Per Row -
pandoraBrowserSubTitle
Section Sub-Title -
pandoraBrowserTitle
Section Title -
pandoraSourceAccount
Source Account
-
-
-
customImageUrls
Custom Image URL's
-
These options control the overall look and feel of the card.
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 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
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 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 name of the media player.
Renders the following: SoundTouch Card "Bose-ST10-1"
title: SoundTouch Card "{player.name}"
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
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.
The following document the options for the Header Status area of the Player section.
TODO - update image.
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'
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: Kutless - What Faith Can Do
playerHeaderArtistTrack: '{player.media_artist} - {player.media_title}'
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: It is Well (Expanded Edition)
playerHeaderAlbum: '{player.media_album_name}'
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.
YAML Example
Display the specified text if no media is currently playing.
playerHeaderNoMediaPlayingText: 'No Media is Currently Playing'
Hide progress bar in the header area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerHeaderHideProgressBar: false
Hide header area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerHeaderHide: false
The following document the options for the Media Controls area of the Player section.
TODO - update image.
Hide play / pause button in the controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerControlsHidePlayPause: false
Hide repeat button in the controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerControlsHideRepeat: false
Hide shuffle button in the controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerControlsHideShuffle: false
Hide next track button in the controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerControlsHideTrackNext: false
Hide previous track button in the controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerControlsHideTrackPrev: false
Hide controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerControlsHide: false
The following document the options for the Volume Controls area of the Player section.
TODO - update image.
Hide mute button in the volume controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerVolumeControlsHideMute: false
Hide power button in the volume controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerVolumeControlsHidePower: false
Hide volume controls area of the Player section form.
- type: boolean
- required: false
- default: false
YAML Example
playerVolumeControlsHide: false
These options control the look and feel of the Presets section of the card.
Hide source titles displayed for Preset media browser items.
- type: boolean
- required: false
- default: false
YAML Example
presetBrowserItemsHideSource: false
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
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
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 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}
Title displayed at the top of the Preset media browser 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" Presets
presetBrowserTitle: '"{player.name}" Presets'
These options control the look and feel of the Recently Played section of the card.
Hide source titles displayed for Recently Played media browser items.
- type: boolean
- required: false
- default: false
YAML Example
recentBrowserItemsHideSource: false
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
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
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.
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}
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.
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'
These options control the look and feel of the Pandora section of the card.
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
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
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.
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}
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.
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'
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'
These options are configured manually by clicking on the Show Code Editor
button on the card editor form.
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 isLiGhT rAiLs *ੈ✩‧₊˚
you would specifyLiGhT rAiLs
for the title value. -
imageurl
is the url path to the cover art image. This can reside in theconfig\www\
folder, can be a Home Assistant Brands icon, or a direct url to an image hosted on the web. For images found in theconfig\www\
, just use a prefix of/local/...
(see example below).
The following special titles are available, and apply to various 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.
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
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 playerlastupdatedon
attribute. -
{config.pandorasourceaccount}
- Pandora source account named defined in the configuration.
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}
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:
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 selection box, or supply a valid entity_id
option keyword.
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 selection box, or supply a valid pandoraSourceAccount
option keyword.