In this article
Music Assistant distributes related options across several pages because each page controls a different part of the system. Think of the three layers as a delivery chain: the source decides what enters the library, the player decides how one endpoint receives and processes audio, and the Home Assistant Plugin makes existing Home Assistant capabilities available to Music Assistant.
Use this first-pass rule:
- Content entering or synchronizing with the library: configure the music source.
- Audio handling for one playback device: configure the individual player.
- A capability supplied by Home Assistant: configure the Home Assistant Plugin, then select the exposed entity in the relevant player or feature.
This is a responsibility map, not a setup guide or a setting-precedence hierarchy. It is based on Music Assistant documentation retrieved September 30, 2026. No hands-on test was performed. The documentation does not establish universal compatibility, performance, latency, audible improvements, automatic fallback, or precedence among undocumented or overlapping settings.
Responsibility map
| Desired behavior | Owning layer | Documented example | Important boundary |
|---|---|---|---|
| Control what a source contributes to the library | Music source | Import album tracks or playlist tracks (Music Sources) | Options can vary by source |
| Send library changes back to a provider | Music source | Sync library additions and removals (Music Sources) | A change goes only to the item’s originating source |
| Process audio separately for one player | Individual player | DSP filters (Individual Player Settings) | DSP is independently configured per player |
| Choose how Music Assistant sends audio to one player | Individual player | Preferred output protocol and protocol-specific options (Individual Player Settings) | Available protocols depend on the player |
| Use a Home Assistant entity for power, mute, or volume | Plugin, then individual player | Expose an eligible entity, then assign it under Player Controls (Home Assistant Plugin Provider) | Exposure and assignment are separate steps |
| Use Home Assistant AI or speech capabilities | Home Assistant Plugin | Expose AI Task and text-to-speech entities as engines (Home Assistant Plugin Provider) | Home Assistant must already provide the entities |
One adjacent component is easy to confuse with these layers. Adding Home Assistant media players to Music Assistant requires the Home Assistant Media Players provider. The Home Assistant Plugin is a prerequisite for that provider, but the plugin does not add players by itself (Home Assistant Plugin Provider).
Music sources own library and synchronization behavior
A music source is where content lives: for example, a streaming service, local files, or a media server. Music Assistant combines configured sources into one library, while each source retains controls for what is imported and synchronized (Music Sources).
This is where settings such as media-type synchronization, album-track import, playlist-track import, two-way library synchronization, and supported podcast or audiobook progress synchronization belong.
For example, importing a playlist normally adds the playlist itself without adding all its tracks as separate library items. Import playlist tracks changes that behavior for specified playlists, identified by a case-sensitive playlist name or playlist URI. Likewise, Import album tracks changes the documented default from importing only an album entry to importing its associated tracks. Some streaming sources may already add all tracks to favorites, so neither option proves that every provider behaves identically (Music Sources).
The source boundary remains important after content is combined in Music Assistant. With sync-back enabled, adding or removing a library item affects only that item’s originating source. Choosing an item associated with one streaming service does not apply the same change to another service offering similar content (Music Sources).
Individual players own DSP and output protocols
When a change concerns one playback endpoint, look under its Individual Player Settings rather than the source that supplied the music.
Music Assistant documents DSP as independently configurable for each player. Two players can therefore use separate DSP configurations. That establishes where the controls belong, but not what audible result a filter will produce (Individual Player Settings).
Output protocol selection is also a player responsibility. Individual Player Settings contains Preferred Output Protocol and configuration sections for the protocols available to that player. Music Assistant can combine multiple protocols exposed by one device into a single player entry (Individual Player Settings).
Not every player exposes every documented setting. Providers can supply defaults or hide options that do not apply, while other controls depend on player capabilities. Protocols can be disabled except for a device’s native protocol. Some options are also hidden until advanced settings are enabled (Individual Player Settings).
A missing option therefore does not automatically belong at another layer. It may simply be unavailable for that player or provider, or hidden in the current settings view.
The Home Assistant Plugin exposes HA capabilities
The Home Assistant Plugin is the bridge Music Assistant uses to reach Home Assistant. It exposes eligible Home Assistant entities for player controls and makes existing AI Task and text-to-speech entities available to Music Assistant features (Home Assistant Plugin Provider).
Power, mute, and volume cross two layers
Linking a Home Assistant entity to a player control takes two steps:
- Select the eligible entity in the plugin’s power, mute, or volume list.
- Assign that exposed entity under the individual player’s Player Controls settings.
Power and mute candidates must support on/off behavior and have a boolean state. Documented examples include suitable switch, input_boolean, and media_player entities. Volume candidates need a numeric value or state; examples include suitable number, input_number, and media_player entities (Home Assistant Plugin Provider).
For an amplifier represented by a numeric Home Assistant entity, the plugin owns exposure of that entity, while the individual player owns its final assignment as the volume control.
These entity filters are not compatibility guarantees. A linked power entity also cannot restore mains power to the player itself. Once the player is off the network, Music Assistant marks it unavailable and disables its controls. The documented use is to control downstream equipment such as an amplifier or active speakers instead (Home Assistant Plugin Provider).
AI and text-to-speech remain divided
The plugin exposes existing Home Assistant AI Task and text-to-speech entities as engines; it does not supply the underlying AI or speech service. Model, voice, language, speaking speed, and audio-quality choices remain in Home Assistant. A Music Assistant feature then selects an exposed engine where that feature provides a choice (Home Assistant Plugin Provider).
When deciding where an option belongs, ask three questions:
- Does it change what enters or synchronizes with the library? Use the music source.
- Does it change one playback endpoint? Use the individual player.
- Does it provide access to an existing Home Assistant capability? Use the plugin, followed by the relevant player or feature selection.
No comments yet