Navidrome

Navidrome is optional. Aurral can browse and play indexed media in the app without Navidrome when the canonical file is readable. Aurral also creates and updates Navidrome playlists through the Subsonic API when Navidrome is configured. Navidrome must be able to read and scan the Aurral download tree for that destination.

This is a filesystem connection as well as an API connection. A successful Test connection only proves that Aurral can reach the Navidrome API.

Aurral also exposes an authenticated Subsonic server at /rest/*.view. It supports XML and JSON browsing, canonical artist/album/song search, artwork, direct streaming with byte ranges, and user-scoped favorites through getStarred, star, and unstar. Completed flow entries and accessible shared-playlist entries are exposed as read-only playlist items through getPlaylists and getPlaylist; the endpoint does not create or update playlists, transcode audio, or write to the canonical library. Navidrome remains optional for clients that connect directly to Aurral.

Connect a Subsonic client

Point the client at the Aurral URL and use the Aurral account from onboarding. Aurral enables browser Subsonic clients on /rest without an additional CORS setting. Feishin can connect with its default token authentication when you use that configured account. Feishin can also use password authentication when you set LEGACY_AUTHENTICATION=true in Feishin’s environment, not Aurral’s. When Feishin locks server settings, also set SERVER_LOCK=true in Feishin’s environment.

Use the Aurral URL as the Feishin server URL. Set the server type to Subsonic. Feishin then shows canonical tracks, flow playlists, and shared playlists that the account can access. A playlist entry remains playable while its canonical file is readable.

The native Subsonic responses include playlist artwork through getPlaylists, getPlaylist, and getCoverArt. They also expose genres from canonical artist, album, and track metadata through artist, album, song, and getGenres responses. The native path does not fetch metadata from a provider while browsing.

Submit play history

Aurral reports scrobble.view submissions from Subsonic clients as local play events. The endpoint accepts repeated id and time parameters and follows the Subsonic submission flag. A successful submission records local history before Aurral delivers the play to any configured scrobbling provider.

Aurral exposes scrobblingEnabled=true from getuser.view. This reports that the server supports the scrobble endpoint. It does not require a provider connection.

The built-in Aurral player records completed library tracks through the same local play-event path. Aurral keeps local history when Last.fm, ListenBrainz, or Koito is unavailable.

Navidrome-compatible scrobbling

Open Settings > Playback > Scrobbling to connect Last.fm or ListenBrainz. Aurral copies Navidrome’s provider flows directly, so a Navidrome connection is not required for scrobbling.

Aurral uses the Last.fm API key and API secret from Settings > Connect > Last.fm. It validates ListenBrainz tokens directly. Completed plays are submitted from Aurral to the selected provider.

Navidrome remains an independent playback and playlist destination.

See Filesystem and mounts for the complete 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

Mount the same media root in Aurral and Navidrome at the same container path.
Set Aurral’s Settings > Download Clients > Downloads Folder > Path to a folder under that path, for example /data/downloads/aurral.
Make sure Navidrome can read both /data/music and /data/downloads/aurral if you want to play reused Lidarr tracks as well as new Aurral downloads.
Open Settings > Playback > Navidrome in Aurral.
Enter the Navidrome URL, username, and password. Select Test connection, then save.
Run a flow or update a playlist so Aurral can create or update the Aurral Playlists library and request a Navidrome scan.

Aurral creates the Aurral Playlists library at:

/data/downloads/aurral/aurral-weekly-flow

You do not normally need to create this library manually in Navidrome. The library can be empty until a track finishes downloading. Wait for the scan after the first completed track.

Navidrome must have permission to manage libraries through its API. If Aurral cannot create the library, use Settings > System > Storage Health for the exact path and error, then check the Navidrome account permissions and mount.

Existing Lidarr library

Aurral does not copy your Lidarr library into the Aurral playlist folder. If a playlist reuses tracks that already exist in Lidarr, Navidrome must also scan the Lidarr root folder, such as /data/music.

Add /data/music as a normal Navidrome music library if it is not already present. The automatically managed Aurral Playlists library is for Aurral’s generated download tree.

Filesystem paths

Aurral uses the Subsonic API for playlists, so it does not have a Navidrome playlist path-mapping setting. The automatically managed Aurral Playlists library must use the same absolute path in Aurral and Navidrome. Mount the shared download tree at matching paths in both applications.

Reused Lidarr tracks do not need matching path strings because Aurral resolves indexed songs by metadata. For generated tracks, Aurral first uses the exact indexed Navidrome path to get the Navidrome song ID, then uses metadata search only when the path is not available. Navidrome still needs its own library for those files. Use a separate Remote Path Mapping only when Aurral cannot read a path reported by Lidarr or a download client.

API playlists and scans

Aurral stores the Navidrome playlist ID for each flow or shared playlist. Names are only display values, so a rename updates the same Navidrome playlist.

Aurral also uploads its generated playlist artwork to API playlists and updates it when you change or regenerate artwork in Aurral. Aurral revalidates its local artwork response after restart, so the image stays current in the Aurral UI. Navidrome uses that uploaded image instead of its automatic tiled artwork when custom playlist artwork is supported.

If a new track is not indexed, Aurral publishes the indexed tracks and adds the missing track during the next scan catch-up. If no tracks are indexed yet, it keeps a temporary M3U fallback until Navidrome can resolve at least one track. Navidrome scans the Aurral Playlists library, not only your main Lidarr library. If the library appears but has no tracks:

confirm that a track exists under aurral-weekly-flow;
confirm that the Navidrome library path points to that folder;
run a Navidrome scan or save the Aurral Navidrome settings;
wait for the scan to finish.

Upgrade from M3U playlists

Aurral adopts a matching Navidrome playlist that was imported from an old M3U file. It keeps the native playlist ID, updates its ordered tracks through the API, and then removes the legacy file. It also removes obsolete duplicate names.

If the old file is already gone, Aurral can recover the imported playlist from Navidrome’s import comment during its next playlist publish. It also rejects an imported playlist whose comment belongs to a different Aurral playlist.

If migration does not finish:

Keep the existing Navidrome playlist and M3U file.
Make sure that Navidrome has indexed every track.
Run a full Navidrome scan.
Edit and save the Aurral playlist to retry migration.
Confirm that the same Navidrome playlist updates and the legacy file disappears.

To roll back, stop Aurral and deploy the previous exact image. Restore the previous Aurral data and legacy playlist files from the same backup. Do not delete or rename the Navidrome playlist before recovery completes.

Remove missing tracks

For Weekly Flow, set this Navidrome environment variable:

ND_SCANNER_PURGEMISSING=always

This removes old flow entries after a flow changes.

For Plex and Plexamp, see Plex.