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.

Connect Navidrome when you want to use Navidrome’s server, scanner, or apps. Aurral then publishes its playlists to Navidrome through the Subsonic API. Navidrome must be able to read and scan the Downloads Folder.

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 for each user
• 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. Timed lyrics include millisecond timestamps. getLyrics returns the same text when the artist and title identify one Library track. Aurral does not query external lyrics services.

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.

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 > System > Subsonic. 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 > Playback > Scrobbling. Aurral sends plays to these services itself, so Navidrome is not required.

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

Publish playlists to Navidrome

See Filesystem and mounts for the full layout. The recommended Docker setup mounts 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. Set Settings > Download clients > Downloads Folder > Path to a folder under that path, for example /data/downloads/aurral.
3. To play reused Lidarr tracks as well as Aurral downloads, make sure that Navidrome can read /data/music and /data/downloads/aurral.
4. Open Settings > Playback > Navidrome.
5. Enter the Server URL, Username, and Password, then select Test connection.
6. Run a flow or change a playlist. Aurral then creates the Aurral Playlists library and asks Navidrome to scan it.

Test connection proves only that Aurral can reach the Navidrome API. It does not prove that Navidrome can read the files.

Aurral creates the Aurral Playlists library at the Downloads Folder, for example /data/downloads/aurral. Flow files under _flows are part of this library.

You do not need to create this library in Navidrome yourself. It stays empty until the first track finishes downloading. Wait for the scan after that.

The Navidrome account must have permission to manage libraries through the API. If Aurral cannot create the library, open Settings > Storage health for the exact path and error. Then check the Navidrome account permissions and the mount.

Existing Lidarr library

Aurral does not copy the Lidarr library into the Downloads Folder. If a playlist reuses tracks from Lidarr, Navidrome must also scan the Lidarr root folder, such as /data/music.

If Navidrome does not have /data/music yet, add it as a normal music library. The Aurral Playlists library holds only Aurral’s files.

Playlist names

By default, Aurral names each Navidrome playlist username - playlist name. To use the bare playlist name, turn off Prefix playlist names with the owner username in Settings > Playback > Navidrome. Single-user servers often turn it off.

Aurral stores the Navidrome playlist ID for each flow and static playlist. When you rename a playlist, Aurral renames the same Navidrome playlist.

Aurral makes a new Navidrome playlist public. Later syncs change its name and tracks but not its visibility. If you make a playlist private in Navidrome, it stays private. The configured Navidrome account owns all Aurral playlists.

Aurral uploads its playlist artwork to Navidrome and updates it when you change or regenerate the artwork. Navidrome shows this image instead of its own tiled artwork, if your Navidrome version supports custom playlist artwork.

Filesystem paths

Mount the Downloads Folder at the same path in both containers when possible. If the paths differ, add a mapping in Settings > Download clients > Remote path mappings with Applies to set to Navidrome. Set Remote path to the folder inside Navidrome and Local path to the same folder inside Aurral.

Aurral finds each track in the Navidrome index by its exact file path or by its MusicBrainz recording ID. It never guesses by title. A reused Lidarr track can therefore use a different path in Navidrome, but Navidrome must still have a library for it.

Aurral uses the mapping to create or update the Navidrome library, find playlist tracks, and write fallback M3U files. Storage health and automatic cleanup also use the mapping. If reused Lidarr tracks have different paths in Navidrome, add a Navidrome mapping for that folder too. See Playback servers report a different path.

Scans and missing tracks

If Navidrome is unavailable during a playlist update, Aurral keeps the playlist ID and tries the update again later.

Aurral leaves a new track out of the playlist until Navidrome indexes it. It never adds a track with the same title by another artist instead. If the Aurral Playlists library appears but has no tracks:

1. Make sure that a track exists in the Downloads Folder, or a flow track exists under _flows.
2. Make sure that the Navidrome library path points to that folder.
3. Run a Navidrome scan, or save the Navidrome settings in Aurral.
4. Wait for the scan to finish.

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 Plexamp, see Plex.