User Interface

Take a tour

A short tour points out the main parts of the app: the menu, search, the settings, your profile, the player bar, picking a player and grouping players. It is offered at the end of the setup wizard and of the welcome, and you can take it whenever you like by selecting your name at the bottom of the menu and choosing Take a tour. Stops for anything that is not on screen are skipped, so a phone shows fewer of them.

Main Menu

This menu’s appearance can be configured by clicking on the ⋮ in the bottom right and selecting Edit menu. Items can then be re-ordered, shown or hidden and section titles renamed.

In Settings → User Interface there are Display options which affect the UI. On a desktop, the menu can be placed vertically on the left or right or horizontally at the bottom (by selecting “Force mobile layout”). In the mobile layout, Menu, Discover, Search, and Players will be seen.

Sidebar Shortcuts

Use shortcuts to pin frequently used library items to the main menu for quick access.

• Add a shortcut from an item’s context menu (⋮ menu, right click, or long press) by selecting Add to shortcuts.
• Remove it from the same menu with Remove from shortcuts.
• Shortcuts are stored per user account.
• If a pinned item is updated (for example renamed), the shortcut is updated automatically.
• If a pinned item is deleted, it is removed from shortcuts automatically.

Settings

The settings open on a list of sections, shown as cards or as a list (switch with the icon at the top). Which sections are listed depends on your role:

• Music sources, Player providers, Metadata providers, Plugins and Audio analysis. The providers of each kind, and where more are added. Users whose role lets them have music sources see Music sources too, with their own sources and the ones shared with them
• Players. The settings of each player, and where group players are created
• Profile and User Interface. Your own account and how the app looks for you. Every user has these
• User management and Remote Access. For administrators
• System. The core server settings, and pages such as Storage, Diagnostics and Genre Management. For administrators
• About. Version information, credits and more

The settings pages all look alike. A header card names the page and has a Documentation button that opens the matching page here, followed by one Options card with all of the settings, grouped under headings. The Show advanced settings toggle in the header of the Options card reveals the settings most people never need, and the choice is remembered for your user.

At the bottom of the list, administrators find Run the setup wizard again, which also resumes a paused setup, and other users Show the welcome again.

Global Search

Searches can be done via any combination of words or partial words and also via a URL to a source such as https://open.spotify.com/album/0BwWUstDMUbgq2NYONRqlu

Search opens as a pop-up in the middle of the screen, from Search in the sidebar or with Ctrl+K. Below the search box is a row of chips to choose what is searched: All, Tracks, Artists, Albums, Playlists, Podcasts, Audiobooks, Radio, Genres and Pages. The Sources button limits which music sources are searched.

Results are shown as list rows, with up to 5 for each type and a Show more for each type to see the rest. Context sensitive menus are available for each. If the item desired is not found then narrow the search term.

Player Bar

The Audio Pipeline selectable label shows, via a colored icon and two letters, the sound quality of the audio output: LQ (Low Quality), SQ (Standard Quality), HQ (High Quality) or HR (Hi-Res). Select the label to see the full path the audio takes; what each quality level means is explained on the Audio Pipeline page. For groups, where the quality varies between players, the highest quality available will be indicated.

The overflow menu holds a number of useful options. Of note, for podcasts and audiobooks, there is a Change playback speed option which when selected will open a dialog with five preset speeds and a slider. The slider ranges from 0.5x to 2.0x and a preset is available for a boosted speed of 3.0x.

Now Playing View

This view will change depending on screen width. With wider displays you will be able to see the track that is playing (and associated information) as well as the queue. With narrow displays you need to use the toggle in the bottom right to switch between the currently playing information and the queue. Adjustments to the queue can be done with the ⋮ menu on the right. This view can be cast to a TV or display as a dashboard, using the TV icon at the top.

The Audio Pipeline selectable label is described above in the Player Bar section.

You can also access the Now Playing view directly via URL

The heart shows your own favorite state for the playing track: filled for a favorite, an outline for nothing, a thumbs-down for a dislike. Selecting it opens the same menu as everywhere else, to favorite or dislike the track or add it to a playlist. A change made from another view or device shows here straight away. See Favorites and dislikes.

When lyrics are available for the track being played then the LYRICS selectable label will be shown in white. Upon selection, the queue will be replaced by the lyrics which will be in sync with the music when timing information is available. Accurate lyric selection is contingent upon the metadata providers and may not be accurate for alternate versions of a song. Adjustment to the lyric timing is available in the ⋮ menu.

The Autoplay and Crossfade toggleable buttons allow quick access to the behaviour configured at the global level or for the particular queue. Individual queue settings are available in the ⋮ menu. Autoplay will be turned off and disabled if Repeat One or Repeat All is selected.

A sleep timer is also available in the ⋮ menu, which will stop playback after the selected period.

The contents of the ⋮ menu vary depending upon player and queue state. When a track is playing the full set of options are available and will look like:

Player List

NOTE

The volume shown against a player group is the MAXIMUM of the volumes of the child players. When the group volume is changed then each player is changed by a proportionate amount such that all speakers reach 0 when the group slider hits 0 and 100 when it hits 100. The relative balance between speakers is preserved such that returning the group slider to the original value will revert each child player to their original volumes

When a player group is powered on the members of that group will disappear from the player list and individual playback to those players will not be possible. In order to playback to an individual player, then either power off the group or remove the player from the group.

NOTE

The icon shown against each player (a Material Design Icon) can be changed in the player settings.

Grouping Players

There are four ways to group players

1. TEMPORARY SYNC GROUP. As shown in the Player List section players can be linked via the checkbox in the player list. Only like player types that support synced playback are allowed to be joined. These players will then play in sync. It should be noted that when players are grouped in this way only the main player holds the queue.
2. SYNC GROUP. Create a (permanent) group player from the players list in the settings; its members are then set on the player’s own settings page. In addition to playing in sync the group will also keep the queue on the group player instead of one of its child players.
3. UNIVERSAL GROUP. This allows grouping of dissimilar player provider types but carefully note the potential limitations on the linked page.
4. NATIVE GROUP. Use the native functionality to group players offered by some player provider types (e.g. Google Cast)

NOTE

If an attempt is made to power on a group and a member of that group is already a member of another powered on group then an error will be shown.

NOTE

If a player is taken over by another app, MA will not have knowledge of that, and the group may no longer function correctly. Additionally, if a player of a sync group tries to join late (e.g. it was unpowered) it will not be synced to the group.

Play Button

The play button is used as a shortcut to play the various items in the UI. It is shown on hover for non-mobile devices or is always in view for mobile devices.

Clicking/touching the Play Button will either execute the default play action for the item or show the play menu. To ensure the user doesn’t accidentally play on the wrong player, the play menu will show:

• the first time the MA view is entered; or
• if the player is not playing (or paused)

NOTE

If there is ever uncertainty as to whether the item will immediately start playing use a right click or long press to bring up the menu.

Multi Select

After you choose Select multiple items, a bar floats at the bottom of the screen reading N selected · Select all · Actions · ✕. Select all selects all of the items in the view (or section of the view as appropriate), Actions opens the menu of what can be done with the selection, and ✕ ends the selection. For large lists a confirmation dialog will appear, as selecting thousands of items can cause unresponsiveness depending on the resources of the host.

CTRL-A will also select all items unless the search box is in view in which case it will select all text in that box. Also CTRL-A won’t work on views that have multiple sections (e.g. the artist view has albums and tracks) so Select multiple items must be used in that case.

Shift-Click is also available to select a range of items.

Track Menu

In any of the following views, Right click or long press on a track to get the following menus

The View … endless mix option will only be seen if there is a music source that supports it. The wording follows what you selected, so it reads track, album or artist. It populates the queue with tracks based on that selection. The tracks are selected by the source not MA.

Every item menu, for tracks, albums, artists, playlists and other items, has a Dislike entry between Add to favourites and Add to playlist…. See Favorites and dislikes for what a dislike does.

View - Discover

The Discover view provides quick access to different media types and recommendations. Recommendation rows load independently, so content appears one row at a time as it becomes available. Each enabled music source can supply its own rows.

Select the pencil icon in the top right to enter edit mode. From there, show or hide rows and drag them into your preferred order. Some specialized or slower-loading rows are hidden by default to keep Discover fast; enable them in edit mode if you want to use them. Select Leave edit mode to return to the normal view.

Refer to the Library Recommendations Plugin for information about the available recommendations rows that are built into Music Assistant.

View - Artist / Album / Track

The Album, Track and Playlist list views look similar to the above except there is no album artist filter option and the track view has an ADD VIA URL option. Opening a single artist, album, track or playlist shows its detail page instead, with a large header (image, title, play button, Shuffle and endless mix) and, for albums and playlists, the tracks in a table below. The ⋮ menu on artist, album, track and playlist pages has Edit rows, which lets you choose which sections the page shows and in what order. Playlists have a Create new playlist on option as well as a Import playlist option which allows the manual importation of plain text M3U and M3U8 playlist files.

A blue dot on any icon (e.g. search icon ) indicates that the viewed results are subject to filtering.

The source filter option will only show when there are two or more music sources installed that support the media type being viewed. Multiple sources can be selected as part of the filter.

Items in all views can be “right-clicked” or “long-pressed” to bring up an extensive menu of options which is the same as that accessed by the ⋮ menu on the right. In the image above the complete list of possibilities is shown and this will vary slightly depending on the current view.

Multiple selections of albums / artists / tracks is possible with Select multiple items. Once one or more items are selected then selecting Actions in the bar at the bottom

will bring up this menu

The behavior described above will work on any view where the N selected bar appears.

View - Playlist

The top of the playlist page shows the artwork, the number of tracks and the total length in hours and minutes, with the play and shuffle buttons and the ⋮ menu. On a phone, a small bar with the back button, favorite and menu stays at the top of the screen once you scroll down.

On wider screens the tracks are shown as a table with the columns #, Title, Album, Year, Source and the duration. The column picker icon at the end of the table header shows or hides Album, Track number, Year, BPM, Key and Source, and the choice is saved for your user. BPM and Key are off by default, because only tracks that have been through audio analysis, such as Smart Fades, have them. The key is shown in Camelot notation (for example 8A), in its colour on the Camelot wheel. Columns drop out as the window narrows, and the column menu shows which ones are hidden at the current width. The artist and album names link to their pages.

The tracks can be sorted from the toolbar, including by date added, and the play button plays them in the order shown. Below the tracks a Featured artists row lists the artists with the most tracks in the playlist. Like other rows, it can be hidden or moved in Edit rows.

The playlist ⋮ menu also has Migrate playlist, which copies the playlist to another music source and matches its tracks there. Choose the destination, a name for the new playlist and how strictly tracks are matched: Exact release, Same recording (the same recording from a different release is accepted) or Best effort (the closest available match). With the first two, tracks that cannot be matched are skipped.

View - Individual Artist

From the top, the artist page has:

• A large header image with the artist name and biography, a Play on this device split button (the arrow picks another player or play option), Shuffle and Artist endless mix, and chips for the artist’s genres and sources
• Top tracks, a numbered grid. The All sources chip chooses which source the top tracks come from, and a link opens the artist’s tracks in your library
• Albums and Singles & EPs, both from your library
• Discography, the artist’s releases according to MusicBrainz
• Similar artists
• Source details and Images, collapsible cards at the bottom of the page

Expanding the IMAGES section (only visible to users with the Administrators role) allows for the selection of Thumb, Fanart or Logo. The other types shown are not used in the UI at this time. If there are no or limited images shown or the Images section is missing then go to the ⋮ menu in the top right of the view and select UPDATE METADATA. Right click on an image to make it the primary to be used. (Similar functionality is also available in the album view for Thumb)

Source Details

The SOURCE DETAILS section (read only for other than users with the Administrator role) shows what music sources are linked to the artist (albums and tracks have a similar section) across the available sources. It is normal to have multiple entries here if an artist has aliases or there are variant spellings, use of punctuation, etc. Thus there may be many entries showing matching links within a music source and across music sources. Cross linking across and within music sources occurs when the item is added to the MA library and can be triggered by using the icon. Adding a new music source does not trigger linking across existing library items.

When an item is available from several sources, Music Assistant picks which one plays. See Which Source Plays for how that choice is made.

The creation of links within the MA library to other identical items in the MA library (within or across sources) can occur when an item is added to the MA library. Links will be made automatically if internal matching logic is satisfied.

Incorrect mappings can be removed via the delete option in the ⋮ menu. For local files incorrect links may occur if the source file isn’t comprehensively tagged.

The ID shown against the streaming source may be used in automations and scripts and is obtainable by pressing the ⋮ icon on the right. Also in this menu, for streaming sources, is an external link which opens the page for the item on the source provider.

View - Individual Track

The header has the Play on this device split button, Track endless mix and a quality badge such as FLAC 16/44.1. The in-library icon can be clicked to copy the track’s URI to the clipboard. The favourite heart is at the top right, next to the ⋮ menu. A Lyrics section appears when lyrics are available for the track.

NOTE

The SOURCE DETAILS section in this view also has the functionality to play a short sample of the track on the local device. Any indicated sample rate and bit depth are as reported by the source and may differ during playback if transcoding is done before the audio data reaches MA.

View - Audiobooks

The audiobooks view shows available audiobooks in your library.

1. Tabs for audiobooks, authors and narrators. These tabs are only shown if at least one of your configured music sources supports syncing of authors and/ or narrators to the Music Assistant library. Otherwise there is only the plain audiobooks view without tabs.
2. Collapse collections: If the music source supports syncing collections (e.g. audiobook series) to Music Assistant, using “Collapse collections” minimizes these collections to single items.

View - Audiobooks Collection & Author/ Narrator details

The collection subview shows audiobooks in a collection. The items are sorted in the order given by the music source. When you play a collection, it will always enqueue the first not fully played item.

The author & narrator subview shows audiobooks belonging to the given artist. For library items it is possible to collapse collections.

View - Radio

The Radio view shows streaming radio stations that are available in the MA library. Stations can be added to the library in the following ways:

• Add item from URL - A URL for a streaming radio station (e.g. self-hosted Icecast stations) can be added to the library by selecting Add item from URL from the menu in the top right of the Radio view. When filtering by source, they will be shown as provided by “Music Assistant”.

• Music sources that support Radio items will have those items shown here when they are added to the library

View - Browse

Entering the Browse view will present a list of the installed Music Sources that have a browse capability. Selecting one of those will show a relevant list of the items from that source that can be browsed.

When viewing a source which has a native library then only what is in that library will be seen. For the local sources and other sources that do not have a native library, you will see all items available from the source. For local sources, if a folder is visited that is not already in the MA Library it will be automatically added even if it has been previously removed.

CAUTION

Be careful once browsing within the source as selecting PLAY on a folder will play everything in that folder and all subfolders. Attempting to play thousands of tracks may consume an excessive amount of system resources on the host and cause MA to crash or become unresponsive.