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

• Installation
• Configuration
  • Base Config
  • Entity Config
  • Entity Hidden Elements Config
  • Music Player Config
  • Music Player Hidden Elements Config
  • Music Player Layout Config
  • Queue Config
  • Queue Hidden Elements Config
  • Media Browser Config
  • Media Browser Hidden Elements Config
  • Favorites Config
  • Sections Config
  • Section Item Config
  • Players Config
  • Players Hidden Elements Config
• FAQs
  • The card won't display at all or won't display properly!
  • The media browser won't display any items for:
  • I'm not seeing any artwork in the queue or media browser!
  • How do I theme the card?
  • Can this card work in my local language?
  • I have other questions or issues not addressed

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.

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

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

The card does not have a visual editor. Use this configuration to create your card:

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

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

type: custom:mass-player-card
entities:
  - entity_id: <MEDIA_PLAYER_ENTITY>
    volume_entity_id: <MEDIA_PLAYER_ENTITY>
    max_volume: 100
    name: <MEDIA_PLAYER_ENTITY_NAME>
    inactive_when_idle: true
    hide:
      player:
        favorite: false
        mute: false
        player_selector: false
        power: false
        repeat: false
        shuffle: false
        volume: false
queue:
  enabled: true
  hide:
    action_buttons: false
    move_down_button: false
    move_next_button: false
    move_up_button: false
    remove_button: false
    album_covers: false
    artist_names: false
  limit_before: 5
  limit_after: 100
  show_album_covers: true
  show_artist_names: true
player:
  enabled: true
  hide:
    favorite: false
    mute: false
    player_selector: false
    power: false
    repeat: false
    shuffle: false
    volume: false
    group_volume: false
  layout:
    controls_layout: compact
    icons:
      shuffle:
        size: small
        box_shadow: false
      previous:
        size: small
        box_shadow: false
      play_pause:
        size: large
        box_shadow: true
      next:
        size: small
        box_shadow: false
      repeat:
        size: small
        box_shadow: false
players:
  enabled: true
  hide:
    action_buttons: false
    join_button: false
    transfer_button: false
media_browser:
  enabled: true
  hidden:
    back_button: false
    search: 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
  favorites:
    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

type: custom:mass-player-card
expressive: true
download_local: false
entities:
  - media_player.kitchen_player_music_assistant
  - entity_id: media_player.bedroom_player_music_assistant
    inactive_when_idle: true
    hide:
      player:
        favorite: true
        mute: true
        player_selector: true
        power: true
        repeat: true
        shuffle: 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
    hide:
      player:
        mute: true
        power: 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: true
        power: true
queue:
  enabled: true
  limit_before: 10
  limit_after: 50
  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

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.

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

📷 Media Player Example

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

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

Display and interact with the player's queue.

📷 Queue Example

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

📷 Media Browser Example

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

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

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.

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.

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

📷 Media Player Example

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

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.

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.

Ensure your music provider actually provides recommendations.

Have you tried listening to music?

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 ecample, 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.

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;

This card currently has complete support for English and majority support for Dutch.

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.

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