Navidrome and Subsonic

Navidrome is optional. Aurral can browse and play indexed media in the built-in player when the canonical file is readable. Aurral also exposes its own authenticated Subsonic service for compatible clients.

Connect Navidrome when you want Navidrome’s server, scanner, or ecosystem. Aurral 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, and song search, artwork, direct streaming with byte ranges, user-scoped favorites, and playlist changes through createPlaylist, updatePlaylist, and deletePlaylist. Flow entries and accessible shared-playlist entries are available through getPlaylists and getPlaylist. Navidrome remains optional for clients that connect directly to Aurral.

When a Subsonic client adds a Flow or shared-playlist entry to a playlist, Aurral stores a reference to one canonical library acquisition job. The acquisition runs in the background. Multiple playlists that add the same track share that job. Removing a playlist entry removes only that playlist reference. It does not delete the canonical media file.

Favoriting a Flow or shared-playlist entry uses the same canonical acquisition by default. To keep the favorite without acquiring the track, turn off Favorite Flow tracks in Settings > System > Subsonic. This setting does not change favorites for tracks that already exist in the canonical Library.

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.

Scrobbling without Navidrome

Open Settings > Playback > Scrobbling to connect Last.fm or ListenBrainz. Aurral submits provider events 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. Aurral’s built-in player and native Subsonic clients use the same local play history.

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 the Downloads Folder root:

/data/downloads/aurral

Flow files live under _flows, which is visible to Navidrome scanners.

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 > 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 their exact recording MBID. Generated tracks use the exact indexed Navidrome filepath or recording MBID; Aurral does not substitute a title match. 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 Navidrome is unavailable during a playlist update, Aurral keeps the stored playlist ID and queues the snapshot for its existing catch-up attempts.

If a new track is not indexed, Aurral leaves it out until Navidrome scans it; it never substitutes a same-title track from another artist. Navidrome scans the Aurral Playlists library, not only your main Lidarr library. If the library appears but has no tracks:

confirm that a permanent track exists under the Downloads Folder or a flow track exists under _flows;
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.

Remove missing tracks

For Navidrome, set this environment variable if you want it to remove old files:

ND_SCANNER_PURGEMISSING=always

This removes any missing Navidrome files, including flow entries, after a scan.

For Plex and Plexamp, see Plex.