MA System Settings

The core server settings are set with typical defaults that should work for most users. However, there are settings available for each of the core controllers and these are outlined below. Each one opens a page with a Documentation button, which links to its section below, and an Options card holding all of its settings. Some settings only show when the Show advanced settings toggle in the card’s header is on, and the toggle is remembered for your user. All controllers have a setting for the log level among the advanced settings. There may be slight differences in the settings between the Home Assistant App and docker versions of the servers.

Background Tasks (configuration)

• Maximum number of concurrent background tasks. Defaults to 2. This controls how many background tasks run simultaneously. Higher numbers mean higher demands on the system’s resources and can slow the system down. Setting is only visible when the advanced toggle is on

Cache

• A button is available to clear the cache used by Music Assistant. Do not routinely use this button as it increases API usage and slows down the MA experience

Discovery

• Allow network scan for UPnP discovery. When enabled, MA uses an additional broadcast based discovery method (SSDP). Turn this on if some UPnP/DLNA players are not being found by regular discovery (see the discovery checklist)
• MDNS/Zeroconf discovery interface(s). Options are Default interface [default] and All interfaces. Used in custom network setups when multiple network interfaces are used. Setting is only visible when the advanced toggle is on

Metadata

• Preferred language. Preferred language for metadata. If the selected language is unavailable then English will be used. This language is also used for text searches, so localised names such as genres and the built-in playlists can be found by the name shown in this language
• Enable metadata retrieval from online metadata providers. Enables the lookup of information that is not available locally. MA does not modify any existing metadata but supplements it
• Advanced - Link items to your other music services through MusicBrainz. On by default. Uses the links MusicBrainz keeps to find the artists, albums and tracks of your library on your other music sources, instead of searching each source for them. A background task works through the library in small batches after a library sync and once an hour, and items are also linked whenever their metadata is refreshed
• Use local genre metadata only when available. Online metadata providers will not add genres to items that already have a genre from a local source such as a file tag or NFO file. Items with no local genre still receive genres from online providers as usual
• Enable artist/track artwork lookup for radio streams. Enables the lookup of album or artist imagery when the station supplies Artist - Track metadata
• Maximum thumbnail cache size(MB). When the cache exceeds this value the oldest thumbnails are automatically removed

Music

• Advanced - Keep remastered versions apart. Off by default. Keeps a track or album that is named as a remaster, such as Remastered 2009, apart from the original in the library instead of merging the two. Tracks and albums that were already merged stay merged. Read Keep remastered versions apart before turning it on
• Advanced - Reset Library Database. Selecting this button will erase the MA library database. This is a destructive irreversible action! This should only be used if database corruption is confirmed. All library items including playlists stored in the database will be lost and will need to be recreated. A rescan of the music sources will rebuild the database with the information contained on those providers. Do not use this routinely. For problems with individual items use the REMOVE FROM LIBRARY menu option

Players

• Volume step size. Defaults to zero which enables an adapative mode where the step size is smaller at the ends of the range. When set, this determines how much the volume change when an up or down command is received (e.g. mouse wheel click, slider tap, HA action)
• Announcement text to speech engine. Which engine is used to generate announcements sent from within Music Assistant. The engines on offer come from your plugins, such as the Home Assistant Plugin

Player Queues

The behaviour when playing or enqueuing items is determined by the settings in this section.

Items to select

• Items to select when you play a (in-library) artist. The options are All tracks from all providers [default], Artist top tracks only, In-library tracks for the artist only and Prefer library, fall back to top
• Order to play an artist in. The options are Shuffled tracks [default], Albums in random order, each album in track order and Albums by release year, oldest first. Shuffled tracks plays the tracks picked by the artist selection in random order. The album orders play the artist’s albums one after another, either picked at random or from the oldest to the newest, with albums without a year last
• Items to select when you play a (in-library) album. The options are All tracks for album on (streaming) provider [default] and Only in-library tracks

With either album order:

• The artist selection picks the artist’s own albums. The in-library selections play the albums in your library. All tracks from all providers also plays the albums found only on a provider.
• Each album plays as it does on its own, following Items to select when you play a (in-library) album.
• Each album plays once, even when your library and a provider both have it.
• If one copy of an album can’t play, another copy plays instead. With Only in-library tracks as the album selection, an album in your library plays only your saved tracks.
• Singles are left out, as their songs are mostly on the albums.
• Compilations in your library still play. Compilations found only on a provider are left out, as their songs are already on the albums.
• Artist top tracks only still plays shuffled tracks.
• An artist without albums plays shuffled tracks instead. For example, an artist with only singles, or one that only appears on another artist’s albums. If the artist’s albums can’t be listed because a provider is offline or fails, and your library has none of them, nothing plays.

An album order switches shuffle off for the queue, as when you play an album. An artist without albums keeps the queue’s shuffle, and so does Artist top tracks only. Asking for shuffle when you start the artist still shuffles it. The setting does not apply to authors and narrators, as they play audiobooks.

Default enqueue options

What happens to the queue when an item is played. There is one setting each for Artist, Album, Track, Genre, Playlist, and Radio and Live Input items (radio stations and plugin sources such as Spotify Connect and AirPlay Receiver). Each can be Play (and replace queue) or Play (and keep queue). Tracks default to keeping the queue and everything else defaults to replacing it.

Click actions

• What clicking an artist / album / track / genre / radio / playlist does. One setting per item type. Open it [default] opens the item, Play it starts playing it straight away
• What playing a track from an album does. Play from this track onwards [default] continues with the rest of the album, Play only this track plays just the chosen track
• What playing a track from a playlist does. The same two options, for tracks in a playlist

Smart Shuffle, Autoplay and Crossfade

These options are set on a global level and can be overridden on a per queue basis.

Smart Shuffle enhances standard shuffle behavior by intelligently reducing repetition. Instead of selecting tracks purely at random, songs and artists that have been played recently are deprioritized, resulting in a more evenly distributed listening experience and reducing the likelihood of the same tracks being repeated when playlists are replayed. Smart Shuffle is always applied when playing a dynamic playlist, regardless of this setting.

• Smart shuffle. Disabled [default] or Enabled. When enabled, the shuffle button uses Smart Shuffle instead of a plain random shuffle
• Avoid replaying the same song heard within. How long a song that has already been heard is pushed toward the back of the queue. From Off to 4 weeks, default 1 week
• Avoid replaying the same artist heard within. The same for artists. From Off to 2 hours, default 30 minutes
• Advanced - Minimum gap before repeating a deliberately-duplicated song. When the same song is added to the queue more than once on purpose, this is the shortest time before it may play again. From Off to 24 hours, default 3 hours

Optimize order for Smart Fades is an optional Smart Shuffle setting. When Smart crossfade is active, Music Assistant uses existing Smart Fades analysis to arrange upcoming tracks so Smart Fades has a better chance of creating a smooth transition between consecutive tracks. It considers tempo, musical key and how the energy changes from the end of one track to the start of the next. Songs and artists played recently are still deprioritized according to the Smart Shuffle settings. No new analysis is started for this, and tracks without analysis are neither preferred nor penalized. Smart Fades still decides how the actual transition is mixed when the tracks play.

A setting is available to enable Autoplay by default on all queues. Each queue can still turn it on or off from the player controls, and Autoplay is always active when a dynamic playlist is playing. The Autoplay source setting has five options as follows:

• Automatic — similar tracks, falling back to your library (default). New tracks similar to what was recently played are requested from the music providers. If no provider is able to supply similar-track recommendations (for example, when only local files are used), an endless mix drawn from the library is used instead, so playback will not stop

• Similar to what you played. Tracks that resemble the most recently played items in the queue are fetched from the connected music providers and appended to the queue. This mode relies on a provider that offers similar-track recommendations; if none is available, no tracks are added

• Infinite mix from your library. Tracks are selected from the local library, with preference given to those that have been played the least. The selection is biased towards the genres of the items that were played most recently; when too few matching tracks are found, the mix is topped up with random tracks from across the whole library.

• Tracks from a playlist. Tracks are taken from the playlist chosen in the Autoplay playlist box, which appears when this option is selected

• Similar artists. When the queue runs out, a similar artist of the last track’s artist is added, one with no track in the queue yet. It is queued the same way as playing that artist. With an album order in Order to play an artist in, all its albums play whole, one after the other, if shuffle is off. Autoplay does not change the queue’s shuffle. If no similar artist is left, no tracks are added. This option needs a music provider that supplies similar artists

Crossfade can be enabled or disabled by default on all queues via a setting here and also can be turned on and off via the button at the top of the Now Playing view. Which crossfade mode will be enabled can be set here on a global level but can be overridden on a per player basis as well. Smart crossfade is the default. Smart Fades automatically analyzes each track’s tempo and beats to create seamless, musically aligned transitions between songs. It adjusts BPM, aligns downbeats, and applies EQ-based mixing for smoother fades—falling back to standard crossfade if analysis fails. Standard crossfade smoothly overlaps the end of one song with the start of the next using a simple volume fade. The Standard crossfade duration (default 8 seconds) appears when Standard crossfade is selected, and this is the only place it can be set.

Volume normalization (EBU-R128 based). Volume Normalization is enabled by default and works to eliminate volume differences between media items and sources. The method and target level are set in the Streams Queue Playback Settings

Streams

All settings in this section should be considered advanced and will not need to be adjusted in the majority of cases. Users with complicated network setups will find settings in this section that will be useful. If MA appears to be setup correctly but no playback occurs then check the settings in this section.

Queue Playback

Audio buffer size. Controls how much audio is buffered in memory. A larger buffer improves playback stability and seeking but uses more memory. The options are Maximum [default], Minimal and Balanced. The options are filtered depending upon system RAM. Minimal (60s buffer) is always available, Balanced (300s) requires a nominal 4 GB of RAM, and Maximum (1200s) requires a nominal 8 GB of RAM. If total memory can’t be determined then all three presets are offered although the default in that case is, conservatively, Minimal.

This section contains settings which affect the Volume Normalization functionality of MA. This functionality is enabled by default and settings are also available on an individual queue basis. There are two of these settings, one for tracks, one for radio, and you set them independently.

The best result comes from a loudness measurement of the audio. Tracks tagged with ReplayGain or R128 loudness values supply one directly, and Music Assistant uses those in preference to measuring anything itself. Everything else it measures on its own: your local library automatically in a nightly background scan, and anything played, including streaming services, while it plays, so those are covered from the second play onwards. The options differ mainly in what happens before a value exists:

• Fallback Dynamic (default) — use the measurement when there is one, otherwise adjust loudness on the fly. Always evens things out; the on-the-fly path is slightly less precise
• Fallback Fixed Gain — use the measurement when there is one, otherwise apply the fixed adjustment below
• Measurement Only — only adjust when a measurement exists. Anything not yet analysed plays at its original loudness
• Dynamic — always adjust on the fly, ignoring measurements
• Fixed Gain — never analyse; apply the same fixed adjustment to everything
• Disabled — leave loudness untouched

Once a measurement exists it is used, whichever of the two fallback options is selected. Two other things are worth knowing: live radio is rarely measured, so the radio setting in practice runs on whichever fallback you choose, and volume normalization also has to be switched on for the player itself. These settings control how it’s done, not whether. How the value is chosen, and when album gain is used instead of track gain, is covered on the Technical Information page.

Fixed/fallback gain adjustment for tracks / radio streams.

How much to raise or lower the volume, in dB, whenever the fixed-gain path is used. That’s either the Fixed Gain method, or Fallback Fixed Gain when no measurement is available. Negative values make things quieter. The range is −20 to +10 dB and the default is −6. Other methods ignore it. Again, separate values exist for tracks and radio.

• Advanced - Target level for volume normalisation. The loudness, in LUFS, that volume normalization aims for. The default is -14 LUFS and a value between -23 and -12 LUFS is recommended. See Technical Information
• Allow crossfade between tracks from the same album. Not enabled by default as it may not be desirable particularly for live albums

Source Selection

These settings decide which copy of a track plays when it is available from more than one source. Which Source Plays explains them with examples.

• Which source plays. The options are Best quality [default], Prefer local and Best quality for every track. With the first two, an album plays all of its tracks from one source, and a playlist or folder plays from the source it comes from. Prefer local plays from your local and self-hosted sources before streaming services
• Upgrade copies below. The options are Off [default], High-bitrate lossy, Lossless and Hi-res. When the copy that would play is below the chosen quality, a better copy of the track plays instead, when the track has one

Streamserver Advanced Settings

Generic

These settings are only visible when the advanced toggle is on.

• The Published IP address and TCP Port are normally populated automatically and set to auto. This is the address Music Assistant advertises to stream clients (including Sendspin) as the place to connect to for audio. It must be a literal IP address reachable by players on your local network, not a hostname, domain name, or URL. If there are issues with playback, confirm the IP address shown is reachable by the players on the local network. The port must be available.
• Bind to IP/interface. Use in complex network setups to start the streamserver on a specific interface

Audio Analysis Options

• Advanced - Smart Fades Log level. Specific log level for the Smart Fades mixer and analyzer
• Background analysis concurrency. Maximum number of tracks analysed concurrently during the nightly background scan. Default is 1 and should only be increased on more powerful systems

Webserver

Music Assistant URL

The card at the top of the page sets the addresses Music Assistant shares with devices and guests. It is always shown, whether or not advanced settings are on. Each switch can be changed back at any time, and what you typed is kept while the page is open.

• Internet. The address used from outside your local network, for links shared with guests such as party and quiz QR codes and, when it uses HTTPS, for casting dashboards. With remote access on, administrators see a Use remote access switch. When it is on, guests’ links open through remote access, and the card shows that link with a button to copy it. Switch it off to enter an External URL, for example the address of your reverse proxy. A set External URL always takes priority over remote access. When remote access is off, the card offers Set up remote access. Leave the External URL empty if your server isn’t reachable from the internet
• Local network. The address shared with devices and apps on your local network. Automatic is on by default and shows the address Music Assistant detected, with a button to copy it. Leave it on unless you have a reason not to. Switch it off to enter an Internal URL when the detected address does not work for your devices, for example behind a reverse proxy, with a custom hostname or on a server connected to more than one network. Enter the full address including the port, such as https://music.example.com:443. The TCP Port setting below is separate and still applies, as it’s the port Music Assistant itself listens on, which behind a proxy is usually not the port in your Internal URL

Options

• Server Name. The name of this Music Assistant instance, shown in the UI and announced on the network. Useful when you run more than one server. Clear the field to restore the default name
• Allow User Self-Registration. Allows users to create accounts by logging in with Home Assistant. Only appears when the Home Assistant plugin is added in Music Assistant, since the login goes through your HA instance

The settings below are advanced and only appear when advanced settings are enabled in the UI

• TCP Port. The port the webserver runs on (default 8095). If you change it, and you set the Internal URL manually, change the port there as well
• Enable SSL/TLS. Serves the web UI and API over HTTPS. When enabled, two additional fields are revealed for the SSL Certificate and SSL Private Key. Both must be PEM format, and you can either paste the file contents or enter an absolute path (e.g. /ssl/fullchain.pem). RSA and ECDSA are both supported and the private key must be unencrypted. Use the Verify SSL Certificate button to check the certificate and key are valid and match. If the certificate can’t be loaded, the webserver keeps running unencrypted and shows a warning
• Advanced-Bind to IP/Interface. Start the webserver on this specific interface. The default 0.0.0.0 binds to all interfaces (IPv4 and IPv6). Change this only in setups such as binding to a docker-internal network behind a reverse proxy

Storage

This opens the Storage page, which lists the folders, drives and network shares that Local files sources can use. Only administrators see it.

Diagnostics

This opens a view where the 150 line tail of the Music Assistant log can be seen and the diagnostics report or full log can be downloaded.

Background Tasks

This opens a view where the completed and upcoming background tasks can be seen. This is where the sync interval for the automatically generated playlists is set. Any failures will be clearly indicated and log snippets can be inspected. Detailed information is obtained by clicking on a task. There is a ⋮ menu on the right which allows for:

• Viewing the task details
• Editing the task schedule. Frequency can be Hourly, Daily or Weekly. A precise time can be specified for the task for Daily and Weekly frequencies
• Running of the task now
• Disabling the schedule

Administrators can see all tasks on the server whereas Users can only see tasks created by them (e.g. playlist creation).

Genre Management

Administrators can access the Genre Management page from the settings menu. This page provides tools for maintaining the genre database. The Genres page describes these tools and the rest of the genre system in full.

Genre Library Administration

Displays statistics about the genres in the library. Genres can be excluded from use via the ⋮ menu

Restore Missing Defaults

Checks for any built-in default genres that are missing from your library and restores them. This does not affect any existing genres or their mappings.

Full Restore

A destructive operation that completely rebuilds the genre database from defaults. This removes all custom genres and restores the full set of built-in genres.

CAUTION

Full restore deletes all custom genres, aliases, and media mappings. This action requires a two-step confirmation to prevent accidental data loss.

Audio Analysis

Administrators can access the Audio Analysis page from the settings menu. This page allows examination of the progress of the installed audio analysis providers, namely Loudness Analysis, Smart Fades, Sonic Analysis and AcoustID Lookup. The stale number is the number of tracks that need to be re-analysed due to a version change. There is also a section which shows failures and the reason for the failure. Each line can be individually deleted to unblock the file and allow it to be rescanned.