Music Assistant

The Music Assistant (MA) integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to connect Home Assistant to a Music Assistant Server. Once configured, all MA Players show up as Home Assistant media player entities. Media players will allow you to control media playback and see the currently playing item.

Prerequisites

This integration connects to a Music Assistant server.

• If you run Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports apps. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users., you don’t need to prepare anything. Home Assistant can install and start the official Music Assistant app for you during setup.
• For other installation types, or if you want to run the Music Assistant server somewhere else, make sure you have a running Music Assistant server first. Instructions are available in the Music Assistant documentation.

Configuration

To add the Music Assistant service to your Home Assistant instance, use this My button:

Music Assistant can be auto-discovered by Home Assistant. If an instance was found, it will be shown as Discovered. You can then set it up right away.

Setting up with the Music Assistant app

If you run Home Assistant Operating SystemHome Assistant OS, the Home Assistant Operating System, is an embedded, minimalistic, operating system designed to run the Home Assistant ecosystem on single board computers (like the Raspberry Pi) or Virtual Machines. It includes Home Assistant Core, the Home Assistant Supervisor, and supports apps. Home Assistant Supervisor keeps it up to date, removing the need for you to manage an operating system. Home Assistant Operating System is the recommended installation type for most users., the setup asks whether you want to use the official Music Assistant app.

1. Keep Use the official Music Assistant app selected and select Submit.
   • If the app is not installed yet, Home Assistant installs it. This can take several minutes.
   • If the app is not running, Home Assistant starts it.
2. If this is a new Music Assistant installation, Music Assistant opens in a new browser tab. Finish its initial setup there.
   • Home Assistant continues automatically once the Music Assistant setup is done.

If you already run Music Assistant in another way, for example in a different app, in your own container, or on another machine, clear the Use the official Music Assistant app checkbox. You can then enter the URL of your Music Assistant server manually.

Manual configuration

Under normal circumstances, Home Assistant automatically discovers your running Music Assistant server. If there is something special about the Home Assistant or Music Assistant setup (for example, the Music Assistant server is running as a remote Docker container) or discovery is not working, you can manually specify the URL to your Music Assistant server.

Supported functionality

There is currently support for the following Home Assistant Platforms:

• Media player
• Dashboard displays
• Button

Depending on the player provider, additional platforms are supported: Number, Select, Sensor, Switch, Text.

Music Assistant player entities support all of the Home Assistant media player control actions. Dashboard display entities support only media playback, media browsing, and turning off.

If using media_player.play_media, then note the media_content_id payload can be any of the following:

• The name of a track, artist, or album. For example, Queen.
• A track or album combined with the artist’s name. For example, Queen - Innuendo.
• A streaming provider URI. For example, spotify://artist/12345.
• A streaming provider URL. For example, https://open.spotify.com/track/31cWPvM99ZHxMl3mdgiw4I.

The media_player.play_media action runs as the Home Assistant user who made the request if their username matches a Music Assistant user. This affects the playlog entry and any provider filtering configured for that user. The media_player.play_media action doesn’t let you choose the user, so if you call it from a script or automation and want the request attributed to a specific user, use the Music Assistant Play media action instead and set its Username field.

If using media_player.browse_media, then the media_content_id payload must be a URI of the form library://artist/1, library://album/20, or spotify://album/5zj4Ej0FrlJQaSo0d6cttH. The type of item that the URI refers to must be an album or artist.

These URIs can, for example, be obtained from the output of the Get library items or Search Music Assistant actions, or the media_player.browse_media action from Home Assistant.

Streaming provider URLs can be obtained from the web interface of the provider.

Media player entities

The Music Assistant integration creates media player entities for all players and groups available in MA, including those imported from Home Assistant. This is needed to provide the full functionality Music Assistant has to offer. This full functionality includes transfer of the playing queue of music from one player to another, automatic pausing of playback during announcements, and richer options for selecting the media for playback. These entities will display media information, playback progress, and playback controls.

Dashboards

Music Assistant can show dashboards, such as a party queue or a “Now playing” screen, on display devices like a Chromecast running the Music Assistant receiver, a Fully Kiosk browser, or an Apple TV. Each display becomes its own Home Assistant device (a “Dashboard display”) with a single media player entity, using the tv device class. A display gets its entity while its provider is running, and the entity becomes unavailable whenever the display disconnects. A browser tab open on the Music Assistant web interface is not a display device.

To show a dashboard from an automation or script, perform the media_player.play_media action on the display entity. The easiest way to set it up is to add the action in the editor and use Pick media to browse to the dashboard you want. Home Assistant then fills in the media content ID and type for you.

The media content type is always dashboard. The media content ID is party, music_quiz, or now_playing/<player id> for the “Now playing” screen of a specific Music Assistant player. For example:

action: media_player.play_media
target:
  entity_id: media_player.kitchen_display
data:
  media_content_type: dashboard
  media_content_id: now_playing/<player id>

You can also pick a dashboard from the entity’s media browser. It lists the dashboards the display supports, with a “Now playing” folder to pick which Music Assistant player to show.

To hide the dashboard again, call media_player.turn_off. This is safe to call even when nothing is shown, or when the display has disconnected.

While a dashboard is shown, the entity’s state is playing, with the dashboard’s name and artwork as the media title and image. It returns to idle when nothing is shown, and becomes unavailable if the display disconnects.

Showing an unknown or unsupported dashboard, or using now_playing without a player, returns a clear error message.

The Music Assistant actions, such as Play media, Play announcement, Transfer queue, and Get queue, only work with speaker entities. To show a dashboard, use the standard media_player.play_media action described above.

This feature requires Music Assistant server version 2.10 or later.

Favorite current song button

The Music Assistant integration creates a button entity for each player to favorite the current song. Pressing this button (manually or by automation) adds the current song to your Music Assistant favorites. This works for songs stored locally as well as for tracks from streaming providers. It also works with remote content such as Spotify Connect, AirPlay, or a radio station, as long as the external source provides an artist and title combination (and optionally the album).

Player options

If a player provider supports player options, the Music Assistant integration exposes additional entities. For example, you may have a number entity to adjust the media player’s bass or treble value. Refer to the Player documentation to see whether your player supports this.

List of actions

The Music Assistant integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

• Get library items (music_assistant.get_library) Retrieves items from a Music Assistant library.

• Get queue details (music_assistant.get_queue) Retrieves the details of the active queue of a Music Assistant player.

• Play announcement (music_assistant.play_announcement) Plays an announcement on a Music Assistant player with fine-grained control options.

• Play media (music_assistant.play_media) Plays media on a Music Assistant player with fine-grained control options.

• Search Music Assistant (music_assistant.search) Performs a global search on the Music Assistant library and all providers.

• Transfer queue (music_assistant.transfer_queue) Transfers a player’s queue to another Music Assistant player.

For an overview of every action across all integrations, see the actions reference.

Notes

• Any Home Assistant players added to Music Assistant will appear duplicated as the MA version of the player is created. The original HA player can be hidden if desired.

Supported devices

This integration requires Music Assistant server version 2.4 or later. The integration can connect to Music Assistant servers hosted as an app or in a separate Docker container.

Music Assistant supports a wide range of devices both natively and through the Home Assistant provider. The Home Assistant provider, when installed, allows any Home Assistant media player to appear as a player in Music Assistant and thereby benefit from the advanced playback functionality that Music Assistant provides. As a general note, if there is a native Music Assistant provider then devices should be added via that method instead of using the Home Assistant media player. Any limitations associated with the providers are described on the related Player Provider page in the Music Assistant documentation.

Known limitations

The data returned by the get_queue action will be partially limited if the item is not in the library (For example, if an item was selected for playback directly from Spotify). Metadata such as favorite status, explicit status, last played, played count, and disc art URL are only available for items that are in the MA library.

Radio mode is only available with certain music providers, and an error will be shown if attempting to enable radio mode on an item that isn’t linked to one of those providers. Review the Music Assistant documentation to identify which providers support this functionality.

Troubleshooting

Can’t find the MA actions

Symptom: No Music Assistant actions are shown in the editor

When trying to set up a script or automation via the GUI, no MA actions can be found.

Description

This means the app may have been installed, but the integration has not.

Resolution

Go to the Configuration section and install the integration.

Removing the integration

This integration follows standard integration removal.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. Next to the entry you want to remove, select the three dots menu. Then, select Delete.
   • Depending on the integration, the entries are listed under one of the following headings:
     • Devices
     • Hubs
     • Services
     • Integration entries
3. To confirm, select Delete.
   • Home Assistant also deletes the devices and entities of the entry.
4. If Home Assistant asks you to restart, restart Home Assistant.
5. If Home Assistant asks whether to also delete the application credentials, select Remove or Keep.
   • If you keep them, Home Assistant uses them automatically when you add the integration again.
   • To delete them later, refer to Deleting application credentials.

After deleting the integration, go to the Settings > Apps and remove the Music Assistant app from there as well (if installed).