Music Assistant for beginners: one library, every speaker
Every speaker brand wants its own app, its own account, and its own idea of your music library. Music Assistant takes the opposite bet: one self-hosted server that knows your music — streaming services and local files alike — and can play it on whatever speakers you already own, in sync, controlled from Home Assistant. It is the missing middle of a local-first music setup, and it installs in one container.
Published Nov 17, 2026
What Music Assistant actually is
Two halves. The server holds the library: it indexes your streaming accounts and local files into one searchable collection, handles queues and playlists, and does the unglamorous work of remembering what you like. The players are your existing speakers — Chromecast devices, AirPlay speakers, Sonos, many smart speakers and Home Assistant media players — which Music Assistant discovers and treats as interchangeable outputs. Group the kitchen and the patio, send the same album to both, in sync, from one interface. If you have followed this site's voice work, this is also the playback engine that makes 'play something' voice commands land on real speakers.
Step 1 — run the server
services:
music-assistant:
image: ghcr.io/music-assistant/server:latest
container_name: music-assistant
restart: unless-stopped
network_mode: host # needed for speaker discovery (mDNS/Cast/AirPlay)
volumes:
- ./music-assistant/data:/data
- /path/to/music:/media # your local files, if you have them
environment:
- TZ=America/New_York
Host networking deserves its note: speaker discovery protocols (Chromecast, AirPlay, DLNA) rely on multicast traffic that Docker's default bridged networking hides. network_mode: host puts the container on the LAN as a first-class citizen, and the web interface appears at http://your-nas-ip:8095. This is the same pattern as Home Assistant itself, and for the same reason.
Step 2 — add music and speakers
- Open the web UI → Settings → Music providers: sign in to a streaming service and/or add the local filesystem provider pointed at
/media. The first library sync takes a while on big collections; it is a one-time cost. - Settings → Players: your discoverable speakers usually appear on their own once the server can see the LAN. Name them by room — those names become the targets you will use everywhere else.
- Play something to one speaker, then group a second in mid-song. That small moment — two brands of speaker in sync from one queue — is the entire pitch, delivered.
Step 3 — the Home Assistant tie-in
Add the Music Assistant integration in Home Assistant and your players become first-class media players: dashboards get proper controls, automations can start playlists when you get home, and — the real prize — the local voice pipeline from our Whisper + Piper guide can target any speaker in the house. 'Play jazz in the kitchen' stops being a cloud trick and becomes your house, talking to itself.
Start small: one provider, two speakers, one playlist you actually love. Music Assistant's depth (cross-provider playlists, smart fading, per-player DSP) rewards exploring later — but the beginner win is a single queue that plays anywhere, and you can have it in fifteen minutes.
Troubleshooting
- No speakers discovered: almost always networking — the server is not in host mode, or the speakers live on a guest/IoT VLAN that blocks multicast from the server's network.
- Streaming provider keeps logging out: some services need a fresh sign-in after their own security events; re-authenticate in the provider settings rather than reinstalling anything.
- Playback stutters on grouped players: Wi-Fi, not Music Assistant — grouped sync is unforgiving of a weak signal to any one speaker. The speaker with the worst connection sets the ceiling.
- Local files missing from the library: check the container can actually read the path (the
/mediamount) and that the filesystem provider is set to watch that folder, then re-run a sync.
The quiet superpower: one library across services
The feature that converts people is not the grouping — it is what happens to your library. Music Assistant merges your sources into a single collection: the album you own as files and the playlist you built on a streaming service sit side by side, searchable in one place, queueable in one breath. Playlists can mix sources track by track. Your carefully built 'Sunday morning' list stops caring which service each song came from, which means it survives the day you switch providers — the library is yours, hosted on your hardware, and the services become interchangeable suppliers. Pair that with radio-style endless playback from any starting track and per-player sound shaping, and the pattern emerges: this is the same local-first argument as the rest of this site, applied to music. Own the library; rent the catalog.
Gear for this build
Prices are editorial and change often; buttons show live prices. Some links may earn a commission at no cost to you — see the disclosure page.
Official documentation and references
- Music Assistant — the project's official site and documentation
- Music Assistant documentation — installation options
- Music Assistant documentation — supported players and providers
- Music Assistant on GitHub — the official server repository
Frequently asked questions
Is Music Assistant free?
Yes — it is open source and self-hosted, with no subscription. Your streaming services still cost whatever they cost; Music Assistant is the librarian and conductor, not the music itself.
Does it replace Spotify or Apple Music apps?
For playing music at home, largely yes — one interface over all of them, plus your files. You will still use the native apps for downloads on your phone and discovery features; Music Assistant owns the house.
Which speakers work best?
Anything speaking Chromecast, AirPlay or Sonos protocols is a strong citizen, and Home Assistant media players (including ESPHome satellites) join in too. The practical rule: if it can be discovered on your LAN, Music Assistant can probably play to it.

