Start with the server, then connect Home Assistant
For a Home Assistant Music Assistant setup, get music playing in Music Assistant first, then add its Home Assistant integration. Music Assistant is a separate music server: it combines your sources, manages the queue (the waiting list of songs), and sends audio to supported players. Home Assistant can then provide buttons and routines for those players.
Choose this route when you want one library for several sources or want household routines to start music. If your existing speaker controls already do everything you need, there is no need to add another server. This guide assumes you already have Home Assistant and a speaker supported by a Music Assistant player provider; it is not a speaker buying guide.
The official Home Assistant integration is built in. You do not need a custom dashboard or HACS to establish playback. The similarly named Home Assistant plugin inside Music Assistant serves the reverse connection and is optional for the basic setup below. Our HACS versus apps guide explains where these different kinds of components belong.
Research basis: Home Assistant and Music Assistant documentation checked October 27, 2026. This is a documentation-based walkthrough, not a tested Tara speaker installation. Menu names and available features can differ with installed versions. The cover is an illustrative music-library scene.
1. Check the host and local network
Music Assistant needs an always-on, supported 64-bit host and at least 2 GB of RAM; its project recommends 4 GB or more when other software shares the machine. Check the current CPU and installation requirements before installing. These minimums are not a promise about large libraries, audio processing or the number of rooms you can run.
The supported arrangement puts Home Assistant, Music Assistant and the players on the same local network segment: devices can discover and communicate with each other directly. Ethernet for the server and Wi-Fi for a speaker can still be the same segment. Guest Wi-Fi and separate virtual networks, or VLANs, may prevent that.
Music Assistant's networking guide explains discovery announcements and client isolation. Forwarding discovery announcements alone does not establish a supported audio path. Devices sharing this segment are not isolated from one another; choose the arrangement deliberately. Do not disable your internet firewall or move security devices to troubleshoot music.
2. Install and open Music Assistant
- With Home Assistant OS: follow the app setup steps: open Settings → Apps → App store, find Music Assistant, install the stable release and start it. Open its web interface. Older Home Assistant versions call apps “add-ons.”
- With Home Assistant Container: run the separate Music Assistant Docker server using the project's current installation instructions. Keep its
/datadirectory persistent. The documented host-network setup gives the container direct access to the host's network; it does not bridge separate household networks. - Complete the first-run screen: opening the HAOS app through Home Assistant's sidebar can set up the administrator automatically. Standalone access presents an account setup. Store those credentials securely. See first-run authentication.
Checkpoint: Music Assistant's own interface opens and its settings are accessible. An empty library at this stage is normal. Keep the service on your private network; this walkthrough needs no router port forwarding.
3. Add one source and one player
A music source supplies the songs or stations. A player provider is the connector that lets Music Assistant talk to a family of speakers. Adding one does not replace the other.
- In Music Assistant, open Settings → Music Sources and add Radio Browser for a simple internet-radio check. It needs no subscription or account. Open Browse → Radio Browser, find a familiar station and add it to your library. Stations are not automatically added to the Radio view just by installing the source. Follow the Radio Browser instructions if labels differ.
- Open Settings → Player Providers. Check whether the connector for your speaker is already present; add the appropriate one if needed. Prefer Music Assistant's own provider for the device, such as its Sonos or Google Cast provider, after checking that provider's exact support. Some providers discover players; others require an address. See player-provider setup.
- Select one available, ungrouped room player. Make sure nobody is using it, lower its volume with a known working control, then play the station. Listen briefly and stop it.
Checkpoint: the intended room produces the intended audio, and stop works. A moving progress display alone is insufficient. If this fails, use the table below before adding Home Assistant actions.
For your own collection, add Local Files and select storage the Music Assistant server can actually read. A folder visible on your laptop, or in Home Assistant's media browser, is not automatically visible inside the Music Assistant container. Start with a small folder of files you have permission to play.
Spotify is optional and requires Spotify Premium. A free account will not work. Its current provider offers different playback engines with different account and authentication limits; read the Spotify provider's setup and cautions before choosing one. Music Assistant does not replace the streaming service's subscription or internet connection.
4. Bring the working player into Home Assistant
- In Home Assistant, go to Settings → Devices & services. Configure the discovered Music Assistant server, or select Add integration → Music Assistant.
- If prompted for an address, use the Music Assistant server's local URL, normally
http://SERVER-IP:8095, replacingSERVER-IPwith its real LAN address. This is the music server's address, not Home Assistant's usual port 8123. When a Music Assistant login is requested, its documentation requires an administrator account for the integration. - Open the new integration's entities and identify your room's
media_player. An entity is the individual control Home Assistant uses in dashboards and routines. Note its actual entity ID; do not guess from an example name.
The Home Assistant integration reference confirms the running-server prerequisite. Music Assistant's connection instructions explain the address, account and player selection.
If two controls have similar room names, inspect their integration before changing anything. Use the Music Assistant entity for this music routine. Keep an existing Cast or manufacturer integration if other household features use it; deleting it is not a necessary cleanup step.
Only if a speaker has no native Music Assistant provider should you investigate the Home Assistant Media Players fallback. That reverse route needs the Home Assistant plugin inside Music Assistant and a compatible playback entity. It is not an automatic way to make every Home Assistant device a synchronized music player.
5. Worked example: a kitchen radio button
This example connects the successful checks above into a small, manually started routine. The household wants a familiar station in the kitchen, with no scheduled surprise and no change to other rooms. It is a configuration example, not a measured installation.
- In Settings → Automations & scenes → Scripts, create a script named Kitchen radio. A script is a saved sequence you run when you choose.
- Add a Music Assistant: Play media action. Target only the kitchen entity from the Music Assistant integration. Avoid a room, floor or label target for this first check because it can include several players.
- Set Media ID(s) to the station name you just played and saved. Set Media type to Radio and Enqueue to Replace. This deliberately replaces the selected player's queue. Leave the separate similar-track “radio mode” option off.
- If your installed version offers Username, select the intended Music Assistant user explicitly, as the current action documentation recommends for scripts. Save the script.
- With the kitchen player idle, ungrouped and at low volume, run the script once. Confirm the correct station plays only in the kitchen. Stop it from that player's control. If the station name resolves incorrectly, stop playback and use the item identifier check below.
Field meanings are documented in Music Assistant: Play media; the project also documents starting radio by station name and getting library item identifiers. A URI is the item's precise identifier, rather than its display name.
If two stations share a name: open Developer tools → Actions → Music Assistant: Get library items. Choose your Music Assistant integration, set the media type to Radio, use the same Username as the script when offered, and search for the saved station. Run this read-only action, inspect the returned items, and copy the correct item's uri into the script's Media ID field. If no item appears, return to Music Assistant and confirm the station was added to its library.
Expected result: one deliberate run starts the chosen station in one room, and the player control stops it. If a group is active, stop and turn off that group first, then select the individual player. Do not delete group members during playback.
Once this works, add the script as a dashboard control and keep the player's stop control nearby. If you later add a schedule, decide whether it may interrupt existing music. Our scenes versus scripts guide explains how a button and an automation can share the same routine.
Find the failing stage before changing the setup
Keep the same source and player while checking a failure, then change one of them at a time. This follows the project's troubleshooting approach. The table gives checks to narrow the problem, not diagnoses based on one symptom.
On a small screen, swipe the table sideways.
| What you see | First reversible check | What the result tells you |
|---|---|---|
| The interface opens, but no music appears. | Inspect the music-source settings for a sign-in or scan error; browse one Radio Browser station. | A working station separates basic playback from a paid source's login or a local folder's permissions. |
| A speaker is missing. | Confirm the correct player provider, its supported-device details and the speaker's network segment. | A missing discovery entry alone does not prove broken hardware. A successful ping alone does not prove provider support. |
| The player appears, but stays silent. | Check mute, volume and active groups. Try the same source on another player, then another source on this player. | This separates a source failure from a player path. Music Assistant's web interface and the audio stream use different connections. |
| Music works in Music Assistant but the script fails. | Check the script target's integration, media name or URI, and the Music Assistant account permissions. | The working manual playback narrows attention to the Home Assistant connection or action fields. |
| One physical speaker has several Home Assistant controls. | Read each entity's integration and use the Music Assistant one in this script. | Several control paths can represent the same hardware. Removing a different integration can remove unrelated features. |
| Two rooms sound like an echo. | Stop the group; test each speaker alone and check the documented grouping method. | Playing the same content is different from synchronized playback. Do not keep adjusting volume to fix timing. |
For silent network players, check the server's reported LAN address and stream access in the installation documentation. The web interface normally uses TCP 8095; the audio stream starts at TCP 8097 and may use a later port if occupied. Other player protocols have their own requirements. Opening one port or adding a discovery reflector is not a complete remedy.
If a guest network is suspected, a reversible test is to put one non-critical speaker on the same trusted segment as the server, with household permission, and repeat low-volume playback. Record its previous network so you can restore it. Do not factory-reset the speaker or weaken isolation for the whole home.
Expand to more rooms only after one works
Use a documented native or sync group when the speakers support it. Universal Groups can play the same audio without keeping it in sync, so they are unsuitable when you can hear both rooms together. Newer Sendspin bridging can link some different player types, but support depends on the device and provider; Cast bridging is documented as experimental and disabled by default. Check the current grouping documentation for your exact setup.
Test two rooms at ordinary listening volume before adding more. Listen from the doorway and verify stop behavior as well as playback. This guide makes no promise about delay, sound quality or whole-home synchronization on hardware we have not tested.
Common questions
Does a local Music Assistant server make all music offline?
No. Online stations and streaming accounts still depend on their services. Local files remove that particular music-source dependency, but the server, storage, player and their network must remain available. Check the player's own requirements too.
Do I need HACS or a custom music card?
No. The Music Assistant server and built-in Home Assistant integration provide the basic path here. A custom card can change how the controls look after playback works.
Will this automatically restore music after a spoken announcement?
Do not assume it will. Announcement playback, interruption and recovery need their own supported path and test. Follow our Home Assistant TTS announcement guide before adding spoken messages to a room used for music.