How to set up and use Music Assistant for Home Assistant

Disclosure: This post contains affiliate links. If you click through and make a purchase, I will earn a commission, at no additional cost to you. Read my full disclosure here.

A digital illustration of two women at the turntable playing records.

Introducing Music Assistant – the fresh-faced app taking the Home Assistant world by storm! Recently unveiled during the Let's get loud! stream, this nifty tool is set to become the go-to third-party service for seamless integration with Home Assistant. Don't miss out on this game-changing addition to your smart home setup!

Music Assistant is more than just an extension or custom component

Hold on to your hats, folks – Music Assistant is way more than just another integration in the Home Assistant Community Store (HACS). Get ready for a mind-blowing experience with this bad boy.

Let's start with the Music Assistant integration for Home Assistant, which is the core of the app. It runs like a well-oiled machine, keeping track of all your music sources – from Spotify to YouTube Music to local files. And that's not all! It also imports any compatible media players you've set up in Home Assistant, giving you unparalleled control over playback.

But wait, there's more! Music Assistant also seamlessly integrates with Home Assistant's native Media panel, and it even boasts its very own user interface, which is chock-full of features that will take your smart home game to the next level. So, what are you waiting for? Get your groove on with Music Assistant!

Adding Music Assistant to Home Assistant

You might be concerned that Music Assistant is just an add-on and won't work with anything besides Home Assistant OS, given all the components I just mentioned. But fear not, my friend – you can install Music Assistant using HACS, and it will work flawlessly on any system.

In fact, I, personally, run Home Assistant Core in a Docker container on Unraid, and I have had zero issues using Music Assistant. It's just that versatile!

Finding Music Assistant in HACS is a breeze – no custom repositories necessary. Simply head to the integrations section, search for Music Assistant, and voilà! Once you've installed it and restarted Home Assistant, you'll just need to add it as an integration in the appropriate settings. Easy-peasy, right?

A screenshot showing Music Assistant in HACS
Music Assistant in HACS
A screenshot showing how Music Assistant can be integrated with Home Assistant
Adding the Music Assistant integration to Home Assistant
A screenshot showing various Home Assistant media players being added to Music Assistant
Adding the Music Assistant integration to Home Assistant

Once you've located Music Assistant in the integrations section of HACS and added it to your system, you'll be guided through an effortless configuration process. The first step will be to select which media players you want to import into Music Assistant.

But don't worry – Music Assistant has got your back. It will automatically prevent you from selecting any incompatible or broken entities, so you can rest easy knowing that everything will run smoothly.

Which media players are compatible with Music Assistant?

In theory, Music Assistant can support any media player that integrates with Home Assistant and is capable of playing media from a URL. However, in practice, not all media players implement the play_media service in the same way.

However, don't worry! As Music Assistant gains popularity, developers are sure to find workarounds to ensure compatibility with even more media players. Meanwhile, rest assured that the following media players have already been confirmed to work seamlessly with Music Assistant by both developers and users:

When using Music Assistant, which media players should be avoided (for now)?

It's a shame, but Music Assistant doesn't currently support some of the most popular media players out there, due to reasons beyond its control. Notably, Amazon Echo and other players with integrated Alexa support can't play music from URLs, so there is no way to make them work with Music Assistant. However, there is hope for the future – the upcoming Matter connectivity standard may adopt more media players, so stay tuned!

On another note, Music Assistant doesn't currently support Apple AirPlay compatible devices. This means that popular devices like the Apple TV and Apple HomePod won't work with Music Assistant at the moment. But keep an eye out for updates, as Music Assistant is constantly evolving to support more devices and media players.

Which music services does Music Assistant support?

As of now, Music Assistant supports the following music services, and it's been announced that support for Tidal and Deezer is coming soon:

It's worth noting that the locally stored files need to be stored or accessible locally, as Music Assistant doesn't support mounting shares directly. But don't fret – this is an easy fix. I, personally, mounted my media folder as a Docker mount, which allows Music Assistant to see the files as local files, even though they're located in a different folder.

At present, Music Assistant can only import and display items that are marked as favourites in your library. However, there's good news on the horizon – a new feature that allows you to browse a streaming service's recommendations is in the works, and is expected to be released soon.

It's worth noting that Music Assistant can't import services that are already integrated with Home Assistant. For instance, if you've already set up the Spotify integration, you will need to enter your credentials again when configuring Music Assistant. Unfortunately, this is unlikely to change anytime soon, as the Spotify integration with Home Assistant functions as a media player, and doesn't import your library.

A screenshot showing the configuration of Spotify and TuneIn in Music Assistant

Hiding source players and creating media players for Music Assistant

A screenshot showing Music Assistant's advanced options: One setting allows the user to hide source players in the Home Assistant Dashboard. The other setting allows the user to have Music Assistant create media players from those already configured in Home Assistant.
New users should leave the advanced settings in their default position

The final step in the configuration process is to choose which advanced settings you want to enable or disable. I recommend leaving these settings enabled, as they are set by default. Let's go through these options, as they can help you understand Music Assistant even better:

To function properly, Music Assistant needs to create its own media players. In my setup, I added my Squeezebox, which is integrated with Home Assistant using the Logitech Media Player integration. However, Music Assistant can't use this entity to its full potential, so it creates a new one called media_player.mass_squeezebox. Using the option to hide source players in the Home Assistant Dashboard can keep things cleaner and reduce errors.

If you intend to use Music Assistant for your media needs, it's best to add its media players to the dashboard, rather than the source media player. In the screenshot below, you can see both the Music Assistant media player (at the top), and the source media player (at the bottom). The source player only presents basic controls and shows the track info as “Streaming from Music Assistant.” The Music Assistant media player, on the other hand, gives you full control and displays the track and artist, along with the cover art of the track playing (in this example, “Lisa” by Kaufmann).

The Home Assistant Dashboard, displaying the Music Assistant player (top) and source player (bottom)

To ensure that your Home Assistant Dashboard looks its best after setting up Music Assistant, be sure to adjust the displayed entities accordingly.

Using the Music Assistant interface

Using the Music Assistant interface is a breeze, although it currently prioritizes form over function. I'm hoping to see improvements in this area over the coming months, as I'm sure many users would love to use it on wall-mounted tablets. Once you've opened up Music Assistant (which places a link in the Home Assistant Sidebar), you'll be able to choose between artists, albums, tracks, playlists, or radio.

The “radio” option will import any stations you've marked as favourites in TuneIn, provided you've set it up during the configuration process. However, Music Assistant doesn't currently import any radio stations from Home Assistant's media browser.

Music Assistant's main interface

The real magic happens when you delve into an artist and see how Music Assistant handles multiple sources. Instead of displaying duplicates, Music Assistant merges any libraries you've configured. In the example below, I have the Arctic Monkeys in my Spotify library, as well as ripped from a CD and stored locally. An icon indicates the source for each track. The system relies on the ID3 tags stored in the music file, so make sure to set them up correctly using a tool like Mp3tag for seamless use.

Music Assistant will automatically merge multiple libraries

From here, you can start playing any artist, album, or track. What's more, you can use Music Assistant as a jukebox by adding various items to your queue. However, it's worth noting that Music Assistant automatically picks the highest quality track, so if not all of your local files are showing, it's because they're of lesser quality than what's available online.

Using Music Assistant entities in automations and scripts

You can use any media player created by Music Assistant as you would use any other media player. It supports the media_player.play_media and you have the same options to play your media immediately, or queuing it.

The play_media service in Home Assistant being used by a Music Assistant media player.

Music Assistants enables text to speech TTS without stopping the music

One of my favourite features of Music Assistant is its ability to use text-to-speech without stopping the music. There have been various scripts and apps that attempt to make this possible, but none are as seamless and effortless as Music Assistant.

To enable this feature, you'll need to use the media player created by Music Assistant. If you use the source media player, this won't work. You can choose any text-to-speech provider you prefer, have the speaker pause the music, say whatever you've instructed it to say, and then resume your queue from where it left off. It's a super convenient way to enjoy both your music and important announcements.

Music Assistant conclusion: One to look out for

While Music Assistant can greatly enhance the music capabilities of Home Assistant, it may not be for everyone – at least, not yet. There is still some work to be done, especially when it comes to the interface. Currently, it looks and behaves very much like a tool for tech-savvy users, rather than something that would look great on a wall-mounted display or tablet.

If all you do is occasionally play playlists or albums using scripts or automations, there may not be a real need to install Music Assistant. After all, you would have to adjust all your scripts and automations to include the Music Assistant media player. However, if you also use text-to-speech (TTS) in those scripts/automations, Music Assistant can enable seamless continuation of your music after it has made the announcement. Furthermore, if you want to start music playback directly from Home Assistant without having to copy URLs, Music Assistant makes the process a breeze.

If you're looking to play local media on your network-attached speakers, then Music Assistant is a must-have. Although various applications that allow you to cast local media do exist, none of them support all the devices that I own (e.g., my old Squeezebox).

As I mentioned earlier, I can see Music Assistant becoming a central part of many Home Assistant users' setups. This application already boasts some impressive feats, and I can't wait to see what the future holds.

A portrait photo oif Liam Alexander Colman, the author, creator, and owner of Home Assistant Guide wearing a suit.

About Liam Alexander Colman

is an experienced Home Assistant user who has been utilizing the platform for a variety of projects over an extended period. His journey began with a Raspberry Pi, which quickly grew to three Raspberry Pis and eventually a full-fledged server. Liam's current operating system of choice is Unraid, with Home Assistant comfortably running in a Docker container.
With a deep understanding of the intricacies of Home Assistant, Liam has an impressive setup, consisting of various Zigbee devices, and seamless integrations with existing products such as his Android TV box. For those interested in learning more about Liam's experience with Home Assistant, he shares his insights on how he first started using the platform and his subsequent journey.


  1. hi,

    can Music Assistant ‘see’ DLNA Music sources, Home assistant introduced support and all my music files are visible via DLNA

    thanks in advance


    • Hi there. Music Assistant can indeed play to DLNA music sources. I just tested this with an old alarm clock. However, the controls did start acting up after some time. I can’t say who’s fault that is.

  2. I have installed Music Assistant, but when I want to play someting, my speaker keeps on buffering and play does not start. Did I do something wrong?

  3. I have installed Music Assistant in Home Assistant, but when I want to play a song, the Google speaker keeps on buffering and does not start to play.
    How can I solve this problem?


Leave a comment

Share to...