Navidrome and Subsonic

Aurral has its own Subsonic server. Subsonic players such as Feishin and Music Assistant can connect to Aurral directly. Navidrome is optional.

To use Navidrome’s apps, point Navidrome at the Library folder. Navidrome scans the music and imports the playlist files that Aurral writes for every flow and static playlist. Aurral does not connect to Navidrome for this. To bring your Navidrome plays into Wrapped and recommendations, connect it in Settings > Listening.

Aurral’s Subsonic server

Aurral serves the Subsonic API at /rest, for example /rest/ping.view. It supports the OpenSubsonic extensions formPost, topSongsByArtistId, songLyrics, and transcodeOffset. The server offers:

• XML and JSON responses
• Browsing and search of Library artists, albums, and tracks
• Artwork, genres, and direct streaming with byte ranges
• Favorites and ratings for each user
• Artist photos, and biographies of artists Aurral has already looked up
• Playlists: createPlaylist, updatePlaylist, and deletePlaylist
• Flows and static playlists through getPlaylists and getPlaylist
• Play history through scrobble.view

Aurral answers from its own index. It does not ask a metadata service while a client browses. A playlist entry can play while its file is readable.

Subsonic clients can save a personal play queue with savePlayQueue and restore it with getPlayQueue, including the current track and position. Library tracks, flow tracks, and static playlist tracks keep their order. Tracks that are no longer available are omitted. Saving without any track IDs clears the queue. The web player keeps its own queue.

Subsonic stream can convert audio to MP3, Opus in an Ogg container, or AAC when a client requests format=mp3, format=opus, or format=aac. A lower maxBitRate converts to MP3 by default. timeOffset seeks in seconds when converting. format=raw, an unlimited request, or a bitrate limit above the source bitrate keeps the original file. download always sends the original file. Conversion requires ffmpeg, which is included in the Docker image.

getLyricsBySongId returns local lyrics from a .lrc sidecar next to the audio file, then embedded lyrics tags. When a track has neither, Aurral looks it up on LRCLIB, a free lyrics database, using the track’s artist, title, album, and length. Timed lyrics include millisecond timestamps. getLyrics returns the same text when the artist and title identify one Library track.

Connect a Subsonic client

Point the client at the Aurral URL, and sign in with any local Aurral account.

• Browser clients can use /rest without a CORS_ORIGIN setting.
• Feishin: set the server type to Subsonic. Feishin uses token authentication by default. To use password authentication, set LEGACY_AUTHENTICATION=true in Feishin’s environment. To lock the server settings, set SERVER_LOCK=true.
• Music Assistant: add Aurral as a Subsonic provider, and turn on its legacy authentication option. Music Assistant then signs in with the password.

Token authentication uses the account’s Aurral password. Before a token client can connect, these accounts need an extra step:

• An account created before Aurral stored Subsonic credentials. Sign in to Aurral once, or ask an admin to reset the password.
• An account created by a reverse proxy or by single sign-on. It has no local password until an admin sets one.

If token authentication fails, Aurral returns error 41 with a link to the API overview. Switch the client to password authentication, or set a local password.

Playlists and favorites from Subsonic clients

When a Subsonic client adds a flow track or static playlist track to a playlist, Aurral adds the track to the Library in the background. Several playlists that add the same track share one download. Removing a track from a playlist removes only that entry. It does not delete the file. A track the playlist downloaded itself stays in the Library.

Subsonic clients can edit static playlists but not flows. Editing a flow returns error 50. A client removes songs by their positions in the playlist it last loaded. If a position no longer exists, Aurral returns error 70 and changes nothing, so the client can reload the playlist and try again.

When a Subsonic client favorites a flow track, Aurral also adds it to the Library. To keep the favorite without adding the track, turn off Favorite flow tracks in Settings > Library. This setting does not affect tracks that are already in the Library.

Play history

Aurral records each scrobble.view call from a Subsonic client as a play. The endpoint accepts repeated id and time parameters and honors the submission flag. Aurral records the play in its own history first, then sends it to the scrobbling services that the user connected.

getUser.view reports scrobblingEnabled=true. This means that the server accepts scrobbles. It does not mean that the user connected a scrobbling service.

The built-in player records plays in the same way. Aurral keeps its own history when Last.fm, ListenBrainz, or Koito is down.

Scrobble without Navidrome

To connect Last.fm, ListenBrainz, or Koito, open Settings > Listening. Aurral sends plays to these services itself, so Navidrome is not required.

Aurral uses the Last.fm API key and secret from Settings > Discovery > Last.fm. It checks ListenBrainz tokens directly.

Use Navidrome with Aurral

See Filesystem and mounts for the full layout. Mount the same host media root at /data in Aurral and Navidrome:

# Aurral
volumes:
  - /srv/media:/data
  - ./config:/config

# Navidrome
volumes:
  - /srv/media:/data:ro

Setup

1. Mount the same media root in Aurral and Navidrome, at the same container path.
2. In Navidrome, add a library for the Library folder, for example /data/downloads/aurral.
3. If playlists use tracks from a read-only folder, such as /data/music, add that folder as a library too.

Navidrome watches its libraries and picks up new files on its own.

Playlists

Aurral writes an M3U file for each enabled flow and each static playlist to _playlists in the Library folder. Navidrome imports these files as playlists and updates a playlist when its file changes. Settings > Library > Playlist files shows the folder.

• Navidrome imports playlist files only while ND_AUTOIMPORTPLAYLISTS is on, which is the default.
• The files list each track by its full path in Aurral. Navidrome must see the Library folder and your read-only folders at the same paths.
• Navidrome gives imported playlists to its first admin user and keeps them private. To show a playlist to other users, make it public in Navidrome.
• When a playlist is deleted, renamed, or its flow is turned off, Aurral removes its file. Navidrome keeps the old playlist with no tracks. Delete it in Navidrome.

By default, each file name starts with the owner’s username, like test - Road Trip. To use the bare playlist name, turn off Owner in file names in Settings > Library > Playlist files. Playlists of different users that share a name keep the username.

Listening history

1. Open Settings > Listening > Navidrome.
2. Enter the Server URL, your Navidrome Username, and Password.
3. Select Connect Navidrome.

Aurral imports the plays of that Navidrome user, then checks for new plays every hour. Each Aurral user connects their own Navidrome account. Only admins can connect a server. Disconnect removes the plays that Aurral imported.

Plays from a Subsonic client connected to Aurral are already in Aurral’s history. Connect Navidrome for plays in Navidrome’s own apps.

Favorites

After you connect, select Import favorites to star the same artists, albums, and songs in Aurral. Aurral matches them by MusicBrainz ID, then by name, and tells you how many it couldn’t find in the Library. Select it again to add favorites you starred since. Imported favorites are your own, so they stay when you disconnect.

Bring a Navidrome playlist into Aurral

1. In Navidrome, open the playlist and select Export.
2. In Aurral, open Library > Playlists, open the create menu, and select Import playlist.
3. Select M3U and choose the exported file.

Aurral reads the artist and title of each track and downloads what the Library is missing.

Remove missing tracks

To make Navidrome remove files that no longer exist, set this variable in Navidrome’s environment:

ND_SCANNER_PURGEMISSING=always

After each scan, Navidrome then removes every missing file, including old flow tracks.

Caution

ND_SCANNER_PURGEMISSING=always affects all of Navidrome. It also removes the ratings, play counts, and playlist entries of missing files. Use it only when missing files will not come back.

For Plex and Jellyfin, see Plex and Jellyfin.