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.
# homebrew (recommended)
brew install radiosilence/koan/koan
# 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-cliSingle 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 dbuskoan 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 TUIspace 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
koanLocal and remote tracks merge into one library. Local files take playback priority; remote tracks stream with progressive download.
- 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, favourite sync
- 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 mcpexposes 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
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.
| 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 |
| 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 |
| 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 |
File -> Symphonia -> f32 samples -> rtrb ring buffer -> CoreAudio/cpal callback -> DAC
Four crates: koan-core (audio engine, player, database, indexer), koan-tui (Ratatui TUI, visualizers, media keys), koan-server (GraphQL, Subsonic REST, MCP), and koan-cli (the koan binary). See ARCHITECTURE.md for the full technical manual.
- 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)
just check # test + clippy
just fmt # cargo fmt
just cli # cargo run -p koan-cli -- <args>See CONTRIBUTING.md for guidelines.
MIT