Music Assistant Player Card

A Home Assistant media player card built for Music Assistant players.

Important: This card requires the custom integration Music Assistant Queue Actions to function. This integration must be installed before continuing!

Install with HACS:

Table of Contents

• Features
• Installation
  • Prequisites
  • HACS Installation
  • Manual Installation
• Configuration
  • Example Configs
    • Minimal Config
    • Default Configuration
    • Full Example Configuration
  • Base Config
    • Expressive Scheme
    • Default Section
    • Entity Config
    • Music Player Config
    • Queue Config
    • Media Browser Config
    • Players Config
• FAQs
  • The card won't display at all or won't display properly!
  • The media browser won't display any items for:
  • Why is the card completely blank?
  • Why is my player queue empty even though it was just playing something?
  • Can this card support individual users?
  • I'm not seeing any artwork in the queue or media browser!
  • How do I theme the card?
  • Can I group players X and Y?
  • Can this card work in my local language?
  • I am having issues with this card on my iOS/OSX device but it works fine elsewhere.
  • I would like to sponsor you/the card and/or pay to add a new feature!
  • I have other questions or issues not addressed
• Contributing
• Developing

Features

• Responsive Material Expressive UI!
  • Set styles via HA theme variables - see below
  • Set custom Expressive scheme in your config
• Hide elements you don't want, even at the player level or for an entire tab
• Use a different media_player to control the volume of an entity
• Even artwork for local media will show!
• Music Player Tab
  • Swipe to change tracks
  • Hold ❤️ to Add to Playlist
  • Customizable layout
  • Adjust volume for current or any grouped players
  • Switch between any configured player
• Player Queue Tab
  • Select track to play it now
  • Move up, next, down, or remove items
  • Clear entire playlist
  • Configure the number of queue items to display
• Media Browser Tab
  • All media types - Albums, artists, audiobooks, playlists, podcasts, radios, and tracks
  • View your Favorites, Recents, or Provider Recommendations
  • Search your providers for any media type - both local and non-local media
  • Add your own custom media or scripts
  • Subviews to display the details and tracks/episodes for albums, artists, playlists, and podcasts
    • Select which track you want to start on!
    • Remove tracks from a playlist - See below for important notes!
  • Enqueue items to play now/next, clear queue and play now/next, or start radio
• Players Tab
  • Switch to any configured player
  • Join or transfer your active queues

Installation

Prequisites

In addition to the Music Assistant integration, this card depends on the custom integration mass_queue for all the actions. Follow all instructions in the repository to install first.

HACS Installation

1. Use button above to add to your Home Assistant instance.

Manual Installation

1. Download the card.
   • Navigate to the Releases and locate the latest release.
   • Download mass-card.js
   • Save mass-card.js to your Home Assistant <config>/www directory
2. Add card to your HA resources
   • Go to your Home Assistant Settings.
   • Select "Dashboards"
   • In the top left, select the three-dot overflow menu and click "Resources"
   • Press "Add Resource". For the URL, type in "/local/mass-card.js". Select "JavaScript module" and click "Create".

Configuration

This card comes with a visual editor. However, not every option can be set with it (eg, player name and volume player, custom items, etc). Use the below documentation to help.

Example Configs

Minimal Config

This is the minimal config you need for the card to work.

type: custom:mass-player-card
entities:
  - media_player.music_assistant_player

Default Configuration

type: custom:mass-player-card
expressive: true
expressive_theme: expressive
panel: false
default_section: music_player
sync_player_across_dashboard: false
download_local: false
entities:
  - entity_id: <MEDIA_PLAYER_ENTITY>
    volume_entity_id: <MEDIA_PLAYER_ENTITY>
    max_volume: 100
    name: <MEDIA_PLAYER_ENTITY_NAME>
    inactive_when_idle: false
    inactive_when_not_updated: true
queue:
  enabled: true
  hide:
    header: false
    header_title: false
    clear_queue_button: false
    artist_names: false
    album_covers: false
    action_buttons: false
    move_down_button: false
    move_next_button: false
    move_up_button: false
    remove_button: false
  show_album_covers: true
  show_artist_names: true
player:
  enabled: true
  hide:
    header: false
    header_title: false
    player_selector: false
    group_selector: false
    player_name: false
    track_title: false
    track_artist: false
    track_progress_time: false
    track_progress_bar: false
    power_button: false
    repeat_button: false
    shuffle_button: false
    favorite_button: false
    volume: false
    mute_button: false
  layout:
    controls_layout: compact
    hide_labels: false
    artwork_size: large
    icons:
      shuffle:
        size: small
        box_shadow: false
        label: true
      previous:
        size: small
        box_shadow: false
        label: true
      play_pause:
        size: large
        box_shadow: true
        label: true
      next:
        size: small
        box_shadow: false
        label: true
      repeat:
        size: small
        box_shadow: false
        label: true
      power:
        size: small
        box_shadow: false
        label: true
      favorite:
        size: small
        box_shadow: false
        label: true
players:
  enabled: true
  hide:
    header: false
    header_title: false
    action_buttons: false
    join_button: false
    transfer_button: false
media_browser:
  enabled: true
  playlists_allow_removing_tracks: false
  hide:
    header: false
    header_title: false
    back_button: false
    filter_button: false
    search_button: false
    titles: false
    enqueue_menu: false
    add_to_queue_button: false
    play_next_button: false
    play_next_clear_queue_button: false
    play_now_button: false
    play_now_clear_queue_button: false
  recents:
    enabled: true
    show_collection_view: true
    albums:
      enabled: true
      limit: 25
      favorites_only: true
    artists:
      enabled: true
      limit: 25
      favorites_only: true
    audiobooks:
      enabled: true
      limit: 25
      favorites_only: true
    playlists:
      enabled: true
      limit: 25
      favorites_only: true
    podcasts:
      enabled: true
      limit: 25
      favorites_only: true
    radios:
      enabled: true
      limit: 25
      favorites_only: true
    tracks:
      enabled: true
      limit: 25
      favorites_only: true
  recommendations:
    enabled: true
    show_collection_view: true
  favorites:
    enabled: true
    show_collection_view: true
    albums:
      enabled: true
      limit: 25
      favorites_only: true
    artists:
      enabled: true
      limit: 25
      favorites_only: true
    audiobooks:
      enabled: true
      limit: 25
      favorites_only: true
    playlists:
      enabled: true
      limit: 25
      favorites_only: true
    podcasts:
      enabled: true
      limit: 25
      favorites_only: true
    radios:
      enabled: true
      limit: 25
      favorites_only: true
    tracks:
      enabled: true
      limit: 25
      favorites_only: true

Full Example Configuration

type: custom:mass-player-card
expressive: true
expressive: true
expressive_theme: fruit_salad
download_local: false
panel: false
default_section: media_browser
entities:
  - media_player.kitchen_player_music_assistant
  - entity_id: media_player.bedroom_player_music_assistant
    inactive_when_idle: true
    hide:
      player:
        favorite_button: true
        mute_button: true
        player_selector: true
        power_button: true
        repeat_button: true
        shuffle_button: true
        volume: true
  - entity_id: media_player.living_room_player_music_assistant
    volume_entity_id: media_player.living_room_tv
  - entity_id: media_player.bathoom_music_assistant
    name: Bathroom Speaker
    max_volume: 50
    inactive_when_not_updated: true
    hide:
      player:
        mute_button: true
        power_button: true
        volume: true
      queue:
        move_up_button: true
  - entity_id: media_player.loft_music_assistant
    volume_entity_id: media_player.loft_tv
    max_volume: 40
    name: Loft TV
  - entity_id: media_player.basement_music_assistant
    name: Basement
    hide:
      player:
        mute_button: true
        power_button: true
queue:
  enabled: true
  show_album_covers: true
  show_artist_names: true
player:
  enabled: true
  layout:
    controls_layout: spaced
    icons:
      play_pause:
        size: small
        box_shadow: true
players:
  enabled: true
media_browser:
  enabled: true
  columns: 2
  favorites:
    albums:
      enabled: true
      limit: 25
      favorites_only: true
    artists:
      enabled: true
      limit: 10
      favorites_only: true
    audiobooks:
      enabled: true
      limit: 5
      favorites_only: false
    playlists:
      enabled: true
      limit: 5
      favorites_only: false
    podcasts:
      enabled: true
      limit: 15
      favorites_only: false
    radios:
      enabled: true
      limit: 4
      favorites_only: false
    tracks:
      enabled: true
      limit: 100
      favorites_only: true
      items:
        - name: My Playlist
          image: https://resources.tidal.com/images/10c59b67/bb86/4960/8071/a23a03b8cbdd/750x750.jpg
          service: script.play_example_playlist
  sections:
    - name: My Tracks
      image: https://resources.tidal.com/images/0b5ff69d/b031/4445/a804/01b18b5a525f/750x750.jpg
      items:
        - name: The Show Goes On
          image: https://resources.tidal.com/images/9a18c67f/1062/4068/986b/45654fade74a/750x750.jpg
          media_content_id: tidal://track/241647167
          media_content_type: track
        - name: TRUSTFALL (Album)
          image: https://i.scdn.co/image/ab67616d0000b2735b8cf73dd4eebd286d9a2c78
          media_content_id: library://artist/40
          media_content_type: track
        - name: Where Is The Love?
          image: https://resources.tidal.com/images/b15ef956/5eed/43ba/9bba/d1ea1c3e48a4/750x750.jpg
          media_content_id: tidal://track/222419939
          media_content_type: track
  recents:
    enabled: true
  recommendations:
    enabled: true
    providers:
      - plex
      - tidal
  playlists_allow_removing_tracks: false

Base Config

Expressive Scheme

This defines the expressive scheme which will be used for color generation. @Nerwyn has a great description in the readme for his Material You Utilities which may be useful.

There are a handful of different options for the scheme:

• content
• expressive
• fidelity
• fruit_salad
• monochrome
• neutral
• rainbow
• tonal_spot
• vibrant

Default Section

You can choose which section to start on by default. By default, the first enabled section listed below will be chosen. Any of these options are valid for the default section:

• music_player
• queue
• media_browser
• players

Entity Config

For each entity, you can either provide the Entity ID by itself or you can provide the Music Assistant media player Entity ID, the media player Entity ID for volume control, and/or the name of the player. Below is the config if you would like to provide the additional details.

Entity Hidden Elements Config

Certain elements across the different sections can be hidden or displayed depending on your configuration. By default, every item will be displayed.

Music Player Config

📷 Media Player Example

Music Player Hidden Elements Config

Multiple elements on the Music Player tab can be hidden. By default, all elements are visible

Music Player Layout Config

The layout of the control buttons can be adjusted to your liking. Use the full default configuration below as an example.

type: custom:mass-player-card
player:
  layout:
    controls_layout: compact          # Options: compact or spaced (default: compact)
    artwork_size: large               # Options: small, medium, large (default: large)
    hide_labels: false                # Options: True/False (default: false)
                                      # Note: Medium/Large will display in the background behind the header and player controls. Small will display on its own.
    icons:
      shuffle:
        size: small                   # Options: small or large (default: small)
        box_shadow: false             # Options: True/False (default: false)
        label: true                   # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      previous:
        size: small                   # Options: small or large (default: small)
        box_shadow: false             # Options: True/False (default: false)
        label: false                  # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      next:
        size: small                   # Options: small or large (default: small)
        box_shadow: false             # Options: True/False (default: false)
        label: false                  # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      repeat:
        size: small                   # Options: small or large (default: small)
        box_shadow: false             # Options: True/False (default: false)
        label: true                   # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      play_pause:
        size: large                   # Options: small or large (default: small)
        box_shadow: true              # Options: True/False (default: false)
        label: false                  # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      power:
        size: large                   # Options: small or large (default: small)
        box_shadow: true              # Options: True/False (default: false)
        label: false                  # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      favorite:
        size: large                   # Options: small or large (default: small)
        box_shadow: true              # Options: True/False (default: false)
        label: false                  # Options: True/False (default: false)
                                      # Note: Label will never show if size is large
      

Queue Config

Display and interact with the player's queue.

📷 Queue Example

Queue Hidden Elements Config

Multiple elements on the queue tab can be hidden. By default, all elements are visible

Media Browser Config

📷 Media Browser Example

WARNING:

playlists_allow_removing_tracks is experimental and VERY risky. Music Assistant uses the position in a playlist to determine which tracks to remove. However, it does not provide an updated playlist when tracks are removed, instead waiting for its next refresh.

To work around this, the card will automatically update the playlists when items are removed. HOWEVER, this will only work until you leave the playlist view.

default_enqueue_option

The default enqueue mode can be adjusted in your configuration. If not set, any media will play next when they are selected.

The valid options are:

• play_now
• play_now_clear_queue
• play_next
• play_next_clear_queue
• add_to_queue
• radio

Favorites Config

Favorite Items

You can select which favorite items you'd like to display in the media browser. Use the example below to help set it up. By default, all favorites are enabled. If no favorites exist for a category, the section will not be displayed. You can also add your own custom items to the favorite section by specifying it under items.

type: custom:mass-player-card
entities:
  - media_player.my_player
media_browser:
  favorites:
    albums:
      enabled: false
    playlists:
      enabled: true
    ...

Recommendations Config

Recommendations can be enabled/disabled. You can also choose which providers can supply recommendations.

show_collection_view

When show_collection_view is enabled, clicking on an album, artist, playlist, or podcast will open up a collection view displaying information on the collection, enqueue options, and individual tracks/episodes. When disabled, clicking on the items will instead enqueue the item. By default, this is enabled.

Sections Config

Sections lets you add your own sections to the browser with your own items. These can either be media items (by providing media_content_id and media_content_type) or they can be a script (by providing service). If the item is a script, the current media player will be passed to it with the entity_id parameter.

Section Item Config

These will be for each item inside of that section. Either service must be provided or media_content_id and media_content_type.

Media Browser Hidden Elements Config

Multiple elements on the media browser tab can be hidden. By default, all elements are visible

WARNING:

Unless you have a small library, favorites_only will likely not work as you expect:

• Music Assistant will always return items in alphabetical order.
• It will limit the returned items to 500. This may not cover all your items. Simultaneously, this many items may also cause performance issues.

It is recommended that you add custom items instead.

Players Config

📷 Media Player Example

Players Hidden Elements Config

Multiple elements on the players tab can be hidden. By default, all elements are visible

FAQs

The card won't display at all or won't display properly!

1. Check to ensure you have Music Assistant Queue Actions fully installed - including setting up the integration and creating config entries for your MA instances.
2. Check the other FAQs and repository issues to see if they answer your issue.
3. If you still can't figure it out, submit a new issue.

The media browser won't display any items for:

Favorites

Usually, this issue is because you are looking at the Favorites section but don't have any favorites added in Music Assistant or your providers. If you don't want to favorite anything, consider adding your own items instead.

Recommendations

Ensure your music provider actually provides recommendations.

Recents

Have you tried listening to music?

Why is the card completely blank?

Please ensure you have installed and configured the Music Assistant Queue Actions integration. If you are still having issues, ensure that you are using only Music Assistant players.

Why is my player queue empty even though it was just playing something?

For some players and providers, Music Assistant can consider a player inactive rather quickly after pausing. While not every instance can be handled, you usually can correct for this in most instances. In your card configuration, add the following config for each entity:

- entity_id: ...
  inactive_when_idle: false
  inactive_when_not_updated: false

If you are still experiencing issues, please run the action mass_queue.get_queue_items for your player. If it returns your queue, please file an issue report and include your Home Assistant logs and browser logs. The browser logs can usually be found by opening up your browser's Developer Tools and navigating to a section labeled "Console".

Can this card support individual users?

Currently, no. However, this is something we are trying to work towards.

I'm not seeing any artwork in the queue or media browser!

If you are using a local provider, Music Assistant sends back a path which usually can't be accessed. Fortunately, this is something that we can easily work around. Music Assistant Queue Actions has the ability to download images for local providers and send them back to the card. This can cause a slowdown as downloading and encoding each image may take some time. Some of this is avoided - for example, images for queue items are usually only downloaded when HA first starts up, the integration is reloaded, or when the queue changes.

To enable this feature:

1. Navigate to the Devices & Servies section in Home Assistant settings.
2. Locate and select the Music Assistant Queue Actions integration.
3. Click on the cog next to the config entry.
4. Check the box titled either "download_local" or "Attempt fallback support for local media images" and click "Submit".

If you are using a non-local provider, submit a new issue.

How do I theme the card?

This card has initial support for custom themes. All tokens are listed in src/styles/main.ts and are prefixed with mass-player-card.

For example, the border radius for the sections and cards are set in the file as:

--default-border-radius: var(--mass-player-card-default-border-radius, 28px);

If you would like to set the border radius to 12px instead, you would add this line to your theme:

mass-player-card-default-border-radius: 12px;

If there are portions of the card which you would like to theme but don't have any support yet, please submit an issue. I will be able to add support in most cases.

Can I group players X and Y?

Yes... Most likely... Usually... Maybe... Ehhh...

It depends. If they are the same provider, you almost always can. Some players can also be grouped across different providers. This really comes down to their support in Music Assistant itself.

For players which don't have any support, you can usually use the universal or sync groups within Music Assistant. However, this card does not support setting up these types of groups. You will need to create them yourself.

Can this card work in my local language?

Current Language Support

If you would like to add new translations for other languages:

1. Fork this repository and clone it locally.
2. Navigate to src/translations. Make a copy of en.ts and save it with the name of your language code.
3. Set the strings for each key so they are correct for your language. The player.messages.inactive and player.title.inactive items do not need to match the English translation if they don't make sense or other strings make more sense for your language.
4. Make the following edits to src/utils/translations.ts. Use the existing translations as reference.

• At the top, import your translations file - eg import en from '../translations/en
• Under const TRANSLATIONS, add an entry for your translations.

5. Commit and push the changes to your forked copy of this repo.
6. Submit a pull request to this repository. The target branch should be dev.

The instructions are rather similar for improving existing language support. However, you do not need to make a clone of en.ts (instead, use the existing translation file) and you do not need to follow Step #4.

If you want to add new translations but don't want to work with the code and/or Git, you can instead contribute by submitting them to us:

1. Navigate to this repository in Github.
2. Download the en.ts file at src/translations.
3. Edit each translation to match with your language. (see step #3 above).
4. Open a new issue in this repository and attach a copy of the translation file and the name of the language you have added support for.

I am having issues with this card on my iOS/OSX device but it works fine elsewhere.

Apple's Webkit engine has some peculiarities that aren't present in other browsers. Unfortunately, I don't own the required equipment (an iOS device and a Mac) in order to properly debug this issue.

If you have the abilities and the equipment to do so, I am happy to accept any contributions to help fix this issue!

I would like to sponsor you/the card and/or pay to add a new feature!

While I appreciate it, I am not going to accept any funding.

When someone funds development, there's often an implied belief that the card will keep being developed or the maintainer will provide new projects. I want to be able to drop development on this card when I feel that it is complete. I do not want people to feel misled, cheated, or that I should prioritize their wants over anything else. This card is something I created for myself

I have other questions or issues not addressed

Check the repository issues to see if your question has already been asked. If not, feel free to submit a new issue.

Contributing

I am happy to accept any new contributions to this repository. Feel free to fork and submit pull requests.

Developing

This card uses corepack for development and relies on Node 22.

Clone the repository:

git clone https://github.com/droans/mass-player-card

Set up the environment

Switch to Node 22:

nvm use 22

Install corepack:

npm install corepack

Install dependencies:

yarn install

Build:

yarn rollup

The output file will be located at ./dist/mass-player-card.js