Skip to content
kōan
Contents

Start

Server

Library

Playback

Automation

Reference

Protocol

Getting started

kōan plays a music folder on this machine, a server's library, or both merged into one. Which piece to install depends on where the music is:

The desktop app

On a Mac, download Koan.dmg or install with Homebrew:

brew install --cask radiosilence/tap/koan-app

On Linux, each release carries an AppImage and a .deb. See The desktop app.

The first launch opens a setup guide that asks where your music is and sets up the rest from there; Settings → Library opens it again. Everything it sets is in Settings too: Library adds folders and scans them, Server signs in to a kōan, Navidrome or Subsonic server, or shares the computer's own library with your phone. On a Mac it needs macOS 26 or later. It shares its config and library with the terminal UI.

An output device can take a while to open: a DAC waking from sleep, or the Mac's audio system busy. kōan goes on taking commands meanwhile, so a seek, pause or skip applies once the device is ready, and after two seconds a line across the top of the window says which device it is waiting for. Retry asks the device again. Cancel plays on the system's default output until another device is chosen, or stops if the default is the one that will not open. The desktop app and the iOS app do the same.

The iOS app

The iOS app plays from a server; a phone has no music folder to scan. It is in public beta on TestFlight until it is on the App Store, or can be built from source onto a phone plugged into a Mac with just ios-phone, signed with your own Apple developer team. Sign in under Settings → Server, or open an invite link from the server's admin. It needs iOS 26 or later.

Sample rates on iOS

The Mac switches the output device to each track's sample rate, so playback is bit-perfect. On iOS koan asks the audio session for each track's rate, and the route decides. A USB DAC (USB-C, or Lightning with the Camera Adapter) that supports the track's rate is switched to it, so there is no resampling in koan or iOS. The built-in speaker stays at its own rate, Apple's headphone adapters go to 48 kHz at most, and iOS resamples anything they do not take. Bluetooth is lossy (AAC, or SBC on other headphones) and never bit-perfect, and AirPlay carries 16-bit/44.1 kHz Apple Lossless.

The format badge shows the rate the hardware runs at, read back from the session, so a route that did not take the track's rate shows as a conversion. The Apple TV app does the same; over HDMI the rate is the one the television or receiver negotiates.

The Android app

The Android app plays from a server, as the iOS app does, and needs Android 10 or later on a 64-bit ARM phone. It is installed from an APK until it is on Google Play; see Android for where to get one.

The Apple TV app

The Apple TV app is in the same TestFlight beta as the iOS app and needs tvOS 26. It is most easily signed in from a phone or Mac that already is, or with a code a browser approves, though it also takes a password or API key typed with the remote; see Apple TV.

History and Recently played

The apps keep what you play. History lists every play by day, and is where a play is forgotten. Recently Played, beside it in the desktop app's sidebar and a phone's Library tab, answers "what was that record I had on yesterday": the records, artists and tracks of the last 30 days, each once however often it played, newest first. Both follow each play as it is recorded.

Recently Played and Favourites show the first few of each kind. Each section's heading gives how many there are in all and opens the Albums, Artists or Tracks browser filtered to the shelf, in the shelf's order; the filter shows in the browser's filter control and is cleared there. Search's sections do the same.

On the Mac, Tracks, beside Albums and Artists, lists every track in the library with the same filters; the iOS and Apple TV apps reach the track listing only filtered, from a "See all", since the whole library as one list is more than a phone or a television should draw and queue at once. On Apple TV the Albums, Artists, History and Playlists pages narrow by name from a field above the listing, as the other apps' filter fields do.

Artist pages

An artist's page holds the records they are the album artist of, and below them, under Features on, the records someone else is the album artist of that they are credited on: compilations, splits, guest spots. The page's Play, Shuffle and Queue act on the artist's own records only, and Play on an artist elsewhere in the apps and the terminal UI (a row, a menu) plays the same.

Features on has its own smaller Play and Queue for those records, so everything they appear on is their records queued and then the features. Records picked with Select can come from both sections. An artist with no records of their own has only Features on, and the page's Play plays the tracks credited to them.

The artist's own records are grouped by release type under Albums, EPs & Singles, Live, Compilations and Other releases, and each record's tile names its type in the top left corner (EP, Single, Live, Remix EP). The type is the MusicBrainz release group type: the RELEASETYPE tag Picard writes (MusicBrainz Album Type in MP3 and MP4 files), or the releaseTypes an OpenSubsonic server sends. The page's Play plays the sections in that order, and each section runs by date. A record is dated by its original release where a file says when that was (ORIGINALDATE, TDOR) or a server sends originalReleaseDate, so a reissue sits where the record does in a discography rather than at its reissue year. A record's type is the one most of its tracks are tagged with. A record with no type is listed as an album, so a library tagged without it reads as one list with no headings, and plain albums carry no label.

Collaborations

A record credited to several artists ("Orchestre Tout Puissant Marcel Duchamp × Frànçois & the Atlas Mountains") is listed under each of them when its tags name them one by one: the ARTISTS and ALBUMARTISTS tags and the MusicBrainz artist ids that Picard and sift write, or the artists and albumArtists an OpenSubsonic server sends. The record keeps its credit as it reads, and the credit itself is no longer listed as an artist.

In the apps and the web UI each artist's name within the credit links to that artist, with the text joining them plain; where the credit spells a name differently from its tag, the artists are listed separated by commas instead.

kōan does not split credits that are only a single string, because "&", "," and " x " also occur inside band names; retag them instead.

After upgrading, the next scan reads every file's tags again and the next sync walks the whole server, so a library already indexed picks these tags up without a rescan by hand.

Downloaded and offline

Downloaded, in the desktop app's sidebar and a phone's Library tab, is a shelf like Favourites: the artists, records and tracks with files on this device, records fully there first, each with a bar along the foot of its sleeve showing how much of it is. On the Mac every record in the library folder is whole.

On iOS and Android, when the server cannot be reached for a few seconds while the app is open, kōan goes offline: every list, from Albums and search to Favourites and playlists, shows only what is on the device, the queue greys out tracks that are not, and the Library tab (on an iPad, the sidebar) says so. It goes back online by itself when the server answers again. Settings → Offline mode turns it on by hand, for a train with a signal that comes and goes. A server without kōan's link (Navidrome) gives no signal for this, so there only the switch applies.

The terminal UI

mise use -g github:radiosilence/koan@latest   # or: brew install radiosilence/tap/koan
                                              # or: cargo install koan-cli

Linux needs the ALSA and D-Bus headers to build: libasound2-dev libdbus-1-dev on Debian and Ubuntu, alsa-lib-devel dbus-devel on Fedora, alsa-lib dbus on Arch.

koan config init   # creates ~/.config/koan/ with a commented config.toml

Add your music to ~/.config/koan/config.local.toml:

[library]
folders = ["/path/to/your/music"]

Then index it and start the player:

koan scan
koan

Or sign in to a server instead of, or as well as, scanning:

koan remote login https://music.example.com alice
koan remote sync

In the apps, Settings → Server has a Try the demo server action, also offered by a signed-out phone's empty queue, which signs in to kōan's public demonstration library, reset daily.

Playing

The terminal UI has pages, as the apps do: 1 the queue, 2 Now playing, 3 Albums, 4 Artists, 5 Favourites, 6 Recent, 7 History, 8 Playlists, 9 Settings and 0 Search, also reached from the sidebar.

On the queue, p picks tracks, a albums and r artists; in the picker, Enter adds to the queue, Ctrl+Enter adds and plays, and Ctrl+R replaces the queue. space plays and pauses, < and > skip, , and . seek, and Ctrl+Z undoes a queue edit.

? lists every key; The terminal UI describes the pages and Keybindings lists the keys.

koan play also takes paths: koan play ~/Music/some-album/.

Shell completions

Completions read the library, so koan play --album <TAB> lists your albums:

source <(COMPLETE=zsh koan)    # zsh; bash and fish take COMPLETE=bash and COMPLETE=fish

Removed files

A scan removes tracks whose files have gone, along with their play history. It refuses when the pattern looks like a missing mount rather than a deletion: a folder with no audio files, a path it cannot read, or more than 20% of a folder of at least 100 tracks gone at once. koan scan --force-remove lifts the last of these after a deliberate mass deletion. A file behind a symlink whose target has gone, such as an unmounted network share linked into the library, counts as unreachable rather than deleted.

A file moved or renamed outside kōan keeps its track, and with it its play history, favourites and playlist places, when the scan that finds it at the new path also finds it gone from the old one: it must be the same MusicBrainz recording, the same disc and number on the same release with the same size or length, or, untagged, the same size, length and modification time. When more than one missing file fits, none is taken, and the new file is indexed as a new track. A full scan matches moves between library folders too; the folder watcher matches them within one batch of changes.

On Linux, a file whose name is not valid UTF-8 is skipped with a warning, since its path cannot be stored as it is.

Local and remote together

A track present both locally and on a server is one entry in the library, matched on artist, album, disc, track number and title, or on MusicBrainz recording and release. The local file plays; the remote copy is the fallback when the drive is not mounted.