Maxi Media Player

Maxi Media Player

Media card for Home Assistant UI with a focus on managing multiple media players!

(If this looks familiar to you, it’s probably because it’s almost identical to my Sonos Card, except this one is focused on supporting all players, not just Sonos.)


  • Group/Ungroup speakers
    • If the individual speakers support it
  • Control multiple speakers
  • Play favorites from list
  • Media browser button
  • Control individual volumes in a group
  • Artwork background
  • Possibility to override artwork
  • Shuffle and repeat mode
  • Theming
  • Configurable styling
  • Dynamic volume level slider
  • Track progress bar

and more!

Support the project

Do you like the Maxi Media Player? Support the project with a coffee :coffee:



With HACS (recommended)

  1. Download HACS following the instructions on Download | HACS
  2. Proceed to the initial configuration following the instructions on Initial Configuration | HACS
  3. On your sidebar go to HACS > Frontend
  4. click on the icon at the right top corner then on Custom repositories
  5. For the repository add this: GitHub - punxaphil/maxi-media-player: Media card for Home Assistant UI with a focus on managing multiple media players, but not excluding single player setups.
  6. For the category select Lovelace then click Add
  7. Now click on Maxi Media Player then on the Dowload button
  8. Go back on your dashboard and click on the icon at the right top corner then on Edit dashboard
  9. You can now click on Add card in the bottom right corner and search for Maxi Media Player

Coming soon in the HACS default repo (still waiting for validation).

Without HACS

  1. Download this file: maxi-media-player.js
  2. Add this file into your /www folder
  3. On your dashboard click on the icon at the right top corner then on Edit dashboard
  4. Click again on that icon and then on Manage resources
  5. Click on Add resource
  6. Copy and paste this: /local/maxi-media-player.js?v=1
  7. Click on JavaScript Module then Create
  8. Go back and refresh your page
  9. You can now click on Add card in the bottom right corner and search for Maxi Media Player
  10. After any update of the file you will have to edit /local/maxi-media-player.js?v=1 and change the version to any higher number


Individual sections

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.


Use the Visual Editor in Home Assistant to configure the card. Most options are available there.

Configuration in YAML

type: custom:maxi-media-player
entities: # Required unless you specify entityPlatform
  - media_player.kitchen_player
  - media_player.hallway_player
  - media_player.bedroom_player
  - media_player.livingroom_player
excludeItemsInEntitiesList: true # Will invert the selection in the `entities` list, so that all players that are not in the list will be used.
entityPlatform: sonos # will select all entities for this platform. Will override the `entities` list if set.

# All settings below are optional

# common for all sections
title: ''
sections: # see explanation further up
  - volumes
  - groups
  - grouping
  - media browser
  - player
widthPercentage: 75 # default is 100. Use this to change the width of the card.
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.
selectedEntityId: 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: ''
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. 
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.

# groups specific
groupsTitle: ''
hideGroupCurrentTrack: true # default is false, which means song/track info for groups will be shown

# grouping specific
groupingTitle: ''
predefinedGroups: # defaults to empty
  - 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
      - 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:
        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
skipApplyButtonWhenGrouping: true # default is false. Will skip the apply button when grouping.

# player specific
showVolumeUpAndDownButtons: true # default is false, shows buttons for increasing and decreasing volume
labelWhenNoMediaIsSelected: 'No media selected'
labelForTheAllVolumesSlider: 'All volumes'
mediaArtworkOverrides: # Show your own selected artwork if certain rules match
  - mediaTitleEquals: TV
    sizePercentage: 40
  - mediaContentIdEquals: "x-htastream:RINCON_949F3EC2E15B01400:spdif"
  - mediaTitleEquals: p4malmo-aac-192
    imageUrl: >-
  - ifMissing: true # ifMissing will only be used if none of the "Equals" overrides above resulted in a match 
customSources: # Main use case is probably to set tv media player to play TV sound # set this to 'all' to show the custom source for all players
    - title: TV
dynamicVolumeSlider: true # default is false. See more in section further down.
dynamicVolumeSliderThreshold: 30 # default is 20. Use this to change the threshold for the dynamic volume slider.
dynamicVolumeSliderMax: 40 # default is 30. Use this to change the max value for the dynamic volume slider.
artworkHostname: #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.
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.
fallbackArtwork: # Override default fallback artwork image if artwork is missing for the currently selected media.
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
artworkMinHeight: 10 # default is 5. Use this to change the minimum height of the artwork in the player section. Unit is in rem.

# media browser specific
mediaBrowserItemsPerRow: 1 # default is 4. Use this to show items as list.
mediaBrowserHideTitleForThumbnailIcons: true # default is false. Only makes a difference if mediaBrowserItemsPerRow > 1. Will hide title for thumbnail artworks.
  Ed Sheeran Radio:
  fallback: # will use this if thumbnail is missing and none of the above matches. Defaults to black music notes with white background.  
  - My Favorite Album
  - My Bad Playlist
topFavorites: # Show these favorites at the top of the list
  - Legendary
  - Country Rocks
  - Kacey Musgraves Radio
numberOfFavoritesToShow: 10 # Use this to limit the amount of favorites to show
hideBrowseMediaButton: true # default is false. Hides the button to open the media browser.
replaceHttpWithHttpsForThumbnails: true # default is false. Use this if you  want to replace http with https for thumbnails. 
mediaBrowserTitle: My favorites # default is 'All favorites'. Use this to change the title for the media browser/favorites section.

# volumes specific
hideVolumeCogwheel: true # default is false. Will hide the cogwheel for the volumes section.

Using individual section cards

As mentioned earlier, use the individual sections for more layout flexibility.

Here is an example:

type: horizontal-stack
  - type: custom:maxi-media-player
      - groups
      - volumes
  - type: custom:maxi-media-player
      - player
  - type: custom:maxi-media-player
      - grouping
      - media browser

Theme variables

The following variables are being used and can be set in your theme to change the appearance of the card:


Read more about using theme variables here: Home Assistant frontend - Home Assistant

CSS Styling

The recommend way to change look and feel is to use the built-in theming capabilities in Home Assistant. If that is not enough this card supports being styled with card_mod.


type: custom:maxi-media-player
  style: |
    ha-card {
      color: white !important;
      background: gray;
      --accent-color: pink;
      --primary-color: white;
      --secondary-text-color: white;
      --secondary-background-color: pink;

The above YAML renders the following:

Dynamic volume level slider

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

Linking to specific player

Append #media_player.my_player to page URL to have that player selected.

If entityId is configured for the card, the url param will be ignored. See more in the Usage section above.


Very cool card, thanks for this. I’m using the linkplay platform for multiroom audio which has its own service for grouping speakers. Is it maybe possible to change which service is used for joining speakers?

If the Home Assistant integration for your speakers support grouping it should work. Otherwise I’m afraid not.

Good morning, please help to understand how to use this card with the yTube Music Player integration


This card only supports media_player entities.

1 Like

Love this card! Thanks for sharing!
Looks like this doesn’t support homepod mini through Apple TV integration, despite it has media_player entity. Any idea how to get it to work?

I don’t have any homepods, so hard for me to test.
What does it look like when you try to add it?
Please share screenshots and errors from web console (if there are any).
Also how it looks here: http://homeassistant.local/developer-tools/state

Can you try this new release?


:bug: Fixes

It already shows the homepod mini too. Thanks!
However, the grouping does not work with it. The device itself does not support this service. Now, I’m trying to integrate through Music Assistant add-on.

However, the grouping does not work with it. The device itself does not support this service.

Yes, as expected. Only devices that actually support grouping will be groupable. I can think of a way to show it more clearly in the card though.

Nice card! Just installed it but wondering where the ‘Favorites’ coming from? Can one adjust them manually?

can this work with plexamp on my phone?

I’m also wondering the same, did you find the solution already?

If it shows in the built in media player, it should work

Hi, it’s possible that the player switch to the currently playing media player automatically?. I mean, if I activate my home pod asking to Siri and starts playing is posible that the player show the HomePod media player without the need of interact with the player manually?

I tried with auto entities that works well with mini media player but I not able to make it work with maxi media player.

And a second question, it’s is possible to set the default image url with the content of a sensor? I have a sensor with the current playing Xbox game and I would like to show the actual cover of the game that I have stored in a sensor

Any help will be appreciated

fellow is trying to get this card into auto-entities, but were having a hard time populating the entities map

    - type: custom:auto-entities
        type: custom:maxi-media-player
          - domain: media_player
      card_param: entities

would be the minimal config for that, but we still see:

please have a look what this error means, and if we should try something else to auto-populate?

given the card_param: entities is default for auto-entities (just like when populating a core entities card) I shouldn’t have entered it here, but it makes no diffrence taking it out, so I gather it is indeed default, but not working with this particular card

Ive been chatting with the auto-entities author and that card generates a list like

  - entity: media_player.x
  - entity: media_player.y
  - ...etc...

however, when we do

    - type: custom:maxi-media-player
        - entity: media_player.googlehome_library
        - entity: media_player.googlehome_hal

the maxi-media-player card shows the same error, of not finding entities.

hope this can be fixed, FR FR add option to list entity: · Issue #52 · punxaphil/maxi-media-player · GitHub

1 Like