In this article
Music Assistant can display albums, search a streaming service, or index local files while showing no usable local speaker. That is not necessarily a contradiction: content access and speaker access are separate responsibilities.
The distinction is easiest to understand as three layers:
- Music-source access: Where does the content come from?
- Local-player discovery and connectivity: Can Music Assistant reach the speaker on the local network?
- Player output configuration: Which protocols are available for a player Music Assistant already knows about?
A working music provider establishes only that the first layer works. It does not establish that Music Assistant can discover a local speaker or use an output protocol for it.
This is a documentation-based explanation. No speaker, network, or Music Assistant release was tested.
The three-layer responsibility map
| Visible result | Relevant layer | What the documentation covers | What the result does not establish |
|---|---|---|---|
| Albums, tracks, or playlists appear | Music source | Adding sources, reading their content, and combining it into the library | Local-player discovery or playback |
| A local speaker is absent | Network discovery | Direct layer-2 access, same-network requirements, and supported Docker networking | Compatibility with a particular speaker |
| A player appears, but its output options are limited | Individual player | Available protocols and per-player settings | That every protocol is available on every device |
| Software players work through a Docker bridge, but network speakers do not | Network discovery | Bridge networking for software-player-only use | Support for local-player discovery |
These layers interact during playback, but Music Assistant documents them as distinct configuration areas.
Layer 1: Music sources provide content
A music source answers one question: Where does the music live?
Music Assistant defines a source as a streaming service, a folder on a disk or NAS, a media server such as Plex or Jellyfin, or a directory of radio stations, podcasts, or audiobooks. It reads configured sources and combines their content into one library (Music Sources).
No music sources are installed initially. Each required source must be added, and content does not appear merely because Home Assistant can already access it (Installing the Server; Music Sources).
Source settings can govern:
- Whether the source is enabled
- Which media categories are synchronized
- Whether album or playlist tracks are imported
- Whether supported library changes are synchronized back to the originating source
- Provider-specific configuration
If Music Assistant can browse or search content from a configured source, it can read that source. This does not show that the server can communicate with a speaker.
Source credentials and library-import settings are therefore unlikely to explain a missing speaker when the expected music is already visible. Those settings control content access and library behavior, not local-player discovery.
Layer 2: Local players require direct network access
Speaker discovery belongs to the deployment and networking layer.
Music Assistant’s installation documentation says the server must be on the same layer-2 network as its players. It also requires direct layer-2 access to discover and stream to local or networked players (Installing the Server).
This matters particularly in Docker. A container may be able to read mounted storage or reach another content source without having the local-network access required for players.
For Docker deployments using local or networked players, the documented requirement is host networking or macvlan networking. Music Assistant relies on direct network access for discovery mechanisms such as mDNS and UPnP and for networked audio systems that use TCP and UDP ports (Installing the Server).
Normal Docker bridge networking is documented for the narrower case in which there are no local or networked players and playback goes only to software players. With bridge networking, player discovery and players requiring direct network access will not work. The documentation names AirPlay, Chromecast, DLNA, and Sonos as examples and says this configuration is unsupported for local-player use (Installing the Server).
The following outcomes can therefore coexist:
- Music Assistant successfully reads a streaming or file-based source.
- A local speaker remains absent because the deployment does not meet the documented network requirements.
Meeting those requirements still does not guarantee discovery. Same-layer-2 placement and supported Docker networking are prerequisites, not proof that a particular speaker is supported or exposes a usable protocol.
Layer 3: A known player exposes output protocols
Output-protocol configuration becomes relevant after Music Assistant has a player to configure.
Music Assistant can combine multiple available protocols from one device into a single player. Recognized protocols appear as chips and in the player’s Output Protocols section (Individual Player Settings).
Each available protocol has its own configuration section. Non-native protocols can be disabled, while the device’s native protocol cannot be disabled through that setting (Individual Player Settings).
Depending on the player and provider, settings may cover:
- Enabled output protocols
- Output codec
- Sample rates and bit depths
- Flow mode
- Metadata handling
- Power, volume, and mute controls
Not every player exposes every option. Providers may set defaults or hide settings that do not apply, and some settings depend on the player’s reported capabilities (Individual Player Settings).
These controls do not perform discovery. They configure protocols already available for a player known to Music Assistant. Changing an output codec or enabling an available non-native protocol cannot make an undiscovered speaker appear.
Read the symptom at the correct layer
Three conclusions are easy to draw incorrectly:
“The provider works, so the network is configured correctly”
Provider access shows that Music Assistant can reach the content source. It does not show that the server has direct layer-2 access to local players.
“The speaker is on the same network, so it must appear”
Same-layer-2 access is a documented prerequisite, not a guarantee that every speaker will be discovered or supported.
“Music Assistant documents this protocol, so my speaker must work”
The individual-player documentation describes protocols available for recognized players. It does not promise compatibility with every device that advertises a similarly named protocol.
The diagnostic boundary is straightforward: use source documentation for missing content, installation documentation for local-network prerequisites, and individual-player settings for protocols on players that are already present. Success at one layer is not evidence that the other two are complete.
No comments yet