Sonos Card for Home Assistant UI with a focus on managing multiple media players!
This card is nearly identical to the Maxi Media Player, but is optimized for Sonos players. It will, by default, automatically discover all Sonos players in your Home Assistant instance. It also includes some Sonos specific features like queue management and sleep timer.
and more!
Do you like the Sonos Card? Support the project with a coffee ![]()
Recommended way of installing this card is with HACS Home Assistant Community Store.
By default, all sections of the card is available, and you can jump between them in the footer of the card.
However, you can also select individual sections to enable. Use this if you want to show the different sections next to
each other (by adding multiple instances of the card with different sections enabled).
By using the section configuration you can utilise the full power of Home Assistant’s layout capabilities and also drag in other cards in your Dashboard view.
sections: # Choose which sections to show in the card. Available sections are:
- volumes
- groups
- grouping
- media browser
- player
- queue
- search
Use the Visual Editor in Home Assistant to configure the card. Most options are available there.
type: custom:sonos-card
entities: # Entities are automatically discovered if you don't supply this setting. You can also use this sort your entities in a specific order (instead of alphabetically).
- media_player.sonos_kitchen
- media_player.sonos_hallway
- media_player.sonos_bedroom
- media_player.sonos_livingroom
excludeItemsInEntitiesList: true # Will invert the selection in the `entities` list, so that all players that are not in the list will be used.
showNonSonosPlayers: true # default is false, which means only Sonos players will be shown.
title: ''
sections: # see explanation further up
- media browser
- player
baseFontSize: 1.5 # default is 1. Unit is 'rem'. Use this to change the base font size for the entire card.
doNotRememberSelectedPlayer: true # default is false. If set to true, the selected player will not be remembered in URL hash or session storage.
entityId: media_player.bedroom # Forces this player to be the selected one on loading the card (overrides url param etc)
entityNameRegexToReplace: ' PLAYER' # Regex pattern to replace parts of the entity names
entityNameReplacement: ''
fontFamily: 'Roboto, sans-serif' # Use this to change the font family for the entire card.
footerHeight: 4 # default is 5. Unit is 'rem'. Use this to change the height of the footer.
heightPercentage: 75 # default is 100. Use this to change the height of the card. Set to 'auto' to make the card height adjust to the content.
mediaTitleRegexToReplace: '.wav?.*' # Regex pattern to replace parts of the media title
mediaTitleReplacement: ' radio' # Replacement for the media title regex pattern
minWidth: 10 # default is 20. Unit is 'rem'. Use this to change the minimum width of the card.
sectionButtonIconSize: 5 # Set the size of section button icons in rem units (e.g., 5 for 5rem)
sectionButtonIcons: # customize icons for the section buttons
player: mdi:ab-testing
mediaBrowser: mdi:star-box-multiple
groups: mdi:multicast
grouping: mdi:group
volumes: mdi:volume-high
startSection: groups # default is player. Use this to set the default section to show.
storePlayerInSessionStorage: true # default is false. If set to true, the active player will be stored in the session storage instead of URL hash.
widthPercentage: 75 # default is 100. Use this to change the width of the card.
allowPlayerVolumeEntityOutsideOfGroup: true # default is false. Will allow the playerVolumeEntityId to be outside the group of the selected player.
dynamicVolumeSlider: true # default is false. See more in section further down.
dynamicVolumeSliderMax: 40 # default is 30. Use this to change the max value for the dynamic volume slider.
dynamicVolumeSliderThreshold: 30 # default is 20. Use this to change the threshold for the dynamic volume slider.
entitiesToIgnoreVolumeLevelFor: # default is empty. Use this if you want to ignore volume level for certain players in the player section. Useful if you have a main device with fixed volume.
- media_player.my_sonos_port_device
entityPlatform: music_assistant # default is empty.
predefinedGroups: # defaults to empty. More advanced features in separate section further down.
- name: Inside
volume: 15 # If you want to set the volume of all speakers when grouping
unmuteWhenGrouped: true # If you want to unmute all speakers when grouping
entities:
- media_player.bedroom
- media_player.hall
- name: Kitchen&Hall
media: Legendary # If you want to start playing a specific favorite when grouping
entities: # Use below format if you want to set the volume of the speakers when grouping
- player: media_player.kitchen
volume: 10
- player: media_player.hall
volume: 5
- name: All (except TV)
excludeItemsInEntitiesList: true # Invert entities selection, so that all players will be grouped except those in the entities list
entities:
- media_player.tv
# below advanced settings for predefined groups fully depend on what features your device supports
- name: Party Mode # Example with device-specific settings
bass: 10 # Set bass level (-10 to 10)
treble: -2 # Set treble level (-10 to 10)
loudness: true # Enable/disable loudness
entities:
- media_player.living_room
- media_player.kitchen
- name: Podcast Mode
bass: -5
loudness: false
speechEnhancement: true # Enable speech enhancement (soundbars only)
nightSound: true # Enable night sound mode (soundbars only)
entities:
- media_player.living_room
- name: All with Crossfade
crossfade: true # Enable/disable crossfade between tracks
touchControls: true # Enable/disable touch controls
statusLight: false # Enable/disable status light
entities:
- media_player.bedroom
- media_player.hall
player:
hideHeader: true # default is false. Hides the player header (entity name, song, album, progress).
artworkAsBackground: true # default is false. Will show the artwork as background for the player section.
artworkAsBackgroundBlur: 10 # default is 0 (no blur). Adds a blur effect to the background artwork and shows the normal artwork on top. Higher values = more blur. Creates a modern look similar to Apple Music. Implies artworkAsBackground.
artworkBorderRadius: 10 # default is 0. Adds a border radius to the player artwork in pixels.
artworkHostname: http://192.168.0.59:8123 #default is ''. Usually not needed, but depending on your setup your device might not be able to access the artwork on the default host. One example where it could be needed is if you cast the dashboard with Google Cast.
artworkMinHeight: 10 # default is 5. Use this to change the minimum height of the artwork in the player section. Unit is in rem.
fallbackArtwork: https://cdn-icons-png.flaticon.com/512/651/651717.png # Override default fallback artwork image if artwork is missing for the currently selected media.
fastForwardAndRewindStepSizeSeconds: 60 # default is 15 seconds
hideArtwork: true # default is false. Hides the artwork in the player section.
labelWhenNoMediaIsSelected: 'No media selected'
mediaArtworkOverrides: # Show your own selected artwork if certain rules match
- mediaTitleEquals: TV
imageUrl: https://cdn-icons-png.flaticon.com/512/716/716429.png
sizePercentage: 40
- mediaContentIdEquals: 'x-htastream:RINCON_949F3EC2E15B01400:spdif'
imageUrl: https://cdn-icons-png.flaticon.com/512/4108/4108783.png
- mediaTitleEquals: p4malmo-aac-192
imageUrl: >-
https://mytuner.global.ssl.fastly.net/media/tvos_radios/2BDTPrpMbn_cTdteqo.jpg
- mediaArtistEquals: Metallica
imageUrl: >-
https://mytuner.global.ssl.fastly.net/media/tvos_radios/2BDTPrpMbn_cTdteqo.jpg
- mediaAlbumNameEquals: 'Master of Puppets'
imageUrl: >-
https://mytuner.global.ssl.fastly.net/media/tvos_radios/2BDTPrpMbn_cTdteqo.jpg
- mediaChannelEquals: 'Sky Radio Smooth Hits'
imageUrl: https://cdn-icons-png.flaticon.com/512/4108/4108794.png
- mediaTitleRegexp: ^NRK # Use regexp to match multiple titles, e.g. NRK P1, NRK P2, NRK P3
imageUrl: https://upload.wikimedia.org/wikipedia/commons/thumb/0/0f/NRK_logo.svg/200px-NRK_logo.svg.png
sizePercentage: 50
- mediaArtistRegexp: '.*Radio.*' # Regexp matching any artist containing "Radio"
imageUrl: https://cdn-icons-png.flaticon.com/512/3659/3659784.png
- mediaAlbumNameRegexp: 'Greatest.*Hits' # Regexp matching album names like "Greatest Hits", "Greatest Love Hits"
imageUrl: https://cdn-icons-png.flaticon.com/512/3844/3844724.png
- mediaContentIdRegexp: 'spotify:.*' # Regexp matching Spotify content IDs
imageUrl: https://cdn-icons-png.flaticon.com/512/174/174872.png
- mediaChannelRegexp: '^P[1-4]$' # Regexp matching channels P1, P2, P3, P4
imageUrl: https://cdn-icons-png.flaticon.com/512/2995/2995101.png
- ifMissing: true # ifMissing will only be used if none of the "Equals" or "Regexp" overrides above resulted in a match
imageUrl: https://cdn-icons-png.flaticon.com/512/651/651758.png
- mediaTitleEquals: 'My Radio Station' # imageUrl supports templates
imageUrl: '{{ states("sensor.my_cover_image_entity") }}'
backgroundOverlayColor: 'rgba(0,0,0, 0.3)' # When artworkAsBackground is true, this sets the background overlay color for controls and header.
controlsAndHeaderBackgroundOpacity: 0.7 # default is 0.9. Adjusts the opacity of the header and controls background when artworkAsBackground is enabled. Range 0-1.
controlsColor: pink # default is theme color. Use this to change the color of player control icons.
controlsLargeIcons: true # default is false. Makes the player control icons larger.
controlsMargin: '0 3rem' # default is '0.25rem'. Use this to change the margin around the player controls area.
headerEntityFontSize: 0.8 # default is 1. Unit is 'rem'. Use this to change the font size of the entity name in the player header.
headerSongFontSize: 1.2 # default is 1.15. Unit is 'rem'. Use this to change the font size of the song title in the player header.
hideArtistAlbum: true # default is false. Hides the artist/album text in the player header.
hideControlNextTrackButton: true # default is false, hides player control next track button.
hideControlPowerButton: true # default is false, hides player control power button if media player TURN_ON feature is enabled. This setting does nothing if media player TURN_ON feature is not supported.
hideControlPrevTrackButton: true # default is false, hides player control previous track button.
hideControlRepeatButton: true # default is false, hides player control track repeat mode button.
hideControlShuffleButton: true # default is false, hides player control track shuffle mode button.
hideControls: true # default is false. Hides the player controls (play/pause, next, prev, volume, etc.).
hideEntityName: true # default is false. Hides the entity/group name in the player header.
hidePlaylist: true # default is false. Will hide the playlist name in the player section.
hideVolume: true # default is false. Hides the entire volume component in the player.
hideVolumeMuteButton: true # default is false. Hides the mute/unmute button in the player.
hideVolumePercentage: true # default is false. Hides the volume percentage display in the player.
volumeMuteButtonSize: 2 # default is 2.5. Unit is 'rem'. Use this to change the size of the mute button in the player.
volumeSliderHeight: 0.5 # default is 1.5. Unit is 'rem'. Use this to change the height of the volume slider in the player.
volumeEntityId: media_player.bedroom # default is empty. Use this to control the volume of another player in the player section. Entity ID must the selected player or part of the selected player's group, otherwise it will not be controlled.
showAudioInputFormat: true # default is false. Will show the audio input format (e.g. Dolby Digital) in the player section if available. By default, it will only show if the input format in the volumes section.
showBrowseMediaButton: true # default is false. Will show the browse media button in the player section.
showChannel: true # default is false. Will show the channel (if available) in the player section. This can for instance be the radio station name.
showFastForwardAndRewindButtons: true # default is false, shows fast-forward and rewind buttons
showSource: true # default is false. Will show the source (if available) in the player section.
showVolumeUpAndDownButtons: true # default is false, shows buttons for increasing and decreasing volume
stopInsteadOfPause: true # default is false. Will show the stop button instead of the pause button when media is playing.
mediaBrowser:
hideHeader: true # default is false. Hides the header of the media browser section (title and navigation buttons).
itemsPerRow: 1 # default is 4. Use this to show items as list. Applies to both favorites and media browser.
onlyFavorites: true # default is false. Hides the media browser button, showing only favorites.
shortcut: # Optional shortcut button for quick access to a specific folder in the media browser. media_content_id, media_content_type, and name are required.
media_content_id: 'media-source://spotify/library/made-for-you' # Required: The content ID of the folder
media_content_type: 'spotify://library' # Required: The content type
icon: 'mdi:spotify' # Optional: Icon for the shortcut button (default is bookmark icon)
name: 'Made for You' # Required: Tooltip/name for the shortcut button
favorites: # Settings specific to the favorites view within media browser
title: My favorites # default is 'Favorites'. Use this to change the title for the favorites view.
customFavorites: # Read more in 'Custom Favorites' section below
media_player.tv: # set this to 'all' to show the custom favorite for all players
- title: TV # Must match the name of the source (unless you specify media_content_id/type as shown below)
thumbnail: https://cdn-icons-png.flaticon.com/512/716/716429.png
all:
- title: BBC
media_content_id: media-source://radio_browser/98adecf7-2683-4408-9be7-02d3f9098eb8
media_content_type: music
thumbnail: http://cdn-profiles.tunein.com/s24948/images/logoq.jpg?t=1
customThumbnails:
Voyage: https://i.scdn.co/image/ab67706f000000027b2e7ee752dc222ff2fd466f
customThumbnailsIfMissing:
Ed Sheeran Radio: https://i.scdn.co/image/ab6761610000e5eb4d2f80ceffc6c70a432ccd7c
Legendary: https://i.scdn.co/image/ab67706f000000027b2e7ee752dc222ff2fd466f
fallback: https://cdn-icons-png.flaticon.com/512/651/651717.png # will use this if thumbnail is missing and none of the above matches. Defaults to image of music notes.
exclude: # will compare both against title and media_content_id
- My Favorite Album # Hide specific title
- Christmas # Hide any titles matching 'Christmas'
- radio_browser # Hide any radio stations from radio_browser (since their media_content_id contains this string)
hideTitleForThumbnailIcons: true # default is false. Only makes a difference if itemsPerRow > 1. Will hide title for thumbnail artworks.
iconBorder: 1px solid white # default is none. Use this to add a border to favorites icons.
iconPadding: 0.25 # default is 0.75. Unit is 'rem'. Use this to change the padding around favorites icon artwork.
iconTitleBackgroundColor: blue # default is card background with opacity. Use this to change the background color of favorites icon titles.
iconTitleColor: red # default is theme text color. Use this to change the color of favorites icon titles.
numberToShow: 10 # Use this to limit the amount of favorites to show.
sortByType: true # default is false. Will group favorites by type (e.g. radio, playlist, album).
typeColor: blue # default is theme text color. Color for type headers when sortByType is enabled.
typeFontSize: 18px # default is inherited. Font size for type headers.
typeFontWeight: normal # default is bold. Font weight for type headers.
typeMarginBottom: 6px # default is none. Bottom margin for type headers.
topItems: # Show these favorites at the top of the list
- Legendary
- Country Rocks
- Kacey Musgraves Radio
groups:
title: ''
backgroundColor: '#2a2a2a' # Use this to change the background color of group buttons.
buttonWidth: 10 # default is full width. Unit is 'rem'. Use this to change the width of the groups list.
compact: true # default is false. Makes the groups section more compact.
hideCurrentTrack: true # default is false, which means song/track info for groups will be shown
itemMargin: '5px' # default is '1rem'. Use this to change the margin around groups list items.
speakersFontSize: 1.2 # default is 1.1. Unit is 'em'. Use this to change the font size of the speakers name.
titleFontSize: 1 # default is 0.9. Unit is 'em'. Use this to change the font size of the track title.
grouping:
title: ''
compact: true # default is false. Makes the grouping section more compact.
dontSwitchPlayer: true # default is false. Will not switch to another player if main player is ungrouped.
buttonColor: black # default is theme accent color. Use this to change the background/accent color of grouping buttons.
buttonFontSize: 1.2 # default is 1. Unit is 'em'. Use this to change the font size of grouping buttons.
buttonIcons: # Use this to set custom icons for the grouping buttons.
predefinedGroup: mdi:account-group # default is mdi:speaker-multiple
joinAll: mdi:account-multiple # default is mdi:checkbox-multiple-marked-outline
unJoinAll: mdi:account-remove # default is mdi:minus-box-multiple-outline
disableMainSpeakers: true # default is false. Disables (greys out) any speaker that is currently the main speaker of a multi-speaker group.
dontSortMembersOnTop: true # default is false. Will not sort members of the selected player on top of the list in the grouping section.
hideUngroupAllButtons: true # default is false. Hides the join all/unjoin all buttons in the grouping section.
hideVolumes: true # default is false. Hides the volume sliders in the grouping section.
skipApplyButton: true # default is false. Will skip the apply button when grouping.
volumes:
title: '' # default is empty. Use this to change the title for the volumes section.
additionalControlsFontSize: 0.9 # default is 0.75. Unit is 'em'. Font size for additional controls (e.g., Bass, Treble, Audio delay).
hideCogwheel: true # default is false. Will hide the cogwheel for the volumes section.
labelForAllSlider: 'All volumes' # default is 'All'. Use this to change the label for the all volumes slider.
adjustVolumeRelativeToMainPlayer: true # default is false, which means all players will be set to the same volume as the main player. If set to true, volume will be adjusted relative to the main player in the group.
changeVolumeOnSlide: true # default is false. If set to true, volume will be changed while sliding the volume slider. If false, volume will only be changed when releasing the slider.
inverseGroupMuteState: true # default is false, which means that only if all players are muted, mute icon shows as 'muted'. If set to true, mute icon will show as 'muted' if any player is muted.
volumeStepSize: 1 # Use this to change the step size when using volume up/down. Default is to use the step size of Home Assistant's media player integration.
queue:
title: Songs # default is 'Play Queue'. Use this to change the title for the queue section.
itemBackgroundColor: '#ff0000' # Use this to set a custom background color for queue items.
itemTextColor: '#ffffff' # Use this to set a custom text color for queue items.
selectedItemBackgroundColor: '#00ff00' # Use this to set a custom background color for the currently playing queue item.
selectedItemTextColor: '#000000' # Use this to set a custom text color for the currently playing queue item.
The Search section allows you to search for music using the Music Assistant integration. You must have Music Assistant installed and configured in Home Assistant to use this feature.
search:
title: Search # default is 'Search'. Use this to change the title for the search section.
massConfigEntryId: '' # Leave empty to auto-discover Music Assistant. Only needed if you have multiple Music Assistant instances.
defaultMediaType: track # default is none. Pre-select a media type (track, artist, album, playlist).
searchLimit: 50 # default is 50. Maximum number of results to show per search.
autoSearchMinChars: 3 # default is 3. Minimum characters before auto-search triggers.
Queue supports:
entityPlatform: music_assistant)If you use Music Assistant queue, install mass_queue from HACS.
Search Features:
As mentioned earlier, use the individual sections for more layout flexibility.
Here is an example:
type: horizontal-stack
cards:
- type: custom:sonos-card
sections:
- groups
- volumes
- type: custom:sonos-card
sections:
- player
- type: custom:sonos-card
sections:
- grouping
- media browser
The following variables are being used and can be set in your theme to change the appearance of the card:
--accent-color
--primary-color
--secondary-text-color
--secondary-background-color
--disabled-text-color
Read more about using theme variables here: Home Assistant frontend - Home Assistant
Create a modern look by using a blurred version of the album artwork as background. The normal artwork is displayed on top, and the header/controls have a semi-transparent background.
type: custom:sonos-card
player:
artworkAsBackgroundBlur: 10
controlsAndHeaderBackgroundOpacity: 0.7
This example will give a slimmer version of the card.
type: custom:sonos-card
heightPercentage: 60
player:
showVolumeUpAndDownButtons: true
hideArtwork: true
controlsLargeIcons: true
mediaBrowser:
itemsPerRow: 6
hideHeader: true
groups:
compact: true
grouping:
compact: true
footerHeight: 3.5
You can add your own buttons to the Favorites section. This can be useful if you want to quickly start a specific radio station or playlist.
To determine what to configure for a button do the following:
media_content_id and media_content_type attributes.Example:
type: custom:sonos-card
mediaBrowser:
favorites:
customFavorites:
all: # 'all' means it will show for all players, otherwise specify the entity_id of the player.
- title: BBC
media_content_id: x-rincon-mp3radio://http://stream.live.vc.bbcmedia.co.uk/bbc_world_service
media_content_type: music
thumbnail: http://cdn-profiles.tunein.com/s24948/images/logoq.jpg?t=1
If you want to find the media_content_id for a specific radio station, playlist, or media browser folder, sometimes the above method is not enough. If so, you can use the following method to find it:
websocket connection that appearsplay_media - for finding content to play (custom favorites)browse_media - for finding folder paths (media browser shortcuts)media_content_id and media_content_type in the dataExample for a playable item (custom favorite):
{
"service_data": {
"entity_id": "media_player.living_room",
"media_content_id": "spotify://playlist:1Oz4xMzRKtRiEs51243ZknqGJm",
"media_content_type": "spotify://playlist"
}
}
Example for a folder (media browser shortcut):
{
"type": "media_player/browse_media",
"entity_id": "media_player.living_room",
"media_content_id": "spotify://8fb1de564ba7e4c8c4561860574c83b9",
"media_content_type": "spotify://library"
}
You can configure a shortcut button in the media browser header that takes you directly to a specific folder. This is especially useful for wall-mounted touch displays where you want quick access to frequently used folders like Spotify playlists.
type: custom:sonos-card
mediaBrowser:
shortcut:
media_content_id: 'spotify://8fb1de564ba7e4c8c4561860574c83b9'
media_content_type: 'spotify://library'
icon: 'mdi:spotify'
name: 'My Spotify'
The shortcut button will appear in the media browser header (both in Favorites and Browse Media views), to the left of the other navigation icons. Clicking it will navigate directly to the specified folder, reducing multiple taps to just one.
The volume level slider is dynamically adjusting its scale. If volume is below 20% it will show a scale up to 30%. Above
20% it will show a scale up to 100%. The color will also change from green to red clearly indicating which scale is
being used.
Enable it in config with dynamicVolumeSlider: true
By default, you can append a player in URL hash (e.g. #media_player.my_sonos_player) to have that player selected.
You can change this behavior to use the browser’s session storage by setting storePlayerInSessionStorage: true. This prevents the URL from changing when you select a player.
If entityId is configured for the card, both the URL hash and session storage will be ignored on initial load. See more in the Usage section above.
If you never want to remember the selected player, you can set doNotRememberSelectedPlayer: true to an empty string.