Remote servers
kōan integrates with Navidrome, Subsonic, and any server with a Subsonic-compatible API. Remote tracks merge with your local library into one collection.
Setup
koan remote login https://music.example.com adminThis prompts for your password and saves credentials to config.local.toml (gitignored). Then sync your library:
koan remote syncA full sync lists songs a page at a time, about a hundred requests for fifty thousand tracks; between an iPhone and a kōan server that is about a second per 10,000 tracks. A server that does not answer an empty search3 query is walked an album at a time instead, which for a library that size takes minutes.
A device that cannot use its server says so across the top of every page in the iPhone, iPad and Apple TV apps: signed out of it, its sign-in refused (a revoked key or a changed password), or, signed in to a kōan server, its link down for more than a few seconds. Until then the server reports the device as unreachable and refuses commands sent to it. Offline mode turned on by hand shows no banner.
While the device cannot reach its server at all (no network, no route, the connection refused) or offline mode is on, playback moving on by itself passes over tracks whose files are not on the device and plays the next one that is, in every app and the terminal UI. A downloaded album plays from a cold launch with no network. A track you choose that is not on the device is not swapped for another: playback waits on it, says why, and plays it once the server answers. A server that answers with an error, such as a proxy's 503, is still reachable, and tracks still wait for their downloads.
Staying in sync
Every sync walks the whole library, which is what lets it notice a track the server deleted or gave a new id. The apps sync on their own, and only when the server's library has changed:
- A koan server tells every linked app when its library or a playlist changes, and queues the sync for an app that is away.
- Navidrome and other Subsonic servers are checked on a timer (
auto_sync_interval_mins). Each check asksgetIndexesfor the library'slastModifiedand syncs only if it moved since the last sync.
koan remote sync # sync nowSigning out stops a sync from that server where it is, including one waiting for another to finish, and any that starts before this device signs in to it again. What it wrote stays, and nothing is recorded as synced, so the next sync from that server walks the library again.
Changing servers
Signing out of a server removes everything this device held for it: its tracks, the account's favourites, ratings, play history and playlists, the queue, the downloads and the record of its syncs. The server keeps all of these and the next sign-in pulls them again. Tracks from local files, playlists read from files in the library folders, EQ profiles and this device's settings stay. Signing in as another account, or at another address, signs out of the last one first; signing in again as the same account at the same address keeps what is there.
How merging works
When you have both local files and a remote server, each file and each server entry is a source of its own, and a track holds at most one of each. A file and an entry are the same track when they match on one key, tried in order:
- Position on the release -- album, album artist, disc, track number and title, with the track artist as a tie-break
- The same position, whatever the artist -- only where there is a track number
- MusicBrainz ids -- recording on the same release, with the position as a tie-break
Names are compared case-insensitively and in one Unicode form. Where a position tier matches more than one track, the MusicBrainz recording decides; where that too names no single track, the match is declined rather than guessed, and the two stay separate tracks.
A track's names come whole from the file while it has one, so a server's tagging never mixes into a local track's. Playback priority:
- Local file -- always preferred (bit-perfect from disk)
- Cached download -- previously downloaded remote tracks
- Remote stream -- on-demand progressive download
Drive unplugged?
If a local drive is disconnected, tracks with remote backing are demoted to remote-only (streaming fallback) instead of deleted. When the drive comes back, the next koan scan re-merges them automatically.
Streaming playback
Remote tracks start playing after 256KB is buffered instead of waiting for the full download.
- Both front ends draw the fetched extent on the seek bar, weaker than the played one. It is a fraction of bytes on an axis of time, so it is right for lossless and CBR and drifts with the bitrate on VBR -- read it as whether playback is about to run out of track, not as a position
- The TUI also refuses a seek past the downloaded boundary
- Duration always shows the full track length
- When the download finishes, full metadata and cover art are re-read
Downloads happen in the background with configurable parallelism:
[remote]
download_workers = 5 # parallel download threads (default: 5)Cache management
Played tracks are kept, so they play again from disk, until the cache limit needs the room; with cache_limit = "0" they are deleted once the queue moves past them. See Cache management for size limits and eviction.
[remote]
cache_limit = "50GB" # max cache size; bounds queue prefetch too; "0" keeps no cache (default: unlimited)
download_ahead = 3 # tracks past the playing one to fetch (default: the whole queue, up to 250)
cache_dir = "/custom/path" # explicit cache dir (default: ~/.config/koan/cache)
preload_covers = true # fetch every record's cover ahead (default: on)Covers
A remote library has no files to read covers from, so each one is a request to the server. The apps ask for the size they draw: 600 pixels for grids, lists and headers on a phone or a computer, which a kōan server keeps ready; 1200 for a large screen (Now Playing and record headers on an iPad, an Apple TV, Android's full-screen player); the original only for the artwork viewer, which the server reads from the music file. A large cover shows the 600 one first and sharpens in place.
Every cover fetched is kept in the cache's artwork directory, so any page asking for it again reads it from disk, and with Fetch every record's cover ahead (Settings → Server, on by default) the apps fetch the rest in the background after a sync: one at a time, only while no cover a page asked for is waiting, and only while the app is in the foreground, on a network that is not metered, and not saving power. Its progress shows as an activity row with a stop button; stopping keeps what was fetched and carries on at the next launch or when the setting is turned on again. Kept covers count against cache_limit with the downloads. The preload stops short of the limit, and when the cache is over it covers are trimmed first, oldest first, since one is cheap to fetch again and a download is the music; with cache_limit = "0" nothing is fetched ahead. Records the server has no cover for are remembered, so the preload does not ask again. Covers are kept per server and removed at sign-out; clearing the cache removes them too.
Favourites and playlists
Favourites and playlists sync both ways. A change made in kōan is sent to the server at once; one made in another client arrives with the next sync, unfavouriting included. A favourite made here before its item was on the server, or before signing in, is sent to it rather than dropped. A favourite changed while the server cannot be reached waits on the device and is sent with the next sync, and the server's older list does not undo it in the meantime.
On a kōan server the order of the playlists syncs too: reordering them on one device reorders them on the account's other devices, and a playlist one device has that the server lacks keeps its place among the rest. Other servers have nowhere to keep the order, so there it stays on each device.
A playlist the server marks read-only, such as a smart playlist, comes down like any other and is never edited or pushed back.
A server playlist may name songs the library has not synced; they are kept in their places whenever kōan pushes the playlist back, so an edit here never deletes them there, and they appear in the playlist, in the server's order, with the first sync after the library gains them.
A playlist the server stops listing is deleted locally only once the server, asked for it directly, says it does not have it, so an empty or short listing from a server in trouble deletes nothing.
Play history
Each device records every track it starts, and scrobbles to the server the ones heard long enough to count as plays: half the track or four minutes, and nothing under thirty seconds, as Last.fm counts them. A scrobble that cannot be sent waits on the device and goes, dated to when the track started, once the server answers again.
Signed in to a kōan server, history is shared. The server keeps the account's plays, and each device's History shows the plays the account's other devices made alongside its own, arriving as they are scrobbled. A device's own skips stay on that device. Forgetting a play, or clearing history, forgets it on the server and on every device on the account, including plays recorded before history was shared. A Navidrome server keeps plays too, but has nothing to share them with, so each device shows only its own.
The play queue on the server
Off by default, Settings → Devices → Keep the queue on the server (on the Apple TV, Settings → Server) keeps this device's queue in the account's play queue on the server, where Subsonic clients such as Feishin or Symfonium save theirs. A queue started in another client can then be picked up in kōan, and the reverse. Between kōan devices it is not needed: Play on and Move here move the queue live.
Turning it on replaces this device's queue with the one the server holds, after asking; with nothing saved there, this device's queue is saved instead. While it is on, queue edits are saved a second after they stop, and a change of track, a pause, and the app going to the background save the queue with the playhead.
When kōan starts it takes the server's queue in place of its own only if another client saved one since this device did. Tracks only this device has are left out of what it saves, and a queue of more than 1,500 tracks is not saved, since the server cannot take one that long yet. Turning it off leaves both queues as they are. The setting is this device's own (remote.play_queue in config.local.toml).
Configuration reference
# config.local.toml
[remote]
enabled = true
url = "https://music.example.com"
username = "admin"
# password saved by `koan remote login`
# config.toml or config.local.toml
[remote]
download_workers = 5 # parallel download threads
cache_limit = "50GB" # max cache size (LRU eviction)
download_ahead = 3 # tracks fetched past the playing one
cache_dir = "/custom/path" # cache directory
preload_covers = true # fetch every record's cover aheadChecking status
koan remote statusShows the configured server URL, username, last sync time, and track counts.