Koan Server

A music player for people who give a shit about audio quality.

Pure Rust, Ratatui TUI. Bit-perfect playback, gapless transitions, fast library indexing, Subsonic/Navidrome integration, fb2k-style format strings. No Electron. No subscriptions. No bullshit.

Install

Downloading Koan.dmg from the releases page rather than using the cask? The app is signed but not notarised — Apple charges for that — so macOS refuses the first open and offers only "Move to Trash". Drag it to Applications and run xattr -dr com.apple.quarantine /Applications/kōan.app once. The cask does this for you.

# homebrew (recommended)
brew install radiosilence/koan/koan

# the macOS app (optional — same engine, native UI)
brew install --cask radiosilence/koan/koan-app

# pre-built binary via mise
mise use -g github:radiosilence/koan@latest

# or via cargo
cargo install koan-cli

# or build from source
git clone https://github.com/radiosilence/koan.git && cd koan
cargo install --path crates/koan-cli

Single binary. macOS works out of the box (CoreAudio). Linux needs ALSA dev headers:

# Debian/Ubuntu
sudo apt install libasound2-dev libdbus-1-dev

# Fedora
sudo dnf install alsa-lib-devel dbus-devel

# Arch
sudo pacman -S alsa-lib dbus

30-second quickstart

koan config init                            # create config dir + commented template
# edit ~/.config/koan/config.local.toml:
#   [library]
#   folders = ["/path/to/your/music"]
koan scan                                   # index your library
koan                                        # launch the TUI

space to pause, </> to skip, p to pick tracks, a for albums, q to quit. That's it.

Remote server? If you run Navidrome or Subsonic:

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

Local and remote tracks merge into one library. Local files take playback priority; remote tracks stream with progressive download.

What it does

• Bit-perfect playback -- CoreAudio AUHAL / ALSA via cpal, automatic sample rate switching, no resampling
• Gapless transitions -- decode thread keeps the ring buffer alive across track boundaries
• Format support -- FLAC, MP3, AAC, Vorbis, Opus, ALAC, ADPCM, WAV/AIFF/CAF, Ogg, MKV/WebM, MP4
• Full-screen TUI -- transport bar with album art, album-grouped queue, fuzzy picker, library browser, track info modal, visualizer, lyrics panel, mouse support
• Authentication -- Ed25519 JWT tokens, three roles (admin/user/readonly), 1Password CLI integration
• Subsonic/Navidrome -- incremental sync, unified local+remote browsing, streaming playback, two-way favourite sync for tracks, albums and artists
• Radio mode -- infinite play using Subsonic similarity, cached artist relationships, and genre matching
• ReplayGain -- track and album modes with peak limiting and configurable pre-amp
• Format strings -- fb2k-compatible %field%, [conditionals], $functions() for display and file organization
• File organization -- rename/reorganize your library from inside the TUI using format string patterns
• GraphQL API -- full programmatic control alongside the TUI, or headless. Relay pagination, rich filters, mutations for everything
• MCP server -- koan mcp exposes the player to Claude Desktop via Model Context Protocol
• Queue management -- undo/redo (100-deep), multi-select, drag-reorder, Finder drag & drop, session persistence
• SQLite FTS5 search -- full-text search across your entire library
• Media keys -- macOS Control Center integration (play/pause, next/prev, now playing info)
• Lyrics -- synced (LRC) and plain lyrics from LRCLIB, current line highlighting
• 22 visualizer modes -- spectrum bars, oscilloscope, radial, particles, lissajous, spectrogram, stereo waveform, VU meter, flame, plasma, tunnel, wireframe, metaballs, starfield, terrain, moiré, kaleidoscope, julia fractal, spiral, interference, wormhole, matrix rain. Picker with live preview (v), matrix overlay (X), bass shake (S), configurable reactivity

How it compares

No TUI player combines bit-perfect audio, Subsonic streaming, album art, fb2k-style format strings, and file organization in one binary. Most either need a daemon, lack remote support, or skip the audiophile bits.

TUI / terminal players

	koan	ncmpcpp	cmus	musikcube	termusic	rmpc	stmp
Language	Rust	C++	C	C++	Rust	Rust	Go
Standalone	Yes	No (MPD)	Yes	Yes	Yes	No (MPD)	No (Subsonic)
Bit-perfect	Yes	Via MPD	Via ALSA	No	No	Via MPD	No
Gapless	Yes	Yes	Yes	Yes	Yes	Yes	No
Subsonic/Navidrome	Yes	No	No	No	No	No	Yes
Local library	Yes	Via MPD	Yes	Yes	Yes	Via MPD	No
Local + remote unified	Yes	--	--	--	--	--	--
Album art	Halfblock	Kitty	No	No	Kitty/Sixel	Kitty/Sixel	No
ReplayGain	Yes	Via MPD	Yes	Yes	No	Via MPD	No
fb2k format strings	55+ functions	Column fmt	Basic	No	No	Basic	No
File organization	Yes	No	No	No	No	No	No
FTS search	SQLite FTS5	MPD search	Filter	Text	Filter	MPD search	Basic
Queue undo/redo	100-deep	No	No	No	No	No	No
Mouse support	Full	Yes	Yes	Basic	Yes	Yes	No
Media keys	macOS CC	Via MPRIS	Via MPRIS	--	Via MPRIS	Via MPRIS	--
Drag & drop	Finder -> TUI	No	No	No	No	No	No
Lyrics	Synced + plain	Via MPD	No	Plugin	No	Via MPD	No
Visualizer	22 modes	No	No	No	No	No	No
Favourites	Yes (syncs)	Via MPD	No	Yes	No	Via MPD	Yes
Streaming playback	Yes (256KB)	Via MPD	No	No	No	Via MPD	Yes
API / MCP	GraphQL + MCP	MPD protocol	No	No	No	MPD protocol	No
Tag editing	Soon	Via MPD	No	Yes	Yes	Via MPD	No
DSP / EQ	Soon	Via MPD	Yes	Yes	No	Via MPD	No
Auth	JWT + roles	No	No	No	No	No	No
Platforms	macOS, Linux	Linux/macOS	Linux/macOS/BSD	Linux/macOS/Win	Linux/macOS/Win	Linux/macOS	Linux/macOS
Maintained	Yes	Yes	Yes (2.12.0)	Slowing	Yes	Very active	Stale

Desktop players (GUI)

	koan	foobar2000	Strawberry	DeaDBeeF
Type	TUI	GUI	GUI (Qt)	GUI (GTK)
Bit-perfect	Yes	Yes (WASAPI/ASIO)	Yes (Linux)	Yes (ALSA)
Gapless	Yes	Yes	Yes	Yes
Subsonic	Built-in	Plugin	Built-in	No
ReplayGain	Track + album	Scan + apply	Yes	Scan + apply
Format strings	fb2k-compat	The original	Organizer only	fb2k-like
File organization	Yes	Yes (component)	Yes	No
Queue undo/redo	100-deep	Partial	No	Yes
Lyrics	Synced + plain	Plugin	No	Plugin
Visualizer	22 modes	Plugin	No	Plugin
Tag editing	Soon	Yes	Yes	Yes
DSP / EQ	Soon	Yes (VST)	Yes	Yes
Platforms	macOS, Linux	Windows/macOS	All	All

Documentation

Guide	What it covers
Getting Started	First-time setup, local and remote libraries, your first session
Authentication	JWT auth, user management, 1Password integration, recovery
Radio Mode	Infinite play, similarity scoring, tuning discovery
Remote Servers	Navidrome/Subsonic setup, sync, streaming, cache management
File Organization	Rename and reorganize your library from the TUI
GraphQL API	Headless operation, queries, mutations, daemon mode
MCP Integration	Claude Desktop setup, example prompts
Headless Server	Running koan as a background music server
Configuration	All config fields, layered config, env var overrides
Keybindings	Every key in every mode
CLI Reference	All commands, flags, and shell completions
Format Strings	fb2k-compatible template syntax and all 55+ functions
Troubleshooting	Common issues and fixes
Cache Management	Download cache, eviction, disk usage

Architecture

File -> Symphonia -> f32 samples -> rtrb ring buffer -> CoreAudio/cpal callback -> DAC

Five crates: koan-core (audio engine, player, database, indexer), koan-tui (Ratatui TUI, visualizers, media keys), koan-server (GraphQL, Subsonic REST, MCP), koan-ffi (uniffi bindings for native clients), and koan-cli (the koan binary). See ARCHITECTURE.md for the full technical manual.

macOS app

A native SwiftUI front-end lives in apps/macos. It links koan-core directly through koan-ffi rather than talking to koan serve — the app is sitting on top of the audio engine, so round-tripping HTTP to reach it would buy nothing and cost a daemon, a port, and an auth surface. Playback stays bit-perfect because CoreAudio output never leaves Rust.

GraphQL remains the surface for clients that genuinely can't link the core: the web SPA, iOS, and jukebox-style remotes.

It shares one library and one config with the CLI and TUI, so a queue saved in one shows up in the others. Visualizers are deliberately absent — that is what the TUI is for.

just macos-run     # build and launch
just macos-dmg     # package for release

Requires Swift 6 and macOS 14+.

Coming soon

• DSP pipeline -- EQ, headphone correction profiles, crossfeed (plan)
• Tag editing -- inline editing, bulk operations, vimv-style external editor (plan)
• Artist metadata -- bios, images, similar artists from MusicBrainz/Last.fm (plan)

Dev

just check    # test + clippy
just fmt      # cargo fmt
just cli      # cargo run -p koan-cli -- <args>
just macos-run # build + launch the macOS app

See CONTRIBUTING.md for guidelines.

License

MIT