Changelog
Unreleased
Changed
- The search box goes to a track's record. Return or a click on a track in the kōan app's search box opens its record page instead of playing it, so searching never interrupts what is playing; ⌘Return, ⌥Return and ⇧⌘Return still play.
Fixed
- A Mac app opened from the disk image or from where it was downloaded says to move it to Applications. macOS runs such a copy read-only, so it cannot update itself; kōan said only that it could not write to its folder.
0.72.3
Fixed
- Offline playback no longer stalls. When the device cannot reach its server at all, or offline mode is on, playback moving on by itself passes over tracks that are not on the device and plays the next one that is, so a downloaded album plays from a cold launch with no network. A track you choose that is not on the device is waited for, with the reason shown, rather than swapped for another. A server answering with an error still counts as reachable.
- Downloads finish, and never pass for kept. A download you ask for is remembered until it arrives, across the app being suspended or closed, and what failed while the server was away is fetched again when it comes back. A waiting download is an empty ring, and while the server cannot be reached a track not on the device says so; the Downloads page counts what is not downloaded yet, and the banner says why nothing plays.
- A new playlist from "add to playlist" asks for its name at once. The question used to wait until the picked tracks were read, so a slow read looked like nothing happening. It now comes up as the sheet closes, counts the tracks as they are read, and holds "create" until they are. A failure reading the tracks, making the playlist or adding tracks to one is said over the window instead of only being logged.
0.72.2
Changed
- The iOS app is laid out for the iPad. A window at least 660 points wide gets the desktop's sidebar, the page, the lyrics beside it and the transport bar, inside the safe area and clear of the iPadOS window controls; Settings shows its sections beside the pane. Narrower windows in Split View or Stage Manager take the phone's layout, and the app keeps its place as a window is resized across the two. On a tablet's width record tiles fill their row and forms keep a readable measure. The iPhone stays portrait-only, and its layout is unchanged.
0.72.1
Changed
- The phone app moves where it snapped. Lists give past their ends and bounce; Now Playing grows out of the mini player's sleeve; held menus and artwork open out of the press; sheets slide back down; notices drop from the bar; queue rows close up when one goes and shift over for picking; a list sent back to its top arrives there. All of it is drawn by the GPU, and Reduce Motion makes it instant. The selection bar's verbs are icons over their words, so they fit along a phone.
Fixed
- Flings on the phone coast as far as a native list's. The speed at release was read from the last instant of the touch, which came out at 40–84% of what
UIScrollViewreports for the same finger; it is now read over the trailing window, as UIKit reads it. A long press also fires its haptic once. - Settings sections on a phone. A second section tapped while the first was sliding in stacked the two, and the screen stopped responding as each took Settings' one pane from the other. A section that is no longer offered now goes back to the list.
- Fixes from an audit before the App Store release. A device on the local network could crash the app with a deeply nested Apple TV pairing frame, fill the disk through the log, or queue commands without end; each is now bounded. Lowering the wash's drift late in a long run, a lyric line with an impossible time, and a tap on a queue row that had just gone no longer crash the app. A seek the decoder refuses no longer skips the track, Opus files play at the gain their header sets, the iPhone app again holds back cover preloading on cellular and in Low Data Mode and reconnects when the network changes, and it saves the session when it goes to the background. On a server, a transcoded stream sought while every transcoder is busy is refused where it used to restart from the beginning, and
/auth/refreshtakes its token from the request body only.
Internal
- App Store submissions wait for screenshots.
push.py --submitwaits up to fifteen minutes while App Store Connect processes a new set.
0.72.0
Security
- rmcp 3.9. The MCP client no longer buffers an unbounded response body from a server (RUSTSEC-2026-0462).
Changed
- Licence. kōan moves from MIT to AGPL-3.0-or-later, with an additional permission for app store distribution. Releases up to 0.71.4 remain under MIT.
- A shorter koan.rocks. The homepage now leads with kōan as one player across server, desktop, phone, TV and terminal, and with the GPUI apps, and says what recent releases added; setup detail moves to the documentation. The compare page loses padding and its kōan cells follow the desktop app onto Linux.
- Fewer snaps on the phone. The mini player fades to a new sleeve and new names, and tapping the tab showing slides the page away to the tab's root.
- A search hit on a track plays it. In the desktop app's search box and on a phone's shelves, choosing a track plays it with the tracks listed after it, where it used to open the record with the row selected.
- The iOS app is now the GPUI app. It updates the SwiftUI app in place under the same bundle id, keeping the library, sign-in and downloads; view preferences such as sort order start again.
- koan.rocks leads with the GPUI apps. The homepage presents kōan as your player, server, remote and EQ on every device, with current screenshots, and the compare page and guides drop what described the SwiftUI Mac app.
Fixed
- Sheets on a phone stay on screen with Reduce Motion. A sheet taller than the room above the keyboard now scrolls its body with motion off, as it already did with motion on.
- Read-only playlists on the phone. The phone's playlists page listed only those a pick can be added to, so smart playlists and a server's read-only ones were missing.
- Live Activities are back on the iPhone. While the phone controls another device, the lock screen and Dynamic Island show what is playing there, with working skip and play-pause buttons, kept up to date through the push relay.
- The iOS app is easier to try and to sign in to. A signed-out app offers the demo server without typing, password fields use the secure keyboard and Password AutoFill, an invite or pairing link that launches the app answers in its one window, EQ import questions appear from any tab, and the EQ page can import files.
- The iPhone app recovers from interruptions and follows the system again. Music comes back after Siri on AirPods or a call iOS never ends, the lock screen's scrubber stops when playback stops or waits on a download, Control Center has shuffle and repeat, a refused audio start says to tap to play, and a second shared EQ file in one session is imported at once.
Internal
- The GUI smoke runs no longer gate merges or releases. They still run and report; a slow or stuck run no longer holds up
Checks. - The App Store listing describes the GPUI app. Review notes no longer mention an iPad sidebar, and the description no longer claims a Live Activity.
0.71.4
Fixed
- Even frost, a centred playing track and centred sheets. In the kōan GUI app the bars a page scrolls under blur evenly from their first pixel instead of in visible steps; the queue's follow button brings the playing track to the middle of what shows, clear of the bars; sheets sit in the middle of a desktop window at up to 80% of its height and fill a phone's screen; and selection mode's playlist action opens the add-to-playlist sheet.
- The transport keeps its ground. The desktop transport is tinted with the page's ground again while content runs under it; only the toolbar blurs without darkening.
0.71.3
Changed
- Lyrics lines answer the pointer. On the desktop, the line under the pointer brightens, since a click on it seeks there.
- The lyrics panel resizes. Drag its left edge to widen or narrow it, as the sidebar's edge does; a double click restores it, and the width is kept with the window's.
- Add to playlist is a sheet. Every playlist that takes tracks, with its sleeve and size and a filter as you type, in place of a submenu that thousands of playlists or a finger could not use.
- Rules, the selected row and the frosted bars take the wash's colour. Hairlines and a picked row's ground in the kōan GUI app are translucent white in dark (black in light) instead of opaque grey, and the bars a page scrolls under blur what passes beneath without darkening it.
Fixed
- The lyrics panel fills its width. On the desktop, the hairline under its title spans the whole panel, and "nothing playing" and "no lyrics found" sit in the middle of it at any width, rather than above it.
- Submenus open on a tap on iOS. A submenu row had no tap of its own and opened only under a resting pointer, which touch no longer counts, so tapping it did nothing.
- EQ sheets on a phone scroll and fit the screen. Manage EQ, the correction and EQ pickers and the AutoEQ and measurement flows ran off the bottom of the screen without scrolling in the GPUI app on iOS; they are now screens over the whole window, on the record's wash, their content inside the safe area and scrolling. The EQ editor uses the whole screen rather than sitting low with a wide margin above it. Every kōan sheet on a phone keeps to the safe area on all edges.
- The EQ editor keeps its frame rate on phones. Each mark of a chart draws over only the part of the plot it can reach, rather than the whole plot, so the EQ graph costs about a tenth of what it did per frame; the EQ page shows the wash behind it, and a band's figures take a tap across a finger's height.
- Stopping a server ends its links. An embedded server waits for its link sessions to close before it stops, so a device it was serving is no longer left listed as linked.
- Albums show the format their files are now in. An album whose files were replaced in another format, such as MP3 by FLAC, kept its old format in its header; it now follows its tracks, and the next sync puts existing albums right.
- Smooth at 4K and above. A frame of the desktop app costs half the GPU time it did at a 4K or 6K window: the wash works out its drift once a frame and its colour field once a record instead of at every pixel, and frosted bars and layers are composed only where they draw. Full screen on a 4K display holds 120 fps.
- Empty states fit small areas. In a narrow column or the lyrics beside a small window, the empty state draws itself smaller, down to half size, and is clipped past that rather than drawn over the sidebar.
- The wash at 6K holds 120 fps. Its colour is worked out once per record, appearance and tint rather than at every pixel, so full screen on a 4K panel at its sharpest scaled size keeps up with a 120 Hz display.
0.71.2
Changed
- The kōan GUI app's pages run under its toolbar and transport. On the desktop the page column's toolbar and the transport are drawn over the page, which scrolls under them, and every page's heading scrolls away with it rather than standing over a hard edge. Those bars, and the phone's, are clear while nothing is under them and frost (blur and tint, fading on the GPU) once content passes beneath; on the desktop the frost feathers into the page rather than ending at a line. The keyboard cursor is held clear of both bars.
- The EQ editor's graph makes room on a phone. A profile's graph folds to a quarter of its height once its bands scroll and opens again at the top, and folds away while the keyboard is up so the field being edited stays in view; the EQ screen's graph no longer leaves a gutter wider than its labels.
- The phone's moving parts run on the GPU. A page pushed or swiped back, the tab bar's rule, a queue row swiped and Now Playing pulled down are layers composed from keyframe tracks, so they keep the display's rate while the app is busy and draw no frames as they move.
- Every button answers a press. A button's glyph moves as its verb means: queue drops onto a line, share lifts, add pops, remove squeezes away, rescan turns, back steps back. Buttons without a glyph lift when pressed, and the sidebar's queue or playlist row glows when music is sent to it.
Fixed
- Every press answers. Chips and pop-up pickers lift their ground when pressed, and a track row's play mark rings, so no press in the app goes unanswered while the music it asked for is on its way.
- Every header press answers. A record or artist page's play lifts and its shuffle crosses its arrows when pressed, on the phone as on the desktop; the phone's record heart pops as hearts do elsewhere. The phone's mini player sits on a solid ground under a hairline playhead; only the bar at the top is frosted.
- Sync progress reads as one task. The GUI app shows a sync under one title with the phase beneath the bar and the counts beside the title, as the iOS app does; the row no longer blanks for a frame as a sync ends, and the phone card drops its border.
Internal
- A chart component in koan-kit, with the EQ graph built on it. Axes, lines, areas, rules, draggable points and a wrapping legend, drawn by the GPU from keyframes: a series easing between data sets, an axis rescaling and a point settling cost no frame, and samples arriving at their own rate are drawn at the display's, interpolated a sample behind or extrapolated to the present. The EQ's response graph draws the core's curves through it unchanged, its y labels' column as wide as its labels.
0.71.1
Changed
- EQ lives in Settings. The desktop app's EQ is Settings' EQ tab rather than a window of its own; Playback → EQ… (⌥⌘E) and the transport's EQ menus open it there. On a phone it is the Settings tab's EQ screen, laid out for the width: pickers under their labels, the graph and its legend fitted to the screen, and its sheets over the bar and foot.
- The window wears the page's colours. In the kōan GUI app, on the desktop and the phone, a record's page eases the wash and the accent to its sleeve, as the Apple apps do, and an artist's page to their photo when they have one; leaving the page eases back to the playing record's. Now Playing keeps the playing record's.
Internal
- The kōan GUI app on the iPhone. The GPUI app runs on iOS with a phone's shell: four tabs each with its own history, a mini player opening Now Playing, Settings and EQ as screens, the library's sections as the iOS app lists them, and touch throughout (a tap plays, a hold opens the row's menu, sliders and handles drag by finger, nested lists scroll on their own, native text editing). Not yet released on iOS.
- Settings smoke test follows the Server pane's choice cards. It chose the mode from the picker the cards replaced while nothing is chosen.
- kōan GPUI on a phone and TestFlight. The GPUI app builds for a phone as "kōan GPUI" (
cc.blit.koan.gpui) beside the SwiftUI app, and CI sends it to internal testers. On the phone it now follows the iOS app's shape: swipe from the edge to go back, words for tabs, a record's page that scrolls whole, dialogs that fit the screen, flings that coast in heavy lists, and the audio session's interruptions and route changes handled as the SwiftUI app handles them. - The web UI, share pages and koan.rocks take their theme from
@radiosilence/theme. The tokens move out ofsite/src/theme.cssinto a package radiosilence's other web pages share, installed from GitHub Packages before each stylesheet build. The pages gain awarncolour, and text at the control size now carries its own line height. - kōan GPUI feels like a phone. Text and targets at the iOS app's sizes and weights (the display and title faces one step lighter on the desktop too, as SwiftUI draws them), pages that slide in and swipe back with the page beneath showing, Now Playing sliding up over the page, sheets from the foot, headings that scroll with their page, repeated flicks that carry a long list, swipe to remove from the queue, haptics, and no queue replaced by a stray tap.
0.71.0
Added
- The desktop app asks to restart into an update. Once a new version is downloaded, kōan offers to restart now instead of waiting quietly for the next quit, and a copy Homebrew or
aptkeeps is pointed at the release notes. The first launch of a newer version says so. Updates and running in the background move to a new General pane, first in Settings. - The desktop app walks a new install through setting up. On a first launch with nothing set up, a guide explains what kōan is and asks where the music is: folders on this computer, which it can then share with your phone and other devices, with a checklist for reaching them through Tailscale away from home; or a server to sign in to. It ends with playback and the keys worth knowing. Settings → Library opens it again, beside Reset to Defaults, which stops sharing, signs out, forgets the folders' tracks and puts every setting back, keeping
config.tomlasconfig.toml.bak.
Changed
- Settings → Server asks before it shows a side. A device that neither connects to a server nor shares its library is offered the two as cards, as the setup guide does, with nothing chosen and no sign-in form until one is.
- Compressed web UI. The web UI's pages, page fragments and scripts are compressed with brotli, zstd or gzip, whichever the browser prefers; they were sent uncompressed. Audio served by byte range and the live scan and cache streams are left as they were.
Fixed
- Server settings switch back to signing in. Choosing Connects to a server after looking at Shares its library shows the sign-in form at once, rather than after leaving the pane.
- A queue holding the whole library no longer downloads all of it. Download ahead's whole queue now stops 250 tracks past the playing one and follows the cursor from there; Settings says so, and a larger number can be set by hand. With a cache limit, jumping to tracks not yet fetched makes room for them at once instead of filling the cache past its limit first.
- Sign In is enabled as the fields are filled. The Server pane redraws on each edit to the address, username and password, so Sign In no longer stays disabled until something else redraws it.
Internal
- An overlay fading out takes no input. The window takes clicks the moment a sheet, question or the command bar is put away, and Tab never lands in one that has gone.
- Crash tests for Settings and presenting.
just gui-settings-smokedrives Settings' sharing, invite and sign-in flows through its controls against a real engine, andjust gui-presentresizes, minimises, closes and switches key on presenting windows; CI runs both. - koan-kit runs on iOS, and is ready for touch. The storybook draws on an iPhone simulator through GPUI's iOS backend (
just kit-ios), reading iOS's motion, contrast, transparency and Dynamic Type settings; under touch, controls and rows are finger-sized, a held touch opens a context menu or, moved, lifts a drag, and content keeps clear of the status bar, home indicator and keyboard.
0.70.5
Added
- Artist pages open with their biography and photograph already there. A koan server now looks up its whole library's artists ahead of time, by MusicBrainz id, and serves the answers through
getArtistInfo2and the newkoanArtistInfoextension; the apps read them from the server instead of each asking MusicBrainz and Wikimedia, and a device with a library of its own looks its artists up in the background too, shown as a "looking up artists" row while it runs.
Changed
- Sheets come and go with motion. In the desktop app, sheets, questions and the command bar fade and rise in, briefly, so they read as arriving over the page; the command bar, the shortcuts, presented sheets and questions fade out as they go. At once under Reduce Motion.
- One Homebrew tap. Install from
radiosilence/tap, which holds every radiosilence formula and cask;brew updatemoves installs from the old per-project tap.
Fixed
- Hover highlights fade out. A highlight left as the pointer goes now visibly fades over 130 ms; the old curve lost most of it within two frames, so it looked like a cut.
- A toggle's tick is seen drawing in and erasing. It eases both ways instead of appearing whole within a few frames, and a box turned off keeps its fill until the tick has erased.
- The desktop app no longer crashes within seconds of launch on macOS 27. A window's display link now lets go of its layer before the window draws to it again.
Internal
- Kit tests ignore the host's accessibility settings. A machine asking for less motion no longer lands the transitions the rest tests catch in flight.
- Colour liveness per slot. A shader or window keeps presenting only while a colour slot it draws with moves, not while any slot in the app does, such as the accent settling.
- Linux build. The updater's macOS-only helpers no longer fail Linux's clippy as dead code.
- A question fading out runs its action once. Answering its still-drawn verb again, through a screen reader or the keyboard, no longer repeats a destructive action.
0.70.4
Added
- The desktop app updates itself. Installed from the DMG or as an AppImage, it downloads each new release, checks its digest and signature, and installs it when kōan quits;
updates.auto(Settings → Devices) turns it off. Homebrew and.debinstalls are told a new version is out.
0.70.3
Changed
- The SwiftUI sources are the iOS and Apple TV app's alone. The Mac app they also built, unreleased since 0.70, is removed with its shell, its AppKit views, its build recipes and its CI job; the sources move to
apps/ios, beside the Xcode project that builds them.
Fixed
- iOS playing bars move again. The analyser parked when the play head stalled for over a second, as it does while a streamed track starts or a seek waits for bytes, and nothing woke it once the music resumed; decoded audio arriving while a subscriber waits now wakes it.
- The server banner shows only when a server set up on this device cannot be used. It said "Signed out of your server" on a device that was signed out on purpose, never had a server, or was sharing its own library; every app now shows it only for a refused or missing sign-in, or a server out of reach.
- Every address Settings → Server shows copies on click. Only the address on your network did; the Tailscale name and the address invites carry, the tailnet's or Funnel's, now copy the same way.
- A sign-out cut short by quitting is finished at the next launch, and what you do meanwhile is kept. Signing out records that the server's library is still to be forgotten, and the next launch finishes the forgetting if the app quit, crashed or was suspended first. Hearts, plays, new playlists and session saves made while the forgetting runs now land after it, rather than being deleted with the server's.
- The invite QR code follows the invite address. Switching Invite phones to in the desktop app could leave the code and link showing the previous address; a new address now makes a new invite.
- Sharing follows Tailscale coming up and Funnel moving without being restarted, and says when Tailscale cannot carry invites. The shared library learned its Tailscale name and Funnel address only when sharing started, so one started while Tailscale was stopped refused every request through it. It now asks again when a request names a host it does not know. Settings → Server says, beside Invite phones to, when Tailscale is stopped or the tailnet does not allow Funnel.
- Share links work while the desktop app shares its own library, and are disabled where none can be made. The link was built on
server.url, which sharing never set, so every share failed. Funnel's or a custom address now lives inserver.url, the one public address that invites and share links both read; ashare.urlfrom an earlier version is moved there once at launch. Signed out of every server and not sharing, the share actions are disabled with the reason, which the engine reports asshare_links_unavailable. - Turning sharing off stays on the sharing settings. Unticking it in the desktop app's Settings → Server sent the pane to the sign-in form for another server.
- A sign-in that never reached the server says so. It said the server did not accept the credentials; it now says it could not reach the address tried, keeping the credentials message for a server that answered and refused.
Internal
- CI jobs named after their platforms. The Apple jobs are now macOS, iOS and tvOS; macOS builds and tests the workspace as Linux does.
0.70.2
Changed
- The Mac app is kōan.app. The desktop app installs as
kōan.app, its DMG volume named kōan, in place ofkōan desktop.app.
Fixed
- Commands from the desktop app reach the engine as they are made. Each joined the engine's ordered lane only when the main thread next polled it; now every command joins at the call, so none waits a turn and all keep the order they were made in.
- The desktop app no longer crashes shortly after opening on macOS. A synchronous draw could ask the window's layer for a drawable while the display link that held it was still letting go, which aborted the app; the draw now waits until the link has released the layer.
- Creating the sharing account no longer crashes the desktop app, and signing out shows at once. Making the account started sharing from inside the update that recorded it, which GPUI refuses; the callback now runs after that update ends. Signing out returns once the credentials are gone and forgets the server's library afterwards on a thread of its own, rather than waiting for a sync to stop and for the library's rows to be deleted; a sign-in that follows waits for the forgetting.
0.70.1
Fixed
- The desktop app's main thread sleeps while only its animations move, on macOS. The wash, the playing bars and the seek bar are presented from GPUI's display-link thread from the last frame drawn, rather than waking the main thread at every refresh while music plays.
0.70.0
Added
- Play on in the GUI app. The transport's devices menu controls another kōan device, the account's or one on the network, and moves the music between them, as the Mac app's Play on does; what became of a move shows at the foot of the sidebar.
- Playlist order syncs through a kōan server. Reordering the playlists on one device reorders them on the account's other devices, through the new
koanPlaylistOrderextension; playlists the server does not hold keep their places. - Search in the GUI app. The sidebar's field searches as you type, with a few suggestions of each kind under it and every result on a page of its own, and ⇧⌘K opens the picker for building a queue from several tracks, records and artists at once. Filter and search fields have a clear mark, and Escape empties them.
- Favourites, Recently played and Downloaded in the GUI app. Each shelf shows the first few artists, records and tracks on it with how many there are, and each section's heading opens the browser with the shelf as its filter, so the preview and the full listing always agree. Everything on a shelf can be picked together, dragged to the queue or a playlist, and acted on from its menu.
- Playlists in the GUI app. A playlist's page lays out like the queue, grouped by record or flat, and is edited as the Mac app's is: reorder by dragging, remove, add by dropping tracks, records or other playlists, rename, delete, undo and redo, each change previewed first; new playlists from the queue, a pick or a drop on the sidebar, and export to M3U8. Smart and read-only playlists are shown as such and never edited.
- Covers are fetched ahead. With a remote library, every record's cover is fetched in the background after what is on screen, kept with the downloads and counted against the cache limit, so browsing never waits for one. On by default (Settings → Server); its progress shows as an activity row with a stop button.
- Lyrics, track info and the artwork viewer in the GUI app. Lyrics show beside the page and follow the song, a click on a line seeking to it; Track Info lists what each of a track's sources says; and a click on a record's sleeve or the transport's cover shows it as large as the window allows.
- Downloads in the GUI app. A page of what is being fetched from the server and what finished or failed, with each transfer's rate and bar, the cache's size against its limit, and retry, cancel, remove and clear finished, each saying what it changes first. Cancel and retry are new to the engine (
cancel_downloads,retry_downloads), for every app to use. - Organise, invite and pairing links, and the server banner in the GUI app. Organise… on a track, record, artist or pick lists where every file would go as the pattern is typed, checks the plan against the disk once typing rests, and asks with the counts before moving anything. Invite and
koan.rocks/pair/links opened with the app go to Settings, which signs in or asks whether to sign the device in. While the server cannot be used, a line across the top of every page says why. - The GUI app's menus on Linux. Linux has no global menu bar, so the menus a Mac shows along the top of the screen open from a kōan button at the left of the toolbar, each item with its keys.
- Tooltips with keys, and a remote library's files from the GUI app's menus. Toolbar and transport buttons say what they do and the keys that do the same, as the Mac app's do; the library's and the queue's context menus download tracks to the cache now and remove downloaded copies, asking first, and the queue's menu organises its tracks.
- The desktop app's seek bar shows how much of a downloading track has arrived, and download rings fill smoothly. Both are drawn on the GPU from the transfer's progress, and lists no longer redraw while a track downloads.
- The kōan GUI app sets up waking an Apple TV from Play on, says when the system keeps it off the local network, and gains the Mac's tooltips in Play on and Settings; the line at the sidebar's foot opens the server settings.
- History in the kōan GUI app. Every play under its day, plays scrobbled by another client marked, forgetting and clearing behind previews. Organise saves a typed pattern under a name, and a record that is slow to read shows a spinner.
- Screen readers can read the kōan GUI app's controls. Every koan-kit component (buttons, switches, sliders, steppers, choices, menus, navigation, headings, progress and sheets) reports its role, name and state to VoiceOver and Orca, and answers a click or a step as the pointer or the arrow keys would.
- The kōan GUI app from the keyboard. Tab and Shift-Tab move between controls, F6 between the sidebar, the page and the transport; the sidebar, the track browser, a record's tracks and history move with the arrows, Home, End and Page Up and Down, play with Return and pick with Ctrl-Space, and the place the keyboard is on is outlined.
- Screen readers can read the kōan GUI app as pages. The sidebar, toolbar, page and transport are landmarks; a track, a record heading, an artist or an album tile reads as one line saying what it is, with its place in lists that draw only what is on screen, and the list scrolls as the reader moves down it. The playing track, notes at the sidebar's foot, banners and progress are announced as they change.
- The rest of the kōan GUI app from the keyboard. The album grid, an artist's records and the shelves move in two dimensions with the arrows, the artist browser, an artist's page, a playlist's page, the shelves, search results and downloads take the list keys, and the menu key or Shift-F10 opens the context menu of the row the keyboard is on.
- The kōan GUI app follows the system's display settings. Increase Contrast, or high contrast on GNOME, draws stronger text, thicker rules, an accent held to 7:1 and outlined selections; Reduce Transparency takes the wash away; GNOME's text scaling factor sets the starting text size, which the app's own setting multiplies; and the remaining animations stop under Reduce Motion. Each applies as the setting changes.
- The desktop app keeps running in the menu bar, and opens at login. With its window closed it stays reachable from your other devices, its menu bar item shows what is playing and brings the window back, and it can ask the system to start it when you log in.
- The GUI app's queue, library and sidebar menus match the Mac app's. The queue's context menu adds to a playlist, favourites, goes to the record and copies a share link, a heading's naming its record; every library menu copies a share link, saying how many tracks the server could not include; a playlist in the sidebar has its own menu to play, shuffle, rename, export or delete it; the Downloads row counts transfers while they run; and undo, redo, select and the selection bar's verbs say in their tooltips what they do and their keys.
- The wash's drift is yours to set. Settings → Appearance gains Drift (how fast the wash moves while music plays, from still to twice its pace) and Turn (how far it turns either way, up to 10°), in the desktop app's kōan theme.
- Controls with character. A heart pops when filled, throwing out a few particles, and deflates when emptied; play folds into pause and back; a skip nudges its way; shuffle's arrows cross and repeat spins round, its one popping in. Each runs once, drawn by the GPU, and stands still under Reduce Motion.
- Form controls answer too. A toggle's tick draws itself in and erases; copying turns the copy glyph into a tick and back; a segmented control's mark comes in from the side the last choice stood on; a stepper's value rolls the way it was stepped; a cleared filter's text fades out leftward. Each stands still under Reduce Motion.
- A menu's tick draws itself in, and a drop's line closes into the rows. Choosing in a menu draws the new choice's tick along its stroke as a toggle's is. Rows dropped into the queue take the insertion line into the first of them, the line closing from both ends as their ground lifts.
Changed
- Playing costs less CPU in the apps. The analyser measures loudness (momentary, short-term, true peak) only while something reads whole frames, as the terminal UI does; the playing bars read three bands and no longer pay for it.
- The kōan GUI app on macOS animates the playing bars, the seek bar and the wash on the GPU. Each is a shader quad whose values are read as the frame is presented, so the bars, the drift and the seek bar no longer redraw the window while playing, and the seek bar glides between playhead updates rather than stepping.
- The desktop app's transport on its own ground, balanced as the Mac's. It keeps its ground with the wash under the whole window, its controls and seek bar sit centred in a 64-point bar, and the trailing glyphs and the page header's play and shuffle glyphs are drawn at the Mac's sizes.
- The desktop app keeps its runtime files out of the configuration directory. Window and browse state, the desktop device's id, locks and temporary covers move to the platform's state, runtime and cache directories, keyed per configuration directory; files an earlier version left there are moved on first launch.
- Covers are fetched at the size they are drawn. The Apple apps ask for 600 px covers, which a kōan server keeps ready, instead of 1000 px ones it made on first request; iPad and Apple TV Now Playing and record headers take 1200 px and sharpen in place, Android's full-screen player and record header take 1200 px, and only the artwork viewer asks for the original.
- A download's ring on every GUI track row. The library's track rows, like the queue's, fill a ring as a track arrives, read at the display's rate only while the row is on screen.
- The desktop app's keyboard shortcuts sheet in the kōan look. It is drawn as the app's other sheets are, its keys in badges.
- The kōan GUI app on Linux draws its moving parts on the GPU too. The playing bars, the seek bar and the wash are shader quads in the wgpu renderer, so they no longer redraw the window while playing.
- The loading spinner, button and row fills, the running progress bar and the seek bar's corrections move on the GPU in the kōan GUI app. The ensō turns smoothly at any size with no frame drawn, and a playhead report that disagrees slightly with the seek bar is eased into rather than jumped to.
- The GUI app's menus, copies and Settings match the Mac app. Sort, filter and playlist menus tick a choice at the row's end as the Mac's menus do; every copy button and copyable value says "copied" for a moment after, Settings' app password included; Settings' sections space their headings and rows as the Mac's form does; and the pair-a-device code field spans the form.
- The kōan GUI app's artist page makes room for a photo that arrives late, and keeps the biography under "about" after the records. The photo's slot grows in and the name moves along with it, the photo and biography fade in, and a spinner stands where the biography will be while it is looked up, as on the Mac.
- The kōan GUI app makes the record wash on the GPU. A new record is reduced to a small field rather than baked, switching between light and dark or changing the theme tint no longer bakes the wash again, and the wash is dithered at the screen's own resolution, so it shows no bands at any size.
- The GUI app answers what you do. A heart filling sends out a few small dots and one emptying draws a ring closing in; the transport's buttons and every glyph button leave a faint ring as they are pressed; bordered buttons lift for a moment; a segmented choice, a field taking the keyboard and a sidebar row taking a drop draw a line under themselves. The sidebar and the lyrics panel slide in and out rather than snapping. Each lasts a quarter of a second at most, costs nothing at rest, and none plays under Reduce Motion.
- Artwork that is still loading shows the kōan ensō drawing itself, on the very mark a missing cover shows, and the picture fades in over it. Everywhere covers are drawn: the album grid, rows, record and artist pages, the transport and the queue.
- The playing bars and the spectrum show what you hear. They fall with the pause fade, rise with the resume, follow a sleep timer's fade and lie flat while muted, in every app and the terminal UI: the analyser now scales what it reads by the gain the output applied, on top of the ReplayGain and EQ it already saw.
- A record's sleeve says it opens the artwork. The cover on a record's page and in the transport show "show artwork" under the pointer.
- Icon-only buttons in the kōan GUI app say what they do. Removing a library folder, a person's menu, forgetting a device and waking an Apple TV are named in their tooltips, and koan-kit now makes a glyph-only button without one hard to write.
- The header's shuffle button says what it shuffles, and the queue's status marks say what they mean (played, downloads next, couldn't be played, waiting for its download), in their tooltips.
- The Konami code holds back B and A. Once its arrows are in, the B and A that finish it no longer run a hotkey; the arrows always move the list, as in ordinary use.
- Invite links ask in the kōan GUI app. Opening one asks whether to sign in as its account on its server, and what happens to the current sign-in, before anything changes; a link for the account already signed in says so and does nothing.
- Covers kept ahead arrive much faster. The cover preload fetches six covers at a time instead of one, and from a kōan server with the new
koanCoversextension takes the covers the server has ready two hundred to a request. - One search box in the GUI app. ⌘K,
/, ⇧⌘K and the sidebar's search field all open a search box centred over the window, which finds tracks, records and artists as you type and does everything from the keyboard: play or open the lit result, play it next, add it to the queue, tick several and act on them together, or open every result on a page of its own. It replaces the ⇧⌘K picker. just gui-runbuilds for a quick edit loop again. Dependencies are optimised once and kept, and the workspace's crates rebuild incrementally at a light optimisation with debug assertions and overflow checks on, where the profile was a release build in all but name. On Linux, where the app draws the window's decorations, a strip the toolbar's height sits above the sidebar to move the window by.- Motion in the kōan GUI app is keyframes the GPU interpolates. The playing bars glide between the analyser's frames instead of stepping, the seek bar and download rings move from their last report, the wash breathes, travels and turns through ±3° as the Mac's does, and controls light at once under the pointer and fade out over 130 ms as it leaves (their text, glyphs and edges through colours the GPU moves), sleeves fade in as they arrive, the downloads page's bars fill from each reading, all drawn at the display's refresh rate with no CPU work per frame and nothing drawn while nothing moves.
- Music sent from a menu is seen to arrive. In the desktop app, the sidebar's queue or playlist row draws a short line when a menu, the selection bar or a record's header sends music there. A favourite changed anywhere answers on every heart showing it, the album tile's included. Copied text and each new notice answer the same way.
- Fades, reveals and sliding panels move on the GPU. An artist's photo or biography arriving, the lyrics panel and the sidebar sliding in and out are drawn once and moved by the GPU, with no frames drawn while they move; the page beside a panel moves once rather than reflowing frame by frame.
- The seek bar's times follow the engine's clock. The engine wakes the time label at each whole second of playback; the app keeps no timer of its own, and nothing runs while paused or hidden.
- The desktop app's Settings strip zooms the window on a double click, as the main window's toolbar does. Internally, every page outside the EQ graph is now built from koan-kit's components.
- The launch icon follows Apple's template, and
just gui-runbuilds only what it links. The launch icon's shadow follows Apple's template, and its SVG carries the drawing rather than referring to another file. koan-ffi is a Rust library, so the desktop app's builds no longer also build it as a static and a dynamic library; the Apple and Android builds ask for theirs. - Motion in the desktop app follows written principles. Each answer moves on its own curve. Toggles and segments answer however they change. Rows added to or moved in the queue lift where they land, a skip streaks the way it goes, and a finished download rings on its mark.
- The accent turns with the wash. In the kōan GUI app a new record's accent moves over the wash's two-second dissolve, on the same curve and mixed in OKLab, and is drawn by the GPU with no frames from the app.
- The desktop app's lyrics move with the song. The column glides to each line as it is reached, the sung line eases into emphasis, past lines settle quieter than those to come, and the panel's edges fade. The GPU draws all of it, timed from the playhead.
- koan-runtime. The engine's facade moves out of koan-ffi into a crate of its own, which the desktop app links as plain Rust; koan-ffi is now only the Swift and Kotlin bindings over it, which are unchanged.
- The sidebar's search field opens the search box and shows its query. It was a text field whose suggestions could no longer appear, and which reopened the box whenever Tab landed on it; it is now a button over the query. The results page shows its usual previews while the search box is open, rather than the box's longer lists.
- Library and playlist syncs ask a server four things at a time, everywhere. The playlist pull fetches the next batch while it stores one, and a cancelled sync never counts an unconfirmed album as deleted.
- Syncs ask a server sixteen albums or playlists at a time. Measured against a koan server, that is three times faster than four; the per-album fallback no longer holds up a library scan.
- koan-kit draws its own text field. Fields are built on GPUI's input handler instead of gpui-kit's input: input methods compose in place, the caret and deletion follow whole characters and Unicode words, a screen reader reads and sets the value, and Organise's pattern field colours its fields and functions.
- koan-kit draws every component itself. The scrollbar, the panels controls open, the window root and the focus trap are koan-kit's own, and gpui-kit is no longer a dependency. The scrollbar fades on the GPU without drawing frames, and a panel gives the keyboard back to where it was when it closes.
- Sidebar and lyrics panel. They ease open and closed again, the page beside them reflowing at each frame's width; under Reduce Motion they still snap.
- Artist photo. An artist page's photo is now the size of a record page's sleeve, so the two headers line up.
- Toolbar buttons answer in colour alone.
ToolbarButtonno longer draws a square ground under the pointer or when on: the glyph goes frominktostrongon hover and to the accent when pressed, and a toggle that is on rests atstrong. - The desktop app's icon drops the spindle. The spindle told the app from the SwiftUI Mac app, which 0.70 replaces. The
just gui-rundev bundle and the launch icon of builds outside a bundle keep it, so a dev build is told apart from the installed app. - The desktop app is kōan on the Mac. It uses the Mac app's configuration, device id and saved queue, and the release ships it as the only Mac app; the SwiftUI Mac app is no longer released.
Fixed
- The GUI app's output menu lists UPnP renderers. Opening it searches the network and the menu fills in as renderers answer; the renderer in use shows its volume on a slider and says what it is sent, as the Mac app does.
- The paused track keeps its bars in the desktop app's lists. On record and artist pages and in the track browser the current track's bars fall flat on a pause instead of giving way to its number.
- tvOS TestFlight. The Top Shelf extension declares arm64 in
UIRequiredDeviceCapabilities, which App Store Connect requires of a 64-bit extension; the v0.69.6 tvOS export was refused without it. - The desktop app no longer risks a crash closing a window. A frame wake queued as a window closed could run after its view was released. Windows also keep drawing for a second after input, as GPUI asks, so a display does not drop its refresh rate between scroll events.
- Editing one figure of an EQ band no longer changes its others. A band imported past the hand-edit limits, such as a Q of 30 from REW, keeps that figure when its gain or frequency is edited, so the profile still matches its file.
- Album tiles keep their size while the desktop app's window is resized. The room between and beside them takes the change, until a column fits or no longer does.
- Library totals arrive with their pages in the desktop app. The album, artist and track browsers draw their header, total and rows together, and a revisit draws at once from the listing it last showed.
- Covers no longer show another record's sleeve after the library is rebuilt from scratch. Each cover cache, on the server and in every app, empties itself when it has been away longer than the library remembers what it removed, or the database is new.
- A seek lands at once from every device and never pulls the bar back. A seek sent from another device, a remote or GraphQL settles the playhead where it asked, as one from the app does, and one the player clamps or declines shows where it really went.
- Settings in the desktop app no longer undo a sign-in or another app's change. A setting changed while a sign-in was under way, or after the terminal UI wrote the file, wrote back only itself. A new key, app password or invite is never replaced by another sheet before it is seen, and quitting with a device waiting to pair declines it.
- The desktop app's album grid holds far less memory after a long browse. Covers in memory follow what the lists on screen ask for rather than a fixed budget, sleeves decoded for rows already scrolled past are dropped, and leaving the grid lets its covers go.
- The desktop app's EQ page follows the output in use. A band table row no longer sticks on saving after another device changed the filters, and re-importing an impulse response over one of the same rate now reaches the account's other devices.
- The desktop app builds on Linux again. A duplicate import and a test macro's recursion limit had stopped its design system compiling there.
- Organise previews from where files went. After a move that left some files behind, the GUI app reads the selection again, so the next preview starts from the moved files' new paths.
- In the desktop app, ⌫ removes the selected queue rows and Minimize and Zoom work. Media keys no longer wait on each other, dropped files keep the order they were opened in, a track's details close when you move to another page, and the window remembers its size when closed.
- Saved queues stay with the device that saved them. A second terminal UI on a machine no longer overwrites the first one's queue when it quits; saving and clearing the playback state works through MCP; and clearing the app's saved session through its own server no longer loses the queue at the next launch.
- A server started before its music is mounted shows covers once it is. Covers that could not be read are no longer remembered as missing, an album whose first track's art is damaged takes the next track's, and a cover a busy server could not send is asked for again rather than left blank.
- The desktop app builds again. Gathering the tracks to organise borrowed its list twice in one expression, which the compiler refuses.
- The desktop app's Rebuild Index asks first and says what it keeps. The queue's playing bars stop when the music does and leave with their row, and Clear Artwork Cache brings back the covers on screen at once.
- The server builds again. The cover warm read its source image through a type the compiler could not size.
- Hearts appear again on the desktop app's queue rows under the pointer. The output menu's EQ button opens that device's EQ, the sidebar's resize grip no longer covers the controls beside it, and copying a share link says whether it worked.
- Covers on a slow server. The kōan GUI app now asks a server that slows down for fewer covers at once rather than more, no longer sends hundreds of requests at once after a fast scroll, and stops re-requesting the covers where a flick lands.
- The apps build again. A cover kept on the device was looked up with a configuration the code no longer had in scope.
- The desktop app builds again. The shelf pages released their covers through a call whose signature had changed.
- Clicking a lyric line moves its emphasis once. The line clicked takes the emphasis at once and keeps it while the seek lands, rather than flicking back to the old line.
- A shelf's "see all" draws once. The album, artist and track browsers no longer show the listing kept from an earlier visit under another filter before the shelf's own arrives.
- A shelf's "see all" keeps its own filter. Opening a shelf's albums, artists or tracks shows them on a page of their own, and the library's browsers keep the filter they had, rather than staying on favourites afterwards.
- Toolbar toggles sit level. A toggle's on-underline no longer lifts its glyph above the buttons beside it, in the toolbar and the transport alike.
- Single-key shortcuts no longer act behind a question or a menu in the desktop app. Space with a confirmation up used to play or pause the music. Following the playing track survives a track that is still downloading, and the sidebar's foot says when sharing this computer's library failed.
- Sync's last phase is timed, and albums gone from the server are confirmed eight at a time. Each step the apps show as finishing a sync (confirming albums the listing left out, removing what the server deleted, the database's statistics, then favourites, playlists, play history and EQ) logs how long it took, so a slow finish says where the time went. After a server deletes records, confirming each is gone now runs eight requests at once rather than one after another.
- The desktop app's playing bars rest in a hidden window. Hiding the window no longer keeps the analyser running, the bars move once per display refresh, only the windows showing them repaint, and the accent always finishes settling.
- The tests build again. Two test modules lost an import and a component kept one it no longer used.
- The desktop app builds again. Following transfers read the mirror and wrote to itself in one call, which the borrow checker refuses.
- Choosing from a submenu in the desktop app works. Adding a track to a playlist from its menu did nothing, and Left in a submenu closed the whole menu. Clear Downloaded Files works whichever window is in front and says how much it freed.
- GUI app layout fixes. Long names in the queue, the transport and the rows end in an ellipsis rather than being cut mid-letter; the library filter's rows fit their popover; a record's page gives the window its colours by the page showing, back and forward included; the queue's grouping is laid out off the main thread and never left stale; with the sidebar hidden the toolbar names the queue, history and downloads; and the library's toolbar no longer redraws for every cover that lands.
- Signing in to a large server finishes sooner. A sync fetches the playlists it pulls eight at a time instead of one after another, and logs how long each step after the library took.
- The desktop app's album grids line up with their pages. Their first column sat 16 points in from the header. The queue's shuffle-the-rest button is greyed when there is nothing to shuffle or shuffle play is on, and smart playlists no longer light up for a drop they refuse.
- koan-kit builds again. The theme imported its colour type twice.
- A heart clicked twice quickly in the desktop app shows the second click. The sidebar redraws only for its own playlists' covers, its icons brighten on hover, and idle cover fetch threads end.
- The desktop app's transport controls never seek by mistake. A click low on shuffle, previous, next or repeat seeked; the controls and the seek bar are now laid out apart at every text size.
- The desktop app builds again. Stopping a TV's waking from the devices menu called its confirmation without the TV's name.
- The playing track's title in the desktop app's Dock menu no longer pauses the music when clicked. Covers fade in over their record's colour rather than flashing, and an artist whose photo has gone no longer holds an empty box in their header.
- Choosing an EQ preset while controlling another device no longer sends this computer's output to it. The desktop app's EQ button shows only for this device, and with processing off it is drawn plain and says so.
- A release's desktop DMG is attached even when its Linux packages are not. Each GUI package goes up on its own, and the notary's full wait fits the job.
- The desktop app builds again. The transport bar waits for its sleeve as a
CoverArtimage, after two changes to the cover type met on main. - koan-kit builds again. The slider used an accessibility setter whose trait it did not import.
- A focused text field no longer redraws its page twice a second. The caret's blink is presented by the GPU instead of redrawing every view above the field, so the album grid or a browser stays at rest while its filter field has the keyboard.
- The desktop app says why it cannot open your library, and what to do. A database a newer kōan has upgraded, or another desktop app already running on the configuration, is shown in a window instead of the app quitting without a word.
- The desktop app builds again. A record tile read its state after handing it over.
- Ctrl-C in the terminal quits the desktop app as ⌘Q does. The queue, the window's size and unsaved settings are kept rather than lost, and in full screen the sidebar no longer starts under an empty band.
- The workspace builds without warnings again. Clippy and the tests compile cleanly after several changes to the desktop app met on main.
- Download marks. A row's mark follows its download exactly: no flicker between the ring, the cloud and the arrow while it downloads, the full cloud the moment it completes, and cleared tracks shown as downloaded again once they are fetched again.
- A click on the seek bar lands at once. The bar no longer shows the old place for a frame while the engine takes the seek, so it does not jump on the way to where it was clicked.
- The transport's other controls say what they do. Shuffle and repeat say whether they are on, the sleep timer, output and devices buttons name themselves and what they hold, and the EQ button names its shortcut.
- The queue's playing bars rest flat on pause. They fall with the pause's fade and lie flat while paused, as the library's rows do, instead of giving way to the play mark.
- Network speakers on the desktop app. When macOS keeps the app off the local network, the output menu says so and where to allow it instead of staying empty;
just gui-runlaunches a build as an app of its own, so it can be allowed. - Output and Play on menus. Choosing an output, a network speaker or a device keeps the menu open, so the choice is seen to take.
- Play on and output menus. Each row's buttons line up with every other row's, a long explanation stays on one line with the rest on hover, and the small buttons are quiet glyphs that say what they do.
- Opening the desktop app again while it runs. A second launch brings the running app to the front with what it was given, instead of quitting with nothing shown.
- The Konami code in the kōan GUI app. A capital B or A no longer starts the code over.
- Waking an Apple TV from the kōan GUI app. Choosing a TV that nothing can wake yet opens the pairing that lets it be turned on, rather than doing nothing; a TV signed in from Settings is offered waking as soon as it links, as on the Mac; and Play on says why when choosing or forgetting a device fails.
- Links into the desktop app.
koan://invite and pairing links open the desktop app; it also declares automatic graphics switching, as the Mac app does. - Queue drags, submenu choices and sheets in the GUI app work again. Dragging rows in the queue reorders it while downloads are landing; before, a drop after the queue was refreshed was dropped. Choosing a playlist from "add to playlist" in a context menu adds to it again; the menus had measured themselves one menu-height too low, so a press in a submenu closed both before the click landed. The organise sheet and the Apple TV wake sheet take the keyboard while they show, so Space and the arrows no longer play or move the queue behind them.
- Main builds and tests cleanly again. Two clippy lints, an unused import and two stale test expectations left by merges meeting.
- Clippy and the theme ratchet pass on main again. Two type lints in koan-kit, and the rainbow's test harness counted in
theme-leaks.toml. - Play on menu. The controlled device's tick and the others' "move here" share one column at the right edge, and ticks in the app's menus are in the accent colour.
- Output and Play on menus. They keep one width as their rows change, and the chosen row stands on a faint accent ground, as in the Mac app.
- Network speakers. The volume slider stays where it is let go while the speaker takes the change, and a playing row shows a speaker mark instead of still bars while the speaker plays the file itself.
- A saved session is never overwritten before it is read back. Every app's engine refuses to save while the session is being restored, and before that saves only a queue the person has changed. A quit during start-up, or after a failed read, no longer replaces the saved queue with an empty or half-restored one; the desktop app's own guard, which one busy database read turned off for the whole run, is gone.
- Picked rows, the Dock, About and the toolbar in the kōan GUI app. A picked row's number, play mark and errors read on its fill, and a picked row shows in dark mode; the Dock's Favourite agrees with the pages' hearts; About opens once on Linux and reads in either appearance on a Mac; the transport's sleep, output, devices and EQ buttons and the filter field are easier to hit, and the filter field gives way before the toolbar's buttons in a narrow window; the EQ band table's figures line up.
- Clippy passes on koan-kit again. The button's and transport control's click handlers are allowed their main-thread
Arc. - Playing bars stay under panels, and the wash fades out without a jump. A track's details panel covers the GUI app's playing bars rather than showing them through it. Taking the wash off while a record dissolves in fades what shows from where it stands, rather than first snapping to the new record. The bars' heights are read in koan-core, so the desktop and Mac apps draw the same bars from one rule.
- koan-kit builds again. Its test helpers are compiled only for tests.
- The engine builds again. The session gate reads its baseline before the player state moves into the engine.
- The desktop app builds again. Several merges met on main.
- The desktop app builds again. Two more spots where merges met.
- Tooltips in the toolbar and transport. A control in a part of the window that redraws only when its own content changes now shows its tooltip after the usual delay.
- Main passes its format and lint checks again. An unused import, two files formatted, and the theme ratchet lowered to what the EQ graph now holds.
- The workspace builds without warnings again. A constant the wash no longer reads and a few unused imports removed.
- Hovering no longer crashes the kōan GUI app. A view drawn again after a frame in which its cached ancestor was reused whole could reuse text layouts recorded two frames earlier and panic in
reuse_layouts(in its paint as well as its prepaint); such a view is now drawn afresh. - The desktop app builds again. Download rings keep their colour type in scope.
- Hover leaves as everywhere else on the desktop app's transport controls, pickers and the EQ sheet's choice rows. Their highlight came on and went off at once; it now fades out after the pointer leaves, as every other control's does.
- Copy buttons keep their width in the desktop app while they say "copied", so the buttons beside them stay put.
- Playing no longer crashes the desktop app. The seek bar's clock waited on a timer that needs a runtime the app does not run.
- koan-kit builds again. A name in the availability mark shadowed another.
- The seek bar runs on after the window shows again, and download rings draw on Linux. In the GUI app a seek bar brought to rest while the window was hidden stayed where it stopped once it showed; download rings failed to build on Linux; a download of unknown size showed an empty bar rather than a running one; Reduce Motion cut between records' washes rather than dissolving, as the Mac app does; and a curve control point just under 0.5 or 0.25 was drawn at half its value.
- The sidebar and lyrics turn back smoothly when toggled quickly. A slide reversed part-way now turns from where it stands rather than jumping to the far edge first, and a closed lyrics panel is let go at once rather than kept until something else redraws the window.
- The transport's sleep, output, devices and EQ buttons fade back after a hover, as the other controls do, rather than switching off at once.
- The search box keeps its place and does what its footer says. ⇧⌘Return replaces the queue as listed; ticking a result keeps the light on it as it moves to the top; an answer arriving again for the same query no longer resets the lit row; "nothing found" waits for the answer rather than flickering while typing; a single ticked record plays rather than opening; and ⇧Tab and F6 no longer reach the page behind the box.
- Rainbow mode rests when koan is behind, and its beat is softer. The wash's and the disco's brightening on each beat is lower. A window behind another app no longer animates to the music, and closing a window no longer leaves the analyser running for good.
- The cover preload fetches two hundred to a request from a kōan server, as it was meant to. The preload names each record by one of its tracks, which
koanCoversanswered as not held, so every cover still came one request at a time. The server now answers a track's id with its record's cover, and a stream cut inside a frame's first bytes is read as cut rather than as its end. - Clippy passes on koan-kit again. The lyrics' line colour reads as one condition.
- Sliding and revealed panels. Spinners, rings and fades inside the sidebar move with it as it slides, a late artist photo's reveal clips its cover, and the textures behind these take a fraction of the memory: only the part of a panel on screen is drawn into one, and a panel at rest is not drawn again at each present.
- The cover preload stops when asked. Stopping it, backgrounding the app or a metered network ends a bulk answer between covers rather than after its last; its requests share the limit a page's covers have; a failed chunk no longer ends bulk fetching for the whole pass; and the server no longer holds a thread for each bulk answer while it is read.
- The desktop app builds on Linux again. The wgpu renderer's layer groups construct the field the shader layers gained.
- The GUI app's sidebar rests while nothing happens. Since answers for music arriving were added, the sidebar asked for another draw on every frame, keeping an idle window busy at the display's rate; it now draws only when something changes. Music added from outside the app (files opened, dropped or named on the command line) answers on the queue's or the playlist's row as music sent from a menu does, and a second notice or arrival soon after another is answered too.
- The seek bar's times land on a seek at once. In the kōan GUI app a backward seek, or one made just as the clock ticked, no longer shows the old place for up to a second, and the times no longer step back a second when the queue changes. The engine's clock stops counting at the end of a track.
- Hearts answer favourites changed elsewhere, wherever they are. A record favourited from a menu, a shortcut or another device now answers on its tile even when the pointer is not over it, and a heart emptied elsewhere is seen to close on a row rather than vanishing; a notice no longer answers again when the sidebar is shown again while it stands.
- The desktop app's rainbow appearance rests when the music does. It stops moving and presenting while paused or behind another window, its sheens and gradients included. The sweep between records fires when another record starts playing, not on a stop. Under Reduce Motion the sheens are hidden. The mirror ball's spots wheel from the ball at any spacing, the seek trail takes brat's lime, bursts are mounted only while they fly, and the disco costs less a pixel.
- Opening at login starts the GUI app in the menu bar on macOS, as it was meant to. It never recognised a login launch, so it opened its window every time. Bringing kōan forward opens its main window rather than Settings, and never two of them; turning Open at login on or off no longer holds up Settings; the menu bar's fallback mark no longer shrinks the app's icon elsewhere; and on Linux Settings says Open at login is off when the session has been told to skip the entry or the app has moved, and an app in a folder with
%or$in its name starts at login. - Increase Contrast strengthens the rule over the transport too. The GUI app doubled every rule's weight with the system's Increase Contrast setting except the one over the transport, which stayed at its thinnest.
- Kept running, kōan leaves the Dock only once none of its windows is open. Closing the main window with Settings still open no longer takes Settings out of the Dock and the app switcher; a launch at login stays in the menu bar whatever order the start-up reads land in; and keeping kōan running follows the configuration file as it is written, so a write that fails, or an edit made elsewhere, does not leave it acting otherwise.
- Polish from the #1808 review. Under Reduce Motion a download of unknown size shows a still arc in the desktop app, not a turning ring. GNOME on X11 no longer scales text twice. The accent's high-contrast shade is worked out once per record instead of looked up on every draw, and is kept apart per palette.
- The desktop app's record grids line up with their pages. The first and last columns of the album grid and an artist's records now sit on the page's margin, in line with the header above, and a wider window spreads the tiles apart.
- Settings → Appearance's sliders line up. Their rails start and stop level with each other whatever the words at their ends. An empty page's sentence of detail no longer leaves a single word on its last line. A button beside a text field in Settings stands as tall as the field. Settings' text fields hint in lowercase, as every other word of the app does.
- The keyboard keeps a pick in the album grid, the artist page and the shelves. An arrow key while picking no longer ends the pick and drops what was ticked; a verb from the menu key over a pick ends it as one from a right click does; ↑ on a grid's top row stays where it is rather than jumping to the first record; and a long shelf keeps its spacing between rows.
- A long library folder in Settings keeps its name in view. The path is cut in the middle rather than at its end, and the home directory is written as ~.
- Keyboard and the wash in the kōan GUI app. Tab reaches the sidebar and the page's list again, a menu or question opened over a list keeps the arrow keys and Return, and setting the wash's drift to nothing lets it come to rest rather than stopping dead.
- The desktop app builds without warnings again. The window's close handler ignores a context it no longer uses.
- Accents and screen readers in the kōan GUI app. Accent text held for Increase Contrast follows each record again, the seek bar is named to a screen reader, and a disabled shuffle or a loading play button is reported as unavailable.
- Clippy and the koan-kit tests pass again. The prism's tests use the standard test attribute, and an EQ sheet row names its handler type.
- The keyboard in the kōan GUI app. On a shelf, the search results and the downloads page the arrows bring the item they reach into view, a pill or a record tile included, and pressing a key that stays on the same item still does; the menu key opens under the item from where it was laid out. The page's list takes the keyboard back when the shortcuts or the artwork viewer close, after Back from its filter field, and after a click on the sidebar's place already showing; a click on the transport leaves it with the list. Tab stays inside a question or menu, and F6 waits until it closes. The cursor stays on its row when History gains plays or a list reloads, ⇧-clicks and ⇧-arrows extend from where the pick began, and the sidebar scrolls to follow its arrows.
- The desktop app's sheets, looked over. Escape closes a sheet such as Organise, as its cancel does. The keyboard shortcuts open centred over a dimmed window, like every other sheet, and their keys read "⇧tab" beside "tab". A picker with nothing chosen says so instead of standing empty. Organise's title writes the app's word in lowercase. The search box lists what its keys do only once there is something to do it to.
- Lyrics glide and the cover preload. In the kōan GUI app the lyrics glide to each new line rather than jumping, and a line left behind by a seek to the start fades back with the rest. The cover preload no longer re-asks an overloaded or refusing server at once, counts a chunk fully answered as done however its stream ended, and resumes after the app wakes even when it woke as the pass was stopping.
- The wash's Turn eases, and every wash follows Drift. A change of Turn now eases the wash to its new angle rather than snapping. The wash drawn without shaders moves at the chosen pace on Linux, where it cannot turn, and on Android, where it also turns as far as chosen.
- A page's covers ahead of the cover preload. The preload's requests no longer count against the limit a page's cover requests share, so a page never waits behind them or gives up on a slow connection; a
koanCoversanswer pauses while a page's covers load, and a preload waiting for a slot stops as soon as it is stopped or the app goes quiet. A kōan server reads a few covers ahead of the one it is sending. - The desktop app's lyrics keep their place through quick lines and song changes. A line reached mid-glide carries on smoothly instead of snapping. A new song never starts from the last one's place, the same words included. A click during a glide lands on the line under the pointer.
- Screen readers in the kōan GUI app. A track in a grouped queue or playlist is read with its place among the tracks, not among the rows with record headings counted; an artist page's tiles are numbered through their section rather than restarting each row; a shelf counts only the tiles it shows; and the sidebar's notice is announced as it changes.
- Screen readers in the desktop app. Two badges saying the same no longer stop the accessibility tree from being built. Sliders, segmented choices and sheets are named, and a submenu says whether it is open.
- A screen reader keeps going down and up long lists. In the kōan GUI app, moving through the track browser, a record, the artists, the album grid, history or an artist's page with VoiceOver no longer stalls at the edge of the screen: each row or heading reached scrolls the next one on and draws it, the uniform lists know which row is at their top so moving up goes up, and an artist's rows, tiles and the disc and day headings carry the walk on.
- Playlist order and seeks near the end. A playlist reorder made while signed out no longer overwrites the account's order at the next sign-in, and a seek near the end of a track no longer reads past its length while the player takes it.
- The accent turns everywhere at once. In the kōan GUI app a new record's accent now moves in windows at rest (the EQ window, Settings), in the EQ graph's strokes and in a text field's caret, rather than snapping when the turn ends, and the rainbow's colours reach everything that draws them.
- Seeks and playlist reorders. The engine no longer spins at full CPU after a seek on a controlled device lapses or races a change of device, and a seek on a device that is controlled but not listed just now holds that device's playhead rather than snapping back. A seek the player never takes gives the playhead back to every front end, and the terminal UI's seeks and media keys land on the bar at once. A playlist reorder no longer waits for an earlier reorder's request to a slow server, so the transport stays responsive.
- Terminal sessions and pairing on quit.
koan --remoteno longer takes the terminal's place or overwrites its saved queue, a terminal on a filesystem that cannot lock keeps its session, and quitting the kōan GUI app declines every waiting pairing rather than only the first. - A cleared or half-restored session no longer loses the queue. The terminal saves the whole session again when its saved row has gone, and `savePlaybackState` waits while an app is still restoring its session.
- Playlist edits in the kōan GUI app. Offline, dragging in a playlist with tracks not on this device no longer sends those tracks to the end; play on an empty playlist leaves the queue alone; and a playlist dropped on its own page is not added to itself.
- Play on and the output menu. A renderer found while the output menu is open no longer moves the highlight onto another one, the menu no longer says this computer may need updating while its outputs are read, music moved here that has not started says so in plain words, and the transport no longer redraws whenever another device reports its playhead.
- Covers kept on the device. A cover fetched just before signing in to another server is kept under the server it came from, and a preload running when the server changes stops. Trimming the cache removes the covers least recently used and the oldest records' first, keeps the record of covers the server lacks, and no longer resets the queue's downloads when only covers went. Scrolling quickly no longer makes other cover requests give up. Clearing the apps' artwork, and a cover the Mac app could not decode, now reach the server again instead of the engine's kept copy.
- The EQ window, looked over. Sheets start a step below their head, links sit on the text's edge instead of centred, a target's previews stand in columns, and Manage EQ's details read in one case.
- Reordering a playlist offline. In the desktop app and the Mac app, moving or dropping tracks into a playlist while some of its tracks are not on the device works, and the tracks not shown keep their places.
- EQ: where a profile plays, and a failed AutoEQ search. A profile's "used for" lists the outputs whose filters hold it as well as those it corrects, so it no longer says "no output yet" beside a button for one. An AutoEQ search that fails says so, rather than that AutoEQ has nothing for the headphones.
- Organise moves only what it previewed. In the kōan GUI app, choosing a named pattern previews it before it can be run, rather than moving files under a pattern whose plan was never shown, and whether cover art and cue sheets go with the music is saved before the move reads it.
- Move here, with a controlled device out of view. While a device is controlled but not listed just now, the apps no longer offer to move music as if this device were in view. The Mac, Android and desktop apps now share one rule for when music can move.
- Organise moves what it previewed. The desktop and Mac apps run the plan they showed, with the choice about cover art and cue sheets as shown, instead of reading the library again when the move starts. If the library changed after the preview (a rescan, a sync, an import), nothing moves and the sheet previews again.
- Playlist pages let go of their covers. In the kōan GUI app a playlist page left behind no longer keeps its header's sleeves asked for, so cover memory follows what is on screen after visiting many playlists.
- Reordering a playlist offline on Android. Moving a track in a playlist while some of its tracks are not on the phone keeps the others where they were, instead of moving them to the end and sending that order to the server.
- Cancelling and retrying downloads. A download that finishes just as it is cancelled plays rather than staying failed with its file on disk. "Clear finished" keeps cancelled downloads, since their row is the way to retry them. Retrying a download no longer pins it in the cache unless it was asked into the cache, and a cancel and a retry land in the order they were made.
- Shelves while they load. Favourites, Recently played and Downloaded show nothing until their first answer instead of saying they are empty; a failed read says so and is not asked again until the shelf's contents can have changed; a heart reads the Favourites shelf once.
- Lyrics and the artwork viewer. Clicking a synced line lands on that line rather than a millisecond before it, which left the line above lit, and resizing the window with a cover open no longer refetches and decodes it at every step.
- The transport's and the viewer's sleeves. They forget a record the library lost, so a reused id no longer shows another record's cover, and are decoded for the display's scale. An entry the library no longer has finds its lyrics by its own tags; closing the artwork viewer gives the keyboard back to the page under it; Track Info shows where a server's track is kept on this device.
- Playlist sync and the cover preload after a sync. A playlist pushed from this device while a sync was fetching it is no longer overwritten by the server's older copy, and the cover preload starts as soon as the library is in rather than after the EQ profiles sync.
- History and muted bars. Clearing the history under a filter says how many plays it forgets in all, not only those the filter shows; two plays of one track no longer share a row's clicks; and muted, the playing bars rest instead of redrawing flat.
- History, steadier. A new play no longer creeps the list down a row; a failed read says so instead of leaving the page blank; Backspace and Delete forget plays through the app's shortcuts, so they wait behind an open menu and Edit → Delete works on the page.
- Setting up an Apple TV's waking. In the kōan GUI app the Play on menu closes when its button opens the pairing sheet, rather than covering it, and a fifth digit typed or pasted into the TV's code no longer leaves the sheet stuck.
- Cancelling an Apple TV pairing. Closing the pairing sheet while the TV is still being found now takes the code off the TV, and cancelling while a code is being checked leaves no device of the account set up to wake that TV.
- Covers on a server that slows down. The kōan GUI app halves how many covers it asks for at once once per slowdown rather than several times for one, no longer counts its own disk work as the server being slow, and does not let answers to requests made before a cut widen it straight back.
- Library pages no longer crash as they open. The list menu reads the keyboard cursor from the page as it draws, not by reading the page mid-draw.
- Library menu questions, notices and the artist page. In the kōan GUI app, Clear Downloaded Files and Rebuild Index ask in the main window, brought forward, rather than behind Settings or the EQ; a notice cut short at the sidebar's foot shows its whole text under the pointer; and an artist page scrolled down to its biography keeps its place.
- Menus and the Library menu's tasks. A menu opened over another gives the keyboard back to the list rather than to the closed menu, and the toolbar's and the transport's menus give it back at all; Clear Artwork Cache asks in the main window whichever is in front; Clear Downloaded Files checks again that nothing holds the downloads when confirmed; the sidebar's counts follow a scan or sync as it runs.
- Linux menus act on the page, and the queue follows. In the kōan GUI app on Linux, the in-window menu's Edit items (Delete, Select All, Undo, Redo) reach the page they are for rather than stopping at the toolbar, and following the playing track keeps up when the track changes without the queue changing.
- A second launch says when its hand-off was lost. When the running kōan GUI app does not take the files and request to come forward in time, the launch logs it rather than exiting silently, and an interrupted wait is retried.
- The queue's dice says why it is off. In the kōan GUI app the greyed shuffle-the-rest button says whether shuffle play is on or nothing follows the current track; a smart playlist's sidebar row no longer refuses its own tracks let go over it; and the sidebar reads playlist sleeves a few at a time rather than all at once.
- Nothing acts behind a sheet or a question. Modifier shortcuts and single keys wait while a sheet, the shortcuts list, the artwork viewer or a question is over the desktop app's window. Quit, Hide and Settings still work. Linux's in-window menus grey what nothing would handle, and their submenus stay inside the window. A playlist moved in the sidebar no longer flicks back while the move is written. A menu whose page went while it was open gives the keyboard to the page showing. A lone record in a narrow grid stands on the page's margin, level with the header, rather than centred.
- Sidebar sleeves, transport presses and selected rows. In the kōan GUI app a playlist's sleeve in the sidebar is drawn again when it is dropped from memory rather than going blank, a press between two of the transport's buttons acts on one of them, never both, and a selected list row's detail stays readable.
- Covers after a fast scroll. Memory held for the album grid's covers falls back once a fling ends, covers at the edge of the scroll's reach are not decoded twice, covers on screen no longer wait behind fetches for where a flick lands, a server that is slow but steady keeps fetching several covers at once, and the sidebar's faces are fetched several at a time with no page open.
- Closed windows leave nothing behind for the playing bars. The kōan GUI app no longer keeps an entry per window ever opened (Settings, the EQ, About) in what feeds the playing bars.
- The filter field gives way in a narrow toolbar, and the rainbow washes the whole window. The toolbar's groups no longer hold the field at its full width, and the rainbow's sheen shows under the sidebar and toolbar with colours from the record off. A build outside a bundle names itself without writing to a dictionary it cannot know is mutable.
- QR codes never take the window down. In the kōan GUI app a QR code given fewer modules than its grid draws the missing ones light rather than crashing.
- Drops at a playlist's edges, and copyable values from the keyboard. A drag over the blank space below a playlist's rows lands at the end, and above the first row of a playlist or the queue at the start, rather than at the last row crossed. Settings' copyable values take the keyboard focus, copy on Return or Space, and are named for screen readers.
- A choice menu's Escape is its own; the shortcuts list at larger text. Escape in an open choice menu closes the menu and nothing else: the sheet around it stays up and a field keeps its text. The keyboard shortcuts sheet widens with the text size, so its groups stay side by side.
- Menus say what they show. In the kōan GUI app a menu's word button, such as "move here", is named to a screen reader by the words shown, and a choice that cannot be chosen now still shows its tick, muted.
- Menu row buttons work with a screen reader. In the kōan GUI app a menu row's buttons (move here, forget, waking, EQ) can be pressed through VoiceOver or Orca, and a row with no second line no longer shows an empty tooltip.
- Credits, grouping and the EQ graph. In the kōan GUI app a long credit cuts its names rather than the joins between them, the queue's grouping toggle answers a second press before the first has been laid out, a closed window's album page no longer holds the other windows' colours, and the EQ overview's graph is no longer clipped.
- Idle frames draw less, and loading panes speak. Controls at rest no longer draw shader quads, a seek bar's correction no longer steps when a new position arrives mid-correction, animation timing stays exact over days of uptime, and a loading pane's spinner is announced to screen readers.
- The chosen row in a menu shows the keyboard and holds its contrast. In the kōan GUI app the ticked row in Output, Play on and other menus brightens when the arrow keys reach it, as under the pointer, and with Increase Contrast on it stands on an opaque ground rather than a faint tint.
- Downloads shown as far as they have come, and pickers that hold their size. In the kōan GUI app a stalled download's ring, bar and the seek bar's downloaded part stop where its last report could take them, rather than running on to full and letting a seek land in bytes not there yet, and they no longer keep the window drawing. The Output and Play on menus keep one width as rows come and go, a long name cut rather than widening them; a setting's tick, such as group by album, no longer takes a chosen place's ground; and a choice that cannot be chosen now keeps its ground, quieter.
- Hearts, drops and lyrics. In the kōan GUI app a heart is a toggle a screen reader can name and press, a playlist's own tracks let go over its sidebar row no longer answer as if added, and a lyric line clicked lets go after a moment even while paused and is never carried into the next song.
- Answers, empty shelves and the wash's colours. In the kōan GUI app a worded button or transport control is answered under its word rather than by a ring through it, a pressed button's lift sits under its label, an empty "see all" page says what its shelf holds rather than pointing at the library's filter, and the record wash blends neighbouring colours evenly instead of darkening where they meet.
- Menus' actions line up and reach the keyboard. A row's glyphs stand with the other rows' glyphs and its words ("move here") in a column as wide as the widest words at the text size, so neither spills nor wanders. → moves onto a highlighted row's actions, ← back, Return runs one. A row's detail shows a tooltip only when it is cut, and Play on's Local Network instruction is a note read whole.
- Settings and Organise. A link that opens the app is answered once Settings has read its file, a pairing link naming the signed-in server by another of its addresses is accepted, and a pairing approved elsewhere is no longer declined on quit. A failed save no longer lets what waited on it run, a question waiting behind another is not lost when the first is answered, and Organise previews only the newest pattern typed.
- Covers from a slow server. A server that takes a few seconds for every cover, such as a small board resizing each one, keeps fetching several at once rather than one at a time.
- The desktop app builds again. The settings model imports a type it names.
- Organise names what it will use. A named pattern edited in Organise shows as typed here, as the edited text is what the preview and the move use.
- Fixed widths at the Mac's sizes. The EQ page's width, Settings' number fields, the account sheet, its field and the QR codes stand at the Mac's sizes at the default text size, about 7 % wider than they had become, and grow with the text.
- Grouping a long queue in the desktop app. Turning record headings on or off in a queue of tens of thousands of tracks no longer holds up the window while the queue is copied.
- Lyrics at rest, at the Mac's sizes, and a click that lands once. The lyrics panel no longer draws a frame after another while its lines stand still, which kept the CPU busy whenever the lyrics showed. Only the line being sung is drawn large, as on the Mac. A click on a line moves the emphasis there and keeps it there until the seek lands, rather than flicking back to the line before.
- The seek bar shows a track downloading again. After a track's files were cleared, its new download drew the downloaded part as already complete, so nothing showed.
- Coming back to a library browser. The albums, artists and tracks browsers in the desktop app no longer draw a listing kept from the last visit after the filter changed elsewhere or the library moved, so the scroll position no longer lands on other records. A listing that cannot be read says why and offers to try again, instead of showing an empty library.
- Record pages draw their rows as they arrive. A page opened by navigation could wait for the pointer to move or the window to resize before showing its rows: its notify reached no window when its parent had drawn again in between.
- The search box lists five of each kind and stays inside its panel. Records and artists show as full rows with their art under the tracks, the list scrolls between the query and the keys, "All results…" ends it, and choosing a result goes to it without playing; a track opens its record with the track selected.
- Playlist edits after a removal. A playlist entry's id is no longer given to the next track added once the entry is removed, so a move or a drop made against a view from before the removal is refused rather than landing on the new track. The library database moves to schema version 33; the upgrade keeps every entry's id and place.
- Rainbow mode at the display's rate. Its layers cost about a third of the GPU time they did, measured at 19 ms a frame before and 7 ms after on a 1550 × 900 window at 2×, and a step of its colours no longer draws every album tile again.
- The transport keeps its sides, and has a heart. At larger text sizes or a narrow window the bar no longer squeezes out the playing record or the trailing buttons: the centre gives way first, the title is cut rather than lost, and only when even that is not enough do the trailing items go, the format first and the output last. The playing track has a heart beside its title.
- Pages and hover fades no longer wait for the pointer. A change made while the window was drawing, such as opening a record or leaving a button, could sit unseen until the next input.
- Playback controls answer while an output is slow to open. The audio output now opens off the player thread, so play, pause, seek and skip apply at once while a DAC wakes or the audio system is busy, and take effect when the device is ready. After two seconds the apps say which device they are waiting for, with Retry and Cancel; Cancel plays on the system's default output instead.
- Stopping, skipping and route changes no longer wait on the audio system. Tearing down the last track's output and re-reading the output device's EQ after a route change now happen off the player thread, so a busy CoreAudio no longer holds up the next command.
- The terminal UI builds again. Its remote control leaves the new output commands to the device they belong to.
- The terminal UI builds again. Its remote control leaves the player's DSP command to the device it belongs to.
- A menu refilling keeps its ticks still. A row moved by a menu filling in place (renderers found as the output menu opens) no longer draws its tick in again as if newly chosen.
- Clippy passes on koan-kit again. The code brought in from the GPUI fork is held to the workspace's lints, its colour matrices kept as published.
- Records synced from a server keep their year. A record first synced from its songs alone, such as one added to the server during a sync, stayed undated on the device after later syncs gave its year; the next sync now dates it, by its original release where that is known and by its release otherwise, and an artist's records sort by the same date.
- Text and the wash draw again on macOS. Since gpui-kit went and GPUI moved to koan's fork, the app drew no text (the macOS text system is a feature koan now turns on) and a black wash (the kit's shaders called a sampler the fork names differently).
- Sidebar and lyrics panel. They now appear and disappear at once instead of sliding, so the page beside them is no longer laid out at its final width before the slide ends, and a closed lyrics panel can no longer flash back for a frame.
- The album and artist hearts pop and deflate. The header heart answers a change as the hearts on track rows do.
- Clicking a lyrics line no longer flickers. A seek that lands a hair before the line keeps the clicked line sung instead of showing the one before.
- Queue rows can be dragged onto a playlist again. Dropping rows from the queue on a playlist in the sidebar adds their tracks.
- Typing in the desktop app's search box no longer lags, and its results scroll. A keystroke draws the query alone, whatever the results hold; the results are drawn when an answer lands, and in a small window the wheel and the touchpad scroll them between the query and the keys.
- A seek no longer flickers back to where it was. The engine read the playhead from the old session while the output reopened after a seek, so the seek bar and the lyrics showed the old place for a moment before the new one. That read is gone, a seek now resumes exactly where it was asked rather than at the start of a packet, and every client shows only the playhead the engine publishes: a seek bar let go holds the thumb until the engine answers that seek, and nothing else is predicted.
- Search answers as you type. In the GUI app the search box, and the album, artist and track browsers' filters, ask on every keystroke instead of waiting for typing to pause, and the search reads its three kinds side by side with each kind's matches checked once; over 30,000 tracks a keystroke's results draw in about 30 ms rather than 150.
- Artist photos after a search. An artist shown in the search box before their details had been looked up no longer keeps an empty photo slot on their page until koan restarts: the photo the page's lookup finds is fetched.
- Control fills and outlines. A control's hover fill and a picker's outline cover the control exactly, instead of starting at its padding and running past its right edge.
Internal
- GUI walk, comparison and parity inventory.
just gui-walkdraws every page of the GUI app offscreen and fails when a page's scroll frames run over 6.9 ms at the 95th percentile;just gui-comparesets its pages beside the SwiftUI app's offscreen renders with the edges that disagree marked;just gui-paritylists what the Mac app has as a checklist. - Vendored GPUI as patches; development builds without Xcode. Each vendored GPUI crate is its crates.io release plus
vendor/patches/<crate>.patch, checked in CI;just vendor-gpui VERSIONmoves them to a new release and stops at a patch that no longer applies. Theruntime-shadersfeature, which the development recipes turn on, compiles GPUI's Metal shaders at startup, so the Command Line Tools are enough to build the GUI app. - koan-gui: the Mac's hidden appearance mode. Its switch, its palette for the accent and wash, and the tracks that bring it out, kept per device as on the Mac.
- koan-kit storybook.
cargo run -p koan-kitopens every component and container on its own page, with the appearance, accent, text size, Reduce Motion and Show icons to switch, replacing the theme sheet;examples/storybook.rskeeps the offscreen PNGs. - CI builds GPUI once per push. The Linux job leaves the design system's crate to the GUI jobs, which already check it.
- koan-gui: the hidden appearance on the GPU. koan-kit's prism: a layer over the wash moving with the music, the beat at the window's edges, a mirror ball, rainbow bars and seek trail, shimmering tiles and title, confetti and a sweep between records; nothing mounted while it is off, nothing moving under Reduce Motion.
- koan-kit motion playground. A storybook page to design and tune keyframed motion: each easing on a sample at the display's rate, a draggable Bézier, spring parameters, the curve plotted, scrubbing, and the call to copy.
- koan-kit and koan-gui lose code nothing called. The picker's sheet parts, a compact EQ graph no page asked for, and helpers left behind as their callers moved; a row's links and heart are answered by one function in every list, and the queue's drop line by one handler for every kind of drag.
- The animation engine under churn, and download readings scoped to the desktop. koan-kit's stress tests drive the colour-slot table and shader uniforms from many threads, storms of retargets and hovers, long uptimes, a moving present lead and Reduce Motion turned on mid-animation, and koan-ffi's playhead clock is tested polled outside Tokio; the download store takes a reading every quarter second again, the desktop app's engine asking for about fifteen a second for the progress it glides on the GPU while phones keep the default.
just gui-smokeruns the desktop app as it is used. Headless against a muted generated library, it plays, seeks and pauses while the pointer sweeps every page in both appearances, and fails on a panic, a hang or a queue that never advances: crashes no compile or unit test reaches.- Leftovers of the move onto koan-kit tidied. Doc comments that drifted onto the wrong items, two names shared by a kit type and an app global, and a fallback that could not run; the track lists' number column keeps the width it had before the move at every spacing.
- The smoke run sets its environment before any thread starts. As its safety note says it does.
- CI runs the GUI smoke run. On macOS, whenever the desktop app changes, as a required check.
- The smoke run accepts the libraries it is meant for. The generator marks its libraries, and the smoke run checks for that mark rather than a file the generator deletes.
- The desktop app's tests no longer fail at random on Linux. The theme leaves the desktop portal unwatched under the test scheduler, whose wakes from D-Bus threads it refuses.
- Throwaway configurations keep their caches and state with them.
KOAN_PLACES_DIRputs a configuration's runtime files in one directory; the desktop app's examples andjust gui-runpoint it inside their throwaway, so deleting it reclaims them. - The smoke run says why its playing phase can be short. The first seek can wait on the audio daemon opening the output.
- koan-kit takes GPUI from the vendored crates. GPUI, its platform and its test harness come from the vendored GPUI crates rather than through gpui-kit, which is left only for the components koan-kit has not replaced yet.
- GPUI comes from koan's fork of Zed. The patched copies in vendor/ are gone; every change they carried is a commit on radiosilence/zed, proposed upstream, and koan pins a revision of it.
- The presenter stress test no longer fails after the accent tests. It waits for colours an earlier test left settling to land, and refreshes the colour table at each present as a renderer does.
- Clock tests no longer depend on timing.
a_seek_back_past_the_end_starts_the_clock_againanda_resume_starts_the_clock_againasserted readings within 100 ms of the whole second, which a loaded CI runner overslept; they now bound readings by a second and wait up to ten.
0.69.6
Added
- The web UI shows the server's caches. Admins see the cover cache by size against its budget, the warm's progress and the last sweep, the download cache and the last scan on the Library page, updating as they move, and can warm or clear the covers; GraphQL has the same as
serverCaches,warmCoversandclearCoverCache.
Changed
- The desktop app's transport, as the Mac app's. The play button sits as far below the bar's top as the Mac's, with the seek bar close beneath it, and with the wash under the whole window the wash runs under the transport too.
Fixed
- Covers follow every change to a record's art. A re-tagged file and a cover image added, replaced or removed now refresh the record's cached covers whichever scan finds them, including the start-up and periodic scans of a library the folder watcher hears nothing from.
- The desktop app's Linux packages build. The .deb step failed on a control file missing its architecture.
Internal
- The desktop app's DMG reaches the release whichever other packages built. The attach job looked for it in one place only.
0.69.5
Fixed
- Covers at a few shared sizes. Every app asks for covers at one of 150, 300, 600 or 1200 pixels, and a koan server keeps exactly those, making the 300 and 600 every list and grid uses ahead of time, so the desktop app's covers no longer miss what the server has ready.
- Covers fill quickly again. A koan server removes covers an older version kept at sizes no longer served, keeps up to 4 GB and makes every record's covers whenever there is room; the desktop app keeps asking for covers while a server answers a mix of kept and unkept ones, holding back only when it fails or stays slow.
- Clear Artwork Cache works in the desktop app. It says how many covers and how much space it frees, then deletes the covers kept on this device and fetches the ones on screen again.
- Covers on screen first, always. The desktop app cancels a cover's request the moment it scrolls away, and calls off covers off screen when ones on screen are waiting, so a fling no longer leaves the covers you can see queued behind hundreds you cannot.
Internal
- The GUI leak check annotates CI rather than failing it. Hand-built styling in koan-gui shows as warnings on the run; locally the check still fails.
- The Linux CI job fits the runner's disk. Test builds use line-table debug info, and unused preinstalled toolchains are removed first.
- CI builds carry no debug info. Faster builds and smaller caches, and the runners stay within their disk.
- The server image is tagged without waiting for the Mac app. Its release tags follow the Linux builds it ships from.
- Crates publish without rebuilding, and the GitHub release does not wait for them. A release goes out faster and is not held up by crates.io.
- The GUI DMG attaches to releases again. The attach job ran a bash feature macOS's bash lacks and stopped before the DMG.
0.69.4
Added
- Library pages in the GUI app. The GPUI app has the album grid, artist and track browsers, record and artist pages, filters, sorting, picking several things to play, drag out and context menus, over a cover cache that fetches and decodes ahead of the scroll.
- EQ and convolution in the desktop app. koan-gui has the EQ page for each output, the response graph with bands dragged and curves painted on it, the band table, Manage EQ, profile pages, AutoEQ, measurements, splitting a baked EQ, presets, and importing files, folders and zips, dropped on the page or chosen. An edit names the band it started on and is dropped when another device or page has changed the filters since.
- The desktop app names itself and has a Dock menu. Its icon carries a spindle at the circle's centre, so it is told apart from the Mac app, and a build run from source shows it, at the size the Dock gives every app's icon, and the name too. About kōan shows the version and its build. On macOS the Dock menu has what is playing, its heart, repeat, shuffle, play and pause, next and previous, the sleep timer and the devices to play on.
- Library tasks in the GUI app. Rescan, Force Rescan, Rebuild Index and Sync run from the Library menu, and each running task shows its progress at the foot of the sidebar; a scan can be stopped there.
- The desktop app's transport has an EQ button. It chooses the output's preset and opens the EQ window. With no EQ in force it is the plain glyph rather than a label reading "flat", and it takes the accent while a profile plays, with the profile named in its tooltip.
- The desktop app has an EQ tab in Settings. It shows what the output in use plays and opens the EQ window.
Changed
- Local cover art at the size asked for. The apps receive a local sleeve scaled to the size they request, as a server already sends it, rather than at full size; a record's opened sleeve on the Mac is now at most 1000 pixels for local files too. A scaled copy is turned upright by the image's EXIF orientation, which it no longer carries.
- The GUI app sleeps when nothing moves. On macOS and X11 a visible window woke at every display refresh to find nothing to draw; it now stops its frames after three idle ones and starts them again when something changes, through patched copies of GPUI's backends that are offered upstream.
- The GUI app's sidebar runs from the window's top edge. The traffic lights sit on the sidebar's ground with no line beneath them, and the toolbar heads the page column alone.
- The GUI app's sidebar scrolls and its playlists have sleeves. A short window scrolls the sidebar's rows rather than squeezing them, each place carries its glyph, playlists show the mosaic of their first four records, and the wash runs under every page, and under the sidebar and toolbar when "Wash the whole window" is on.
- The desktop app is called kōan. The menu bar, About and the Finder name it as the Mac app is named; it still installs beside the Mac app, and About shows its icon rather than a folder.
- The GUI app's queue and transport link to their pages. Credits, records and titles lead to their artist and record pages; multi-disc records number by disc; rows carry the heart and the Mac's availability mark, with a download's progress drawn as it lands; the sidebar hides and shows, and grouping by album is in the queue's menu, both kept with the window.
- The GUI app's playing bars move with the music. The queue's playing row and the library's playing record show three bars driven by the analyser, read only while a bar is on screen and painted over the page so a frame redraws nothing beneath them.
- The desktop app's design system. Covers without art show the ensō, loading shows it drawing itself, Settings is spaced as on the Mac, menus carry their glyphs, and the output menu lists each device under how it is connected. Pages now build from koan-kit's page, toolbar, form, table and menu, which decide the spacing.
- The queue and sidebar are built from the design system. Queue rows are koan-kit table rows with the Mac's columns, the sidebar's rows and playlist faces are its navigation rows and mosaics, and a download's ring no longer builds a path every frame. The queue's titles, records and artists are links, records numbered by disc show their disc, and each row has its heart and where its file is.
- Library pages built from the design system. The browsers' filter field, filters, sort, a new deal and select sit in the toolbar as icons, as on the Mac. A track row shows its play button under the pointer rather than going blank, artist rows lead with the artist glyph, and the record and artist pages share the Mac's header: the square play and the shuffle beside it, the title and its count, then play next, queue, copy share link and favourite. An artist page shows no photo box until a photo is found. A record's page gives the window its colours while it shows. Settings has its top margin back.
- The transport and its menus, as on the Mac. The controls sit as close as the Mac's, play and pause is outlined, and the seek bar is the design system's slider. The output menu lists each device under how it is connected with its EQ beneath its name, an EQ button per device, the network's renderers after them and a renderer's volume. Clicking a menu's button while its menu is open now closes it.
- Album art arrives faster from a server. The desktop app fetches as many covers at once as twice the number on screen, up to 512, rather than six, at the size it draws them, and covers that are ready together land together. Reading and resizing local covers is spread over the machine's cores rather than queued behind six threads or crowding them.
- The desktop app's EQ and sidebar foot on koan-kit. The EQ's band and point tables use koan-kit's dense table and its sheets koan-kit's sheet parts; the sidebar's activity rows are koan-kit progress rows with room below the bar, and the sidebar again ends with the connection and library counts, as the Mac app's does.
- The desktop app's queue and record pages, as the Mac app's. A picked row is a dark fill with white text; the queue marks each track played, waiting, next to download or failed; a record page's sleeve and rows are the Mac's size. The EQ button is its glyph alone, in the accent while an EQ is in force.
- The desktop app's wash, sections and queue. The record's wash no longer shows bands; an artist's sections are always headed, at the Mac's size; pages have the same margin on every side; the queue has its header again, saying what it plays, how much, and offering jump, grouping, undo and clear.
- The desktop app's sidebar, drags and queue controls. Sidebar rows are the Mac's height; a drag shows what it carries, with a sleeve, and lights only the places that take it; the queue's controls sit in the toolbar as the Mac's, with save as playlist and clear under ⋯; pages have a 16-point margin.
- Following the queue, and dragging playlists, in the desktop app. The queue's crosshair keeps the playing track in view until you scroll, as the Mac's does; playlists in the sidebar can be dragged to reorder them, or onto the queue to queue them; the queue's selection controls are spaced and drawn as text buttons.
- Covers fade in on the desktop app. A record's sleeve arriving where there was none fades in over its colour, as the other apps' do; one already in memory, or replacing a smaller copy, is shown at once. With Reduce Motion it appears.
Fixed
- Saving an EQ that did not change wakes nothing. An edit that leaves a profile as it was no longer wakes every client watching the engine or sends the profiles to the server.
- GUI library pages in fixed columns. Artist, track and record rows align their figures in right-hand columns, the artist page keeps its margins, its biography and photograph fade in, and the album grid can shuffle again under the random order. An artist lookup MusicBrainz refuses while busy is retried rather than left empty until the next visit.
- GUI activity rows fit the sidebar. A long task or count truncates inside the sidebar rather than running over its edge.
- Seeking no longer flickers. A click on the seek bar lands there at once in every app, and an update the engine sent before it took the seek no longer pulls the bar back to where it was; a seek the engine refuses gives the bar back after two seconds.
- Desktop app fixes from a run through. An artist's page keeps its title, buttons and verbs when the photo arrives, rather than collapsing them into a gap. List rows, headers and the album grid share one leading edge. Rows lose their hover fill, keeping the play mark under the pointer. The playing bars match the Mac's. Library → Clear Downloaded Files works, saying how much it frees before it does.
- Artist photos on the desktop app. A photo arriving no longer pushes the artist's name, count and buttons out of the header, and a photo whose stored address Wikimedia Commons now refuses is looked up again rather than never shown.
- The desktop app's toolbar and transport. The filter field can be clicked and shows what it filters; the toolbar is the Mac's height with its spacing and the window's buttons centred on it, and the transport's sleep, output and EQ buttons sit as close as the Mac's. The EQ button is its glyph alone, in the accent while an EQ is in force.
- Covers on screen first in the desktop app. Covers still downloading after they scrolled away no longer hold places from the ones now on screen, and covers from a server no longer wait behind local covers being resized.
KOAN_LOG=debuglogs how many are being fetched. - Covers no longer flood a slow server. The desktop app fetches covers 16 at a time to start, more while the server answers promptly and half as many when it slows, rather than up to 512 at once, which made a server reading covers off a spinning disk thrash.
- Covers from a koan server no longer read the music files. A record's cover is read once, kept, and served from what was kept, so a grid of covers does not send the server's disk seeking; a rescan of the record's folder drops it. The server makes every record's grid cover in the background, in the order the files lie.
Internal
- The Apple TV app builds again. The tab shell's player alert is a modifier of its own; the shell had grown past what the tvOS type checker solves in time.
- Apple CI runs on three runners. The engine's tests, the macOS app with the iOS typecheck, and the Apple TV app each have a job, so they no longer share one runner's cores; the Apple TV build now runs on pull requests too.
- GUI packages never hold up or fail a release. The release goes out without waiting for the kōan GUI app's packages; whichever built are attached afterwards.
- Menus, scrollbars and icons in the GUI app. Menus are the theme's own, as the Mac app draws them, with the keyboard; every list and page has a thin square scrollbar that shows while it scrolls or with the pointer at its edge; the transport's glyphs are at the Mac's sizes and the output button shows a speaker.
- A faster test loop for the desktop app.
just gui-runbuilds with agui-devprofile, at release speed but rebuilt incrementally, so a change to koan-core no longer rebuilds koan-server and koan-ffi whole. - koan-kit, the desktop app's design system, is a crate of its own. The theme and the components move out of koan-gui, which reaches GPUI only through koan-kit, so pages are built from the system rather than beside it.
- koan-kit's app module. The desktop app's pages are written in
koan_kit::app; every other GPUI use is a named import with a comment saying why, and the theme-leak check counts and enforces them. - Ctrl-C quits
just gui-runcleanly. Quitting the desktop app from the terminal no longer reports a failed recipe.
0.69.3
Added
- The kōan GUI app, drawn with GPUI, on macOS and Linux. Its first part: the window with the sidebar, the transport and the queue, grouped by record, with selection, keyboard control, drag to reorder and undo. It links the engine as the Mac app does; the library pages follow. Windows follows once the core builds there.
- The kōan GUI app meets the system. On macOS and Linux it shows what is playing in Now Playing and MPRIS and takes the media keys; has the Mac app's shortcuts and menus, and a shortcuts sheet; queues files dropped on it or opened with it; runs once per configuration, handing a second launch's files to the first; and is a device of its own beside the Mac app and the terminal UI. Releases carry a DMG, AppImages and .debs for it. Signing in, changing a password and redeeming an invite now name the server key after the device as it presents itself (the name given on the phone, or the TUI's and the desktop app's own) rather than the hostname.
- Settings in the GUI app. Everything the Mac app's Settings holds except EQ, in its own window: library folders, signing in or sharing this device's library, accounts, keys, people, playback, devices and appearance. Each change writes only the setting it changes, and anything that removes or replaces something says what it will do first.
Changed
- Each device keeps its own saved queue. The Mac app and the terminal UI can share one config directory, and quitting one no longer replaces the queue the other restores. Each starts from a copy of the queue saved before upgrading.
savePlaybackStateandclearPlaybackStatenow fail onkoan serve, whose player nothing restores; before, on a config directory shared with the app, they overwrote the app's saved queue.
Fixed
- The desktop app no longer replaces a saved session it could not restore. Quitting after a restore that failed, or before it finished, left whatever the app held, possibly an empty queue, in place of the saved one.
Internal
- The kōan theme in GPUI. A new crate, koan-gui, for the kōan GUI app in GPUI, starting with the theme: tokens, Geist Mono, the icon set, the record accent, the drifting wash, the components and a theme sheet that draws offscreen to a PNG.
- Protocol schemas render in key order with or without serde_json's
preserve_order. koan-gui's dependencies turn the feature on in a workspace build, which made the schema check fail there. - Slider drags in the GUI app redraw only the slider. A drag used GPUI's drag and drop, which redraws the whole window at every mouse move; it now follows the pointer with window-wide mouse listeners, taking a drag's frame from about 1.6 ms to 0.2 ms beside the theme sheet.
- Builds use the latest stable Rust.
rust-versionis removed from the manifests, so dependency resolution targets the toolchain in use instead of holding crates back for an old compiler; the MSRV CI job is removed, since there is no longer a minimum version to check.
0.69.2
Added
- Serving under a path. A
server.urlwith a path, such ashttps://host.example/koan, serves kōan there behind a proxy that forwards or strips the path, so it can share a host with other services, as Tailscale Funnel arranges them. A server whoseserver.urlalready had a path while its web UI was served at a root now links and scopes its cookies under that path: setserver.urlto where it is served. See Under a path. - Top Shelf on Apple TV. With kōan in the top row of the Home Screen, the shelf shows recently played and favourite records; choosing one opens it, Play plays it.
Fixed
- Long credits keep whole names. A credit naming more artists than fit shows the names that fit in full and ends in "…", where every name used to be cut to its first letters.
- Apple TV builds again. The TV app failed to compile after 0.69.0, so its TestFlight build for 0.69.1 was not made.
0.69.1
Changed
- Play shuffled deals the queue. Shuffle beside Play queues the tracks in a random order and plays from the top, with shuffle play off, rather than turning shuffle play on; the queue shows the order they will play in, and its dice can deal the rest again.
Fixed
- A sharing Mac keeps to its own. It takes down only the Tailscale Funnel it published, including when kōan quits; refuses a port another app already holds on this Mac; serves Subsonic and share pages only, so no invited account can drive its player; and keeps its public address in
share.url, leavingserver.urlto a headless server on the same Mac. - The queue's dice after a shuffled play. It often had nothing to shuffle once shuffle play was turned off, and on the Mac it was drawn in the accent colour rather than the header's ink.
0.69.0
Added
- The macOS app shares its own library. Settings → Server → Shares its library makes an account and serves this Mac's library to phones and other devices as a kōan server, with a QR code to sign a phone in. With Tailscale on the Mac, phones on the tailnet reach it from anywhere, and one button publishes it on the internet through Tailscale Funnel and points invites there. The sidebar says whether the Mac plays its own library, is connected to a server, or is sharing. See Sharing your Mac.
- Dice on the queue and on playlists. On the Mac, iPhone, iPad and Android, a dice in the queue's header shuffles the tracks after the current one in place, and one on a playlist's page shuffles the playlist. Each press is one undo step, so pressing again keeps dealing and undo walks back to the order you had; on a phone, Undo stands beside the dice while the last edits are shuffles. Shuffle play is unchanged and still leaves the rows alone.
Fixed
- Sign-out clears the queue at once, a server signed back in to syncs, and sign-in syncs once. The queue stayed until the server's library had been deleted, which on a large library took a while. A server signed out of, or left for another, refused every sync until the app restarted, the Sync button included, and reported it as up to date. Signing in ran the automatic sync and the app's own after it, walking the library twice behind two progress rows; the apps draw one row, and the second sync walks only if the first did not. On iPhone the server banner sits under the navigation bar instead of over its back button, and Settings shows the account an invite signed in to rather than the sign-in form.
0.68.0
Security
- Limits on what strangers can make the server hold. Sign-in reads a bounded body before taking a slot, the nearby listener caps connections, unproven peers and message sizes, DSP zip imports cap the archive total, the
configquery needs an admin andkoanCommanda writing role.
Changed
- Background work waits for events. The remote TUI follows server subscriptions, the web UI clock stops when paused, and the library watch and auto-sync sleep until something changes; failures that were swallowed are logged.
- The
nowPlayingsubscription no longer sends while the playhead runs on time. It sends on a seek, a stall, a pause, a track change or a drift past one second. A client counts on frompositionMswhilemovingis true.
Fixed
- Media keys work in the web UI on Chrome and Firefox. The browser player now holds a media session there, so media keys, headphone buttons and the system's now-playing controls reach it for every track, not only those over 15 minutes.
- Unfavouriting on one device sticks. Syncing no longer stars again what was unstarred elsewhere, every front end writes favourites one way, and commands and playlist edits land in the order they were made.
- Misspelt searches find things over GraphQL and Subsonic. Every front end searches through core, with one fuzzy ranking.
- App fixes from the audit. Headphone unplugs and calls leave a UPnP renderer playing on iOS and Android, real covers shared by editions are no longer hidden, Android queue drags survive downloads landing, and failed library reads say so.
- Large queues edit in one pass, and undo no longer holds old queues without limit. Undoing a reorder, playing next, relinking after a library change and similar edits no longer cost time proportional to the queue multiplied by the rows involved, and undo history is bounded by the rows it holds as well as by depth. Failed audio output setups no longer leak, a sample-rate notification can no longer reach a dropped watch, UPnP discovery refuses oversized or deeply nested descriptions and stops refetching failing ones, and a renderer switched off mid-playback releases its connection.
- The TUI and the Android app no longer redo queue work on every frame or patch. The TUI keeps the library's reading of the queue across status changes, updates download progress without re-deriving the queue, reads each track page from where the last one ended, loads the Now Playing cover off the frame thread, and shows a remote server's played and failed tracks as such. Android rebuilds only the queue rows a patch changes.
- A failed write no longer leaves the database locked. A connection that came back to the pool inside a transaction, after a failed commit or a caught panic, was handed to the next caller still holding the write lock, and that caller's writes were lost with it; it is now closed, and a failed commit is rolled back. Lyrics, artist bios and photos no longer hold a database connection while they wait on the network, a track LRCLIB has no lyrics for is not asked about again for a week, covers from a remote server are fetched at most eight at a time, and organizing onto another drive copies each file before taking the database's write lock rather than while holding it. Server playlist syncs, smart playlist refreshes and queue relinking do work in proportion to what changed, and a long playlist's undo history is bounded by its size.
- The Apple apps stay light with a long queue playing. A change to a few queue rows redraws those rows rather than regrouping and comparing the whole queue on the Mac, the track browser adds each page of a large library to its table instead of reloading it, the playing bars stop the spectrum analyser when their list is closed, EQ files shared to or opened in the iOS app are deleted once imported, and the caches of icons and cover colours are bounded.
- The server holds its resources under load. A linked device that stops reading is dropped within seconds instead of stalling its link and holding a growing queue; a link without a device id leaves nothing behind once it closes; share downloads are capped at four at once and end when the visitor stops reading; the cover cache is held to 1 GiB. Smart playlist changes sync only the devices that can see them,
nowPlayingno longer re-sends a playhead moving on time,queueUpdatedsends download progress at most once a second, a fullsearch3walk reads each track once, and the web UI redraws its queue only when it changes and holds fewer decoded tracks. - Watching another device's levels no longer rebuilds the link state on every frame. The state is read again only when the engine changes. Remote queues and track ids resolve in one query rather than one per entry,
devices.jsonis written whole, only when it changes and without device states, and a nearby dialer for a device that is not on this network stops after its backoff instead of retrying forever. Fixes for Bonjour callback handling and the device-id race between two processes are included. - The TUI's track list no longer repeats or skips rows when the library changes between pages. Queue credits follow library changes made by other processes. Now Playing no longer goes blank when it gets ahead of the queue, and the cover is retried after a partial download. A remote server's downloading tracks show their progress.
Internal
- Dependencies, tools and CI actions are on their latest releases. rusqlite 0.41, parking_lot 0.13, souvlaki 0.9 and sift-music 0.10 among them, AGP 9.5 and Gradle 9.8.2 for Android, and Node 26 for the Pulumi package. ratatui-image stays on 11.1 until 12.0 leaves release candidate.
- The cover slot tests run one at a time. Both use every one of the process-wide cover fetch slots, so in parallel one could starve the other and fail.
0.67.8
Fixed
- Dragging a large selection no longer freezes the Mac. A drag out of a list now carries its rows as one pasteboard item rather than one per row, so dragging every track in a large library to the queue is as quick as queueing it from the menu.
- The seek bar keeps up with the playhead. Resizing the window mid-track no longer leaves the bar behind the elapsed time until the next pause or track.
0.67.7
Security
- The log no longer records server credentials. A failed link to the server logged the address it dialled, API key or password token included; it now names the server alone.
Changed
- Preset, output and Play on are glyphs on phones and the TV. The preset's name ran the Apple TV's Now Playing row off the screen and crowded the phone's; each is now a glyph in the accent when it is not the default (a preset other than Flat, a renderer, another device controlled), with the names in the menus they open. The Mac's transport bar gains a named preset menu for the output playing, which had none on System Default.
- Rust 1.97 or newer is needed to build koan. The web UI's scripts are compiled with oxc 0.155, which requires it.
Fixed
- An Apple TV away from your network says so. Off its network and without a push, the TV is listed as out of reach with the reason; asking for it looks again and, if it is still away, says so in a couple of seconds instead of waiting on an address that cannot answer.
- Covers load on large remote libraries again. Scrolling the album grid fast could use up the app's 256 open files, leaving tiles blank and the link to the server reconnecting every few seconds. The engine now raises the limit when it opens, and a cover fetch no longer holds a database connection while it waits on the network.
0.67.6
Changed
- Asking an asleep device to play wakes it. A command for the device being controlled while it sleeps wakes it first and is sent once it answers, with a spinner on the play button meanwhile; opening kōan with it selected wakes nothing.
Fixed
- Playing bars for a controlled Apple TV. The bars on a controller now follow the clock the controlled device's level frames carry, not its state reports. A report taken while the output was still starting, during a rate switch's lead-in for example, could run ahead of the music for a whole track, and the bars stayed still.
- Searching no longer crashes the Mac app in the kōan theme. The suggestions panel counted towards the sidebar's minimum height, and with enough results that minimum outgrew the window and AppKit gave up laying it out.
0.67.5
Security
- Updated
ctutilsto 0.4.5
Changed
- The site links the TestFlight beta from the top. koan.rocks offers the iPhone and Apple TV beta beside Download for Mac, and in the iOS and Apple TV sections.
Fixed
- Releases reach the public TestFlight group. The release step that adds builds to it asked App Store Connect for the group in a way it refuses, and stopped when a build of the same version was already in beta review.
Internal
- The macOS CI jobs install just through mise.
setup-justfound no release for just on the macOS release runner, which stopped 0.67.4 publishing; mise installs the versionmise.tomlpins, as the Linux jobs that need other tools already do. - Releases go to the public TestFlight beta. A release's iOS and tvOS builds join the public TestFlight group and are submitted for beta review; builds from other pushes to main stay with internal testers.
- The App Store screenshots are in the repository. They sit beside the listing text in
apps/ios/store/screenshots/, andpush.py --screenshotsuploads them, so a submission can be rebuilt from the repository alone.
0.67.4
Changed
- The demo server resets daily. demo.koan.rocks resets at midnight UTC rather than every hour, which signed every device on it out, App Review's included.
Fixed
- Playlist edits refuse tracks that have left the library. Adding to, creating or replacing a playlist from the apps or GraphQL with a track the library no longer holds now fails with a message saying how many are missing, and writes nothing, instead of reporting success with a shorter playlist.
- The Apple TV app builds again. The server banner used the bar material, which tvOS lacks, so 0.67.3's tvOS build failed; on the TV it uses the regular material.
- The server banner on iPhone covers nothing, and its Sign In opens Server. It lay over the first rows of the page, which in Settings were Server and Account, and Sign In stopped at the Settings tab.
- The phone's own speaker can be chosen from Output. On iPhone the Output sheet has a row that opens the system's route picker, so a phone on a Bluetooth speaker or AirPlay can be sent back to its speaker without finding the AirPlay button in Now Playing.
0.67.3
Security
- tokio 1.54.1. 1.54.0 was yanked for RUSTSEC-2026-0384, a race in
tokio::time::Intervalthat can corrupt memory on the multi-threaded runtime.
Changed
- Pairing codes format as they are typed. The code box under Settings → Devices and on the server's
/pairpage turns what is typed or pasted intoXXXX-XXXXin capitals, the way the device shows it. - Signing out is a clean break. Signing out of a server, or in as another account, removes its tracks, the account's favourites, history and playlists, the queue and the downloads from the device; signing in again pulls them back. Local files, playlists read from files, EQ profiles and settings stay. The option to keep the server's tracks is gone.
Fixed
- Tall covers stay in their tile. A non-square cover no longer takes hovers and clicks meant for the record above or below it on the artist page and in the iOS grids.
- Now Playing keeps the artwork when paused from the lock screen. On iPhone, pausing with the app in the background published the track again without its sleeve, because iOS had emptied the bitmap cache; the artwork already published is now reused.
- Signing in again keeps the device's key. A device signed in again by invite or pairing now moves its public key to the new API key and retires the old one, instead of leaving the key behind on every link.
- Signing out stops a sync. A sync from the server in progress, or waiting to start, stops when the device signs out of it, rather than paging the old server and writing its rows.
- A banner when the server is out of reach. The iPhone, iPad and Apple TV apps say across the top of every page when the device is signed out of its server, its sign-in was refused, or its link is down, since other devices see it as unreachable and nothing on it said why.
- Changing servers replaces the library. Signing in to a different server removes the last server's tracks, playlists and downloads and clears the queue, so the new server's library is shown alone and its sync is not held up by the old one's. Local files stay, and signing in to the same server at another address keeps the library.
Internal
- App Store releases from a workflow.
store.ymlpushes the listing inapps/ios/store/listing.toml, iOS and tvOS alike, attaches the version's build and submits it to App Review, cancelling a submission still waiting;just ios-storedoes the same from a Mac and uploads screenshots and the App Review attachment. App Review signs in to demo.koan.rocks, and the tvOS app has review notes of its own.
0.67.2
Added
- Push and the relay, explained. A guide page with a diagram explains why kōan's servers push through the relay at
push.koan.rocks, what it sees and keeps, and how to turn it off. Every server example shows thepushsetting, the privacy policy covers the relay, and the protocol page describes the claim a play notification carries and the relay's text the phone shows. - Public file playlists.
library.public_playlistsmakes the playlists read from.m3uand.nspfiles in the library visible to every account, read-only, as Navidrome'sDefaultPlaylistPublicVisibilitydoes. Off by default. - A demo server. demo.koan.rocks runs kōan with a small, freely licensed library: sign in as
demo, passworddemo, from a browser or any of the apps. It resets on the hour.
Changed
- The site and guides describe 0.67. The homepage covers release types, the Link a device code, invite codes that lapse, waking an Apple TV and UPnP on iPhone; the devices guide lists the iPhone among the apps that play to UPnP amplifiers, and Organize's
%date%is documented as the original release date the library shows.
Removed
- The Pulumi chart's
demoandnameoptions. How a demo server is deployed is the deployment's own business;server.demois unchanged. A stack setting either option is refused.
Internal
- TestFlight notes wait on Linux. Setting a build's What to Test waits for App Store Connect to process the upload; that wait now runs in its own job on a Linux runner instead of holding the macOS one that built the app.
- Workflows are linted. CI runs actionlint, with shellcheck, over
.github/workflows, andjust checkruns it locally.
0.67.1
Added
- Demo server mode.
server.demomakes a public demo: a shareddemoaccount filled in on the sign-in page, whose password, keys and scrobbling no visitor can change. The Pulumi chart'sdemooption runs it with its music from an image and its state wiped every hour, andnamelets it sit beside another server in one namespace.
0.67.0
Added
- Link a device. Every account's page, on the web and in the apps' Settings → Account, opens with a QR code of its own invite, so a phone signs in by scanning the screen. Any account may now ask
koanInvitefor its own invite; inviting others stays an admin's.
Changed
- Push through kōan's relay. Every server, self-hosted or not, now wakes iPhones, asks them to play and updates their Live Activities through kōan's push relay at
push.koan.rocks, instead of only servers holding the developer's APNs key. The app registers with the relay, attesting with App Attest, and gives servers the relay's handles, never its device token; the relay decides what a phone shows.[push]is nowenabledalone (on by default;enabled = falsekeeps a server off the relay, and its apps ask for no notifications), thekoanApnsextension iskoanPush, and the APNs key settings and/push/coverare gone. Device tokens the server kept are dropped. - Albums are dated by their original release. Where a file is tagged with
ORIGINALDATEor a server sendsoriginalReleaseDate, a reissue sits at the year the record came out, in tiles, sorts and artist pages. The next scan and sync read every file and album again to fill it in. - Organize's
%date%is the date the library shows. With albums dated by their original release,%date%is the original release date where one is tagged, for files in the library and files it does not know alike, so a preview and the move it authorises agree.
0.66.7
Added
- Release types. Album tiles name a record's release type (EP, Single, Live), and artist pages group records under Albums, EPs & Singles, Live, Compilations and Other releases. Read from MusicBrainz release type tags or an OpenSubsonic server's
releaseTypes; the next scan and sync read every file and album again to fill them in.
Changed
- The device being controlled is named in a badge. On the Mac's transport bar and the Apple TV's Now Playing, so it is clear that play acts there.
0.66.6
Added
- UPnP on iPhone. The iPhone finds UPnP and DLNA amplifiers on the network and plays through them, as the Mac and Android do. Apple's multicast entitlement, which finding them needs, is now granted to kōan.
Security
- An invite's QR code in the Mac, iOS and Android apps lapses after ten minutes. The server sends a short-lived
qrTokenwith each invite and the apps draw it, as the web UI does; the emailed link keeps the week-long token. Against an older server the apps show the week-long token as before.
Internal
- Push relay protocol. The protocol reference specifies the relay at
push.koan.rocks, which forwards pushes to Apple for kōan servers that do not hold the developer's key: servers hold sealed handles instead of device tokens, and the relay writes the whole of what Apple is sent. The relay itself lives in radiosilence/koan-push-relay. Nothing uses it yet. - TestFlight uploads run in parallel. iOS and tvOS each upload from a runner of their own, so a release no longer waits for one platform to finish before the other starts.
0.66.5
Security
- An invite's QR code in the web UI lapses after ten minutes. It carries a token of its own, so scanning the code off a screenshot or recording of the users page no longer signs a device in for the week the emailed link lasts. The link shown beside it keeps the week-long token.
0.66.4
Added
- An Apple TV wakes from any of your devices on its network. Set up once with the code the TV shows, from the TV's menu in Play on or straight after signing it in, and choosing the TV turns it on and opens kōan there, over the protocol the Remote app uses. The server keeps the pairing for the account, so it needs no push key and works for self-hosted servers; the old AirPlay knock, which woke nothing on current Apple TVs, is gone.
Internal
- The web UI's scripts are ES modules, compiled by Cargo. koan-server's build script strips the types from
scripts/*.tswith oxc as it builds, so no compiled JavaScript is committed andcargo buildandcargo install koanneed no JavaScript toolchain; TypeScript still typechecks the scripts (just js).ui.tsandshare.tsimport the player as a class fromkoan/player, which an inline import map names at its versioned URL, so a cached old player is never paired with a new page script; the CSP allows the map by its hash.
0.66.3
Security
- Distrusted emSign certificates are refused. rustls-webpki 0.103.16 and webpki-roots 1.0.10 reject paths through the emSign intermediates whose private keys are public (RUSTSEC-2026-0381, -0382, -0383).
Changed
- One account of who a track is by, on every platform. Artist credits, whether a row names its artists, and which rows sit under one record heading are now decided in koan-core and drawn by every app, the TUI and the web UI. Grouped playlist rows name their artists only where they differ from the record's, playlists show singles as one row, album pages decide per track, the transport and downloads link each credited artist, and system now-playing, share pages and share downloads use the credit as it reads.
- The album title under a tile is a link like the names beside it. On the Mac it shows the link pointer and a tooltip, as the artist name under it does.
Fixed
- The terminal queue shows featured artists. A grouped track row names its artists whenever its credit differs from the record's, as the apps already did; koan-core now makes that decision for every client.
- A tuning's page adds it to the device's filters. On the Mac and iPhone, an EQ's page offered only "Use for", which made a tuning the device's correction in place of the real one, and always acted on the output in use. It now offers one action by the EQ's role and what the device plays, on the device the page was opened for, as Android does.
- Subsonic playlist writes refuse a song they cannot find.
createPlaylistandupdatePlaylistanswered ok while dropping any song id that named no track; such an id now fails the call with error 70, naming it, and nothing is written.
Internal
- Dependencies updated to their latest releases. Includes lru 0.18 → 0.19 and sift-music 0.6 → 0.8.
- The web UI's scripts are TypeScript.
ui.js,player.jsandshare.jsare compiled fromcrates/koan-server/scripts/*.ts, typechecked by TypeScript 7's native compiler and stripped of their types by Node, so the committed JavaScript reads as the source does andcargo buildstill needs no JavaScript toolchain.just jsbuilds them; CI fails a build whose output is stale. - Release runs keep their image retag. A release's
container-mainjob queues in its own concurrency group, so a third queued run can no longer cancel it and end the release cancelled.
0.66.2
Fixed
- Number pads on iOS can be closed. The cache limit and the browse filters' years use the number pad, which has no return key; a bar above the keyboard now commits the figure and puts the keyboard away.
- Queue rows keep their artist line steady and show featured artists. In a grouped queue a track names its artists whenever its credit differs from the record's, so "Big Data, Kimbra" shows under a Big Data record, and hovering a row on the Mac no longer reveals an artist the row leaves out.
Internal
- The image's
maintag no longer moves on a registry or API error. Only a missing tag, label or commit lets it retag without the ancestry check.
0.66.1
Added
- Features on in the web UI. An artist's page lists the records they feature on below their own, as the apps' artist pages do.
- Tooltips on truncated text in the web UI. Any title or credit cut short by an ellipsis shows its full text on hover, on the web UI and the share page.
Changed
- The site and guides describe 0.66. Android and the Apple TV app are on the homepage and in the install steps, with the TestFlight beta for iOS and tvOS; the terminal UI's pages and keys, the configuration and CLI references, and how local and server tracks are merged now match what the code does.
- The container image is built from the release binaries, for amd64 and arm64. Linux binaries are compiled once per architecture and both the image and the release downloads are made from them. The image now runs on Debian 13 (trixie), whose glibc those binaries need. The Mac release build starts alongside the checks, so a release finishes sooner.
- Shorter paragraphs in the guides. The server, terminal UI and headphone EQ guides, among others, are split into short sections and lists, and the homepage says to make the first admin straight away, since until one exists the setup page lets whoever reaches it first become admin.
Fixed
- Scan progress counts every file first. A scan decides which files it will read in every library folder before reading any, so its total stays fixed and its bar never jumps back. Files whose tags cannot be read count as read, so the bar ends full, and progress is reported for each batch rather than every 50 files.
- Web UI: the library scan from a wide screen. Admins find the Library page, with Rescan and the progress of every scan, in the sidebar as well as the phone's tab bar, and a running scan shows a bar that fills as files are read.
Internal
- The web UI and share page render through askama templates. Their HTML was built with
format!and anescape()call on every interpolated value, where one missed call was an XSS hole; templates are checked when the crate compiles and escape their output by default. Copy buttons, the invite's share sheet and the search address are Datastar attributes rather than script. This is how slsk-mcp renders its UI, so patterns move between the two. A lefthook pre-commit hook (just hooks) runscargo fmt. - CI runs only what a change touches, behind one
Checksgate. Shared inputs such asCargo.lockcount for the apps only when the change reaches them, so a web UI pull request no longer holds a macOS runner. Delivery runs after the gate in the same workflow and ships what CI built: TestFlight and Google Play on every push that changes the apps, the full release on a version bump. - Release jobs read one answer for whether a run releases. The Mac build and the publishing steps can no longer disagree, which could skip a release without a failure.
- CI/CD hardening. The image's
maintag no longer moves backwards when a release run finishes late, freeing runners for a release never fails it, a push whose base cannot be worked out runs every check, and a retried release passes a package version that is already published.
0.66.0
Added
- Invite QR codes in the web UI. The invite panel shows the link as a QR code, so a phone beside the screen can join by scanning it.
- Sort albums by year, oldest first. Every album browser now offers the year order in both directions, so a filtered listing can be played or queued in the order the records came out.
- Playlists reorder by drag on iOS and Android. Press and drag on iOS, in the Playlists page and the iPad sidebar; Edit on Android's Playlists page puts a handle on each row. The order is kept per device, as the Mac's is.
- Protocol reference. A Protocol section in the docs specifies the link between the apps and the server, nearby connections, pairing and invites, each of kōan's OpenSubsonic extensions, and the rules that keep old and new versions working together, for anyone writing a client or server that speaks it.
- Download ahead and no cache. Settings → Downloads chooses how many tracks past the playing one are fetched, from none to ten or the whole queue, so a long queue no longer downloads in full unless that is wanted. Keep downloads is now a choice of a limit in gigabytes, no limit, or only what plays next (
cache_limit = "0"), which deletes played tracks while keeping downloads asked for and favourite albums. - Invite QR codes in the apps. The Mac, iOS and Android apps show an invite link as a QR code beside the ways to send it, so a phone in the room can join by scanning it.
- Track info from any track's menu. On the Mac, iPhone and Android, the menu of every track row (library, search, album pages, history, the queue and playlists) has Info…, which shows what each of the track's sources says, as Now Playing's info view does, with every value selectable for copying.
- A track's path on the server. A kōan server sends admin accounts each song's
path, relative to its library folder, as Navidrome does, and the apps keep it with the server's copy of the track, listed in its info as "Path on server". When a track plays the wrong file or appears twice, the path says where it comes from. Other accounts are not sent paths. - Android: lyrics source and invite mail. The lyrics panel names where its words came from, and the invite dialog adds Open in Mail and Copy email, the formatted email for pasting into a message written elsewhere.
- Android EQ editing matches the iPhone's. The EQ page edits any device's EQ as its chain of correction and filters, with presets saved over, reverted or saved as new, and filters alone; stages open a picker with targets and ways to add more, and an import started there goes into that chain. Find a measurement (squig.link, a file or pasted text), splitting a baked correction, targets and made-against suggestions, layers and groups, sync scope, Save as copy and Reset to file, and Manage EQ with Recently deleted are there too.
Security
- Pairing guesses are limited, and undelivered keys revoked. An account that tries ten pairing codes in a minute that no device is waiting with is refused further codes until the minute is out; a pairing link still works. An approval is confirmed only once the key has been written to the device, and is otherwise revoked and reported to the approver as failed. A device that stops answering pings is dropped after 75 seconds instead of holding its pairing open for ten minutes. Looking a pairing up and declining it now need the same credentials as approving it, the account's own password or an API key, and the apps say so, or that too many codes were tried, instead of reporting that no device is waiting.
- The TUI no longer serves the API unasked.
koanstarted the GraphQL/Subsonic API on 127.0.0.1:4000, and with no accounts any local process could claim it through/setup. It now serves only with--api,--port,--bind,--subsonicor--playground, or[graphql] enabled = true; set that to keep the old behaviour. When it does,/setupstays closed and the first admin comes fromkoan auth setup. Headless mode is unchanged.
Changed
- Lossy tracks show their bitrate. Track rows read "MP3 320 kbps" rather than "MP3 44.1 kHz", since the encoder setting says more about a lossy file than its sample rate. The transport badge keeps the rate, which is what the device is matched to.
- Notifications only from servers that can send them. The iOS app asks to show notifications only on a server listing
koanApns, which a server does when[push]holds an APNs key. Apple accepts pushes only signed by the app developer's team, so on any other server the prompt was noise. - Record, artist and playlist headers on the Mac put Play and Shuffle on top. They sit level with the sleeve, with the title on a line of its own below them, then the credit, then the lesser actions.
- Android names its artists and albums as links. Track rows, record headings, history, downloads and search open the artist or record a row names, as the Apple apps and the web UI do, and every detail line reads "Artist · Album".
- Each artist of a collaboration is its own link on Android. Album headers, tiles, track, queue, playlist and history rows, record headings and Now Playing link every credited artist separately, as the Apple apps do, and Go to Artist menus list each of them. The playlist and history menus gain Go to Artist.
- The web UI links each artist of a collaboration. A credit such as "Orchestre Tout Puissant Marcel Duchamp × Frànçois & the Atlas Mountains" links each named artist separately in album headers and tiles, track, queue and history rows, search, playlists, track properties, the playback bar and Now Playing, as the apps do, where it used to be one link to the artist it is filed under.
- The TUI reaches each credited artist. Where a record or track is credited to several artists, its menu offers "Go to" each of them, and
A, the queue's "Go to artist" and the artist link of a track or record ask which, rather than opening the combined credit's page. server.urlis the server's one address, and a server needs it.koan --headlessrefuses to start withoutserver.url(KOAN_SERVER__URL), the address clients reach it at; share links, invites, MCP's sign-in, push covers and the Last.fm callback are all built on it, and invites no longer fall back to the address a request came in on.sharing.public_urlis still read whileserver.urlis unset, with a warning, and will be removed in a later release; a server with neither must set one before upgrading. The server gives its address onping, and signed-in apps identify it by that address, so devices that reach one server at different addresses recognise each other on the local network.- Records without artwork show the kōan ensō on Android. The album grid, rows, album page, Now Playing, the mini player and the queue draw it on the sleeve's ground, as the Apple apps do, where Now Playing and the mini player drew nothing. The grid's heart sits on a small square so it reads over any cover.
- Android page headers follow the iPhone's. The queue, library and settings tabs drop their repeated titles; record, artist and playlist pages share one left-aligned header, with the record's artist as a plain line and its heart labelled "favourited". Track rows show their hearts, a record's sleeve opens full size, and a playlist offers Play Next, Add to Queue and, per entry, Favourite.
- Android browses and keeps history as the iPhone does. The track browser filters, albums sorted Random reshuffle from their own button, the shelves have a select mode, search titles its results, and history lines its times up in a column in the phone's clock and offers the full track menu.
- Covers for records without art. The server answers
getCoverArtfor a song, album or artist without artwork with the kōan ensō on a dark square, at the nearest served size, as Navidrome answers with its own placeholder, so every client has an image to draw; kōan's own apps recognise it and keep drawing their own. An id the library does not hold is still an error.
Removed
- The sleep timer guide page. One menu does not need a page.
Fixed
- Disc, track and playlist numbers fit. The number column in the queue, playlists and album pages is sized to the widest number in the list, measured in its font, so "2.03" and playlist positions past 99 are no longer cut off in the kōan theme or at larger text sizes.
- Queue rows overshooting onto the sidebar no longer duplicate. On the Mac, rows dragged out of the queue and dropped on the sidebar's Queue row are ignored instead of added to the queue a second time; drags from anywhere else still add there.
- Mac playlists move when dragged down. A playlist dropped on a row below it takes that row's place; before, a drag of one row down did nothing and longer ones landed a row short.
- Downloads on iPhone lay out properly. The artist and record now sit on their own line, where they squeezed the status and Show in Library down to a glyph wide and stretched every row.
- The iPhone mini player is one tap target again. Its artist and record are plain text rather than links, which made the bar hard to tap without leaving the page; Now Playing keeps the links.
- Signing in with a password loads the library on the Mac and iPhone. It synced only when joining with an invite, so a fresh sign-in showed an empty library until a manual sync.
- Signing out clears the queue and downloads. The queue held tracks from a server this device can no longer reach, and its transfers, queued or running, kept going; both are dropped on signing out, in the apps and the terminal UI alike. The synced library still stays.
- Commands from newer versions are answered. A device, a nearby device or the server that cannot read a command sent with an id now refuses it, so the sender is not left waiting and the server no longer takes the device for gone. Pairing passes over messages from a newer server instead of failing.
- Playlists reorder by dragging again. On the Mac and iOS a row dragged within a playlist was added as a copy rather than moved; it now moves as a queue row does, a heading taking its whole run.
- Android playlist rows reorder more than once. After one drag in a playlist, the next moved nothing on screen and could undo the first move on drop; every drag now lands, and a cancelled drag leaves the order as it was.
- History's times fit. The time column in History is sized to the widest time the current locale prints, measured in its font, so 12-hour times are no longer cut off in the kōan theme or at larger text sizes, on the Mac, iPhone, iPad and Apple TV.
- The invite sheet on iOS stays open. It could close as soon as it appeared, when the account list reloaded behind it; it now hangs off the page rather than a list row.
- Every album has a disc total. It is the highest disc among the album's tracks, or a larger total the files are tagged with, so the web UI, GraphQL and the terminal UI report it for synced libraries and for files tagged without one. The next scan reads every file's tags again.
- Move here wakes its destination, and only offers devices on the same server. A device asleep is woken as choosing it does, on the network and then with a background push, before the music is sent, rather than getting the music only as a notification to tap. One of the account's devices that has since signed in to another server, as it says on the local network, is no longer offered the music, since it could not find the tracks.
- Lyrics credit their source after caching. Lyrics read back from the cache were credited to "cache"; they now keep the source they were fetched from, shown as LRCLIB on the Mac, iPhone and Android. GraphQL's
Lyrics.sourcegives the same credit (LRCLIB,Embedded,Sidecar) where it gave the variant's name (Cache,Lrclib), and is null for a source the server does not recognise. - A tap on a record's title in the Android album grid opens the record. The artist link under it had a touch target reaching up over the title, which opened the artist instead; the same held for the line under any row's title.
- Changing server leaves the last one's waiting plays behind. Plays, forgettings and hearts queued for one server were sent to the next one signed in to, so a history clear could reach another koan server. Signing in elsewhere now drops them, and the app no longer asks a server without device relaying to relay lock-screen commands.
- Android queue menus act on the queue. A queue row's menu plays from that row and removes it, as the iPhone's does, rather than replacing the queue; a record heading removes its run; the select bar adds Add to Playlist and Favourite, and bulk Remove and Forget on playlists and history ask first.
- Settings shows koan's accounts and EQ sync only on a server that has them. People and an EQ's Sync choice no longer appear against Navidrome and other servers, and a feature a server lacks is explained as an old kōan server or as one that is not kōan, rather than always as an old one.
Internal
- One Linux CI job for clippy and the tests. They share build scripts and proc-macros, so one runner and one cache compiles those once per run, and the cache holds one entry instead of two.
- Pairing documented against RFC 8628. The protocol reference maps pairing onto the device authorization grant and says why its protocol differs: an API key rather than an OAuth token, servers without
server.url, and a pushed outcome. - Protocol schema. JSON Schema for the link, pairing and nearby messages is generated from the Rust types into
docs/reference/protocol/schema/byjust protocol-schema, and the test suite fails when the committed files fall behind the types. - Android walk.
just android-walkscreenshots every page of the Android app on an emulator, in both looks and appearances, against the generated library the iPhone checks use, so the two apps can be compared page for page. - Faster Apple CI on pull requests. The Apple job builds
koan-ffionce in the dev profile and reuses it for the macOS tests, the app build and the iOS typecheck, which run side by side. Clippy, the full suite and tvOS run on main, which also saves the cache pull requests start from, and release builds wait for a release. Jobs run only for the paths they cover: an app-only change skips the Linux Rust jobs, and an Android-only change skips macOS.
0.65.1
Added
- Jobs over a GraphQL subscription.
subscription { jobs { … } }sends the server's jobs as they start, move and end, scans included, so a client can show a scan without polling. Admins only.
Changed
jobandjobsare admin-only. Only admins can start a job, so only they read them; a non-admin's query is now refused.
Fixed
- Every credited artist links from the queue and playlists. A track or record credited to several artists links each of them on the Mac's and iOS's queue and playlist rows and record headings, as album and artist pages already did.
- Queue rows drag onto playlists again on the Mac. A track dragged out of the queue lands on a playlist or New Playlist, and a record's heading brings the whole record; since the queue became a table they carried nothing outside it.
- ⌘A selects everything in the Mac's lists. Select All in the queue, playlists, track lists, favourites and search held only the row selected before it, so deleting or dragging afterwards acted on that one row.
0.65.0
Added
- Scans the server runs by itself show in the web UI. The Rescan section on the Library page shows the scan at start-up, on a change in the library folders, the periodic one and one for a newly added folder, with what started it, how many files it has read of those it found to read, and how it ended. After an upgrade that empties the scan cache the start-up scan reads every file, which used to run for a long time with nothing to show for it. Over GraphQL they are
watchjobs with areason.
Changed
- Artists and albums link the same way everywhere on macOS and iOS. Every track row, the downloads list, the transport bar and the mini player show "Artist · Album" with both names linked, and queue and playlist album headings link the record and its artist. Queue items and playlist entries carry the artist ids those links need.
- Each artist of a collaboration is its own link. On iOS and macOS a credit such as "Orchestre Tout Puissant Marcel Duchamp × Frànçois & the Atlas Mountains" links each named artist separately in album headers, track and history rows, album tiles and Now Playing, where it used to be one link to the combined credit. Go to Artist menus, tvOS's included, list each artist.
- Web UI links every artist and album name. Track rows on every page, the queue, album tiles, the playback bar, Now Playing and track properties link each name to its page, so a name behaves the same wherever it appears.
Removed
- No Intel macOS build of the CLI. Releases ship
koanfor Apple silicon only, as the app already was; the Homebrew formula now requires arm64. Building it held a macOS runner on every release for machines whose newest supported macOS is behind the app's minimum.
Internal
- Release script recuts a stale branch.
scripts/release.shdeletes a release branch whose PR was closed or merged, locally and on origin, and cuts it again from origin/main; a branch with an open PR still stops it. - Credit parts for every front end. koan-core cuts an artist credit into its credited artists' names and the text joining them (
helpers::credit_parts), and koan-ffi's albums and tracks carry the parts, so each app links every artist of a collaboration from one implementation. - The pre-push hook only formats. Clippy no longer runs before every push; CI runs it on every pull request, so a push is not held up running it locally.
- One macOS runner per CI run. The macOS checks, the app builds and release packaging share one job, and TestFlight uploads iOS and tvOS from one, tvOS on releases only. Pull requests no longer queue behind each other for the few macOS runners.
0.64.1
Added
- Track properties in the web UI. A track row's menu opens its properties: each source's tags and format, its uids and MusicBrainz ids, and for admins the file's path on the server, for working out why a record appears twice or the wrong file plays.
- Collaborations are listed under each artist. A record or track whose tags name its artists one by one (
ARTISTS,ALBUMARTISTSand MusicBrainz artist ids, or OpenSubsonic'sartistsandalbumArtists) appears on every credited artist's page and in the artist list, while keeping its credit as it reads. The koan server publishes the same lists to Subsonic clients and in GraphQL. The first scan and sync after upgrading read every file and server entry again so existing libraries pick them up. - Rescan from the web UI. Admins can rescan the library from the foot of the Library page, optionally reading every file's tags again, which is how a remote server picks up tags an upgrade starts reading.
triggerScan(reread: true)does the same over GraphQL.
Fixed
- Multi-disc records show their discs on the Mac and iPhone. On an album page, tracks spanning more than one disc number get a heading per disc and show their own numbers, rather than one run numbered by position. In the queue, a record whose tracks run past disc 1 numbers them by disc and track ("2.03"). Both read the tracks' disc numbers, so they work where the files give no disc total.
Internal
just releaseresolves the lockfile online and refuses a release branch that already exists on origin. The offline lockfile update failed on a machine whose cargo cache lacked a locked dependency, after the branch had been made and the version bumped.
0.64.0
Added
- Switch the terminal UI's EQ without leaving the page.
Bbypasses the EQ and puts it back, so a change can be heard with and without it, and theEQlabel in the transport bar, the signal path'sdsprow and the curve on Now playing open the EQ list when clicked. - More of the apps' actions in the terminal UI.
Nputs a record, track or tree node next in the queue;fandHfavourite a record and its artist (queued for the server as in the apps), with a heart on the tile and in the album and artist headers;ishows what the library holds of any listed track;dandudownload a record or track to this device or remove the download; and Settings gains offline mode,scan libraryandsync now. - Playlists in the terminal UI. A Playlists page and a page for each playlist, with play, shuffle, create, rename, delete, and moving or removing tracks;
wputs a record, track or queue selection into a playlist from any page, andWsaves the queue as one. They are the apps' playlists, pushed to the server as the apps push them. Pages are now numbered1to9, with Playlists at6, so Recent, History and Settings are7,8and9. - An actions menu in the terminal UI.
m, or⋯ actionsin the heading, opens a menu of what can be done with the record or track under the cursor on the browsing pages, album pages and History, so that play next, favourites, playlists, downloads and info can be reached with the pointer alone; the queue's menu gains go to the record and artist, add to a playlist and downloads. - Playlist undo and a queue that follows. The playlist page undoes and redoes edits (
Ctrl+Z,Ctrl+Y, or the buttons under the name), and while the queue is exactly a playlist, adding, removing or moving tracks in it changes the queue too, as in the apps. - Browse filters in the terminal UI.
Ctrl+F, orfiltersin the heading of Albums, Favourites and Recent, opens a panel for lossless, downloaded, codec, genre and decade, the same narrowing the apps' browser offers. - Search in the terminal UI. A Search page on
0searches the library as you type and lists artists, records and tracks, with open, play, queue, favourite and playlist actions by key or click, as the apps' search results do. - More settings in the terminal UI. Settings lists the library's folders with
add folderand a way to remove one (which forgets its tracks), and, signed in to a server, the sync interval, keeping the queue on the server, parallel downloads and the download cache limit. - Terminal UI: album covers load faster. Thumbnails are kept on disk, shrunk to what a tile draws, in a 256 MB cache that drops the least recently used first, so a cover seen before no longer needs the audio file read and decoded again.
- New EQ and Mono/Stereo on Android. Android can make an EQ from the Flat, Bass boost, Warm or Bright starter, as the Apple apps do, and switch an EQ of bands between one list for both channels and one per channel. Going back to Mono when the two channels differ asks which to keep.
- Artist pages separate an artist's own records from the ones they feature on. The records they are the album artist of come first, and Play, Shuffle and Queue on the artist act on those only; the compilations and other artists' records they are credited on follow under Features on, with their own play and queue, in the macOS, iOS and Android apps.
- Browsing in the terminal UI as in the apps. Albums, Artists and Tracks are the apps' browsers, with their filters and sorts, and Favourites, Recently played, Downloaded and Search are the apps' shelves of artists, albums and tracks. Every row offers the apps' menu, and playing from a row asks before replacing a queue that has music in it.
- A Downloads page in the terminal UI. It lists the transfers from the server, running first, with their progress, rate and size, then the ones that finished or failed.
- An EQ page in the terminal UI.
Eopens it: what the output plays through, with its correction and EQs, plotted together, and the presets to choose from. - The terminal UI's shell follows the apps. The sidebar lists search, the queue and Now playing, the library's pages, the playlists with a row for a new one, and settings, with scans, syncs and downloads shown at its foot while they run. Every page has a toolbar with back, forward, its name and count, and its controls, each of which is also a key; artist and album names are links wherever they appear.
- Theme tint. Settings → Appearance in the kōan theme sets how far the wash is darkened in dark mode, or lightened in light, to keep text over it readable: lower lets more of the sleeve's own colour through. On the Mac, iPhone and Android (
appearance.wash_tint).
Changed
- A device out of reach stays controlled, and says so. A command for the device being controlled that cannot reach it now fails and says why, instead of playing on this device and dropping control; pick this device under Control to play here. The Control button shows a warning sign while nothing can reach the controlled device, before anything is pressed. Control Centre, the media keys and Android's media notification follow the controlled device's track changes even for tracks this library does not have. On a phone controlling another device, a call, Siri or unplugged headphones no longer pause or resume that device, and Android no longer takes audio focus from the phone's other apps.
- The Mac album grid keeps up with ProMotion. Covers are fetched ahead of the scroll, towards where a flick will land, and decoded off the main thread in the format the display draws, so sleeves are on their tiles before the tiles scroll in and a fast scroll holds 120 fps.
- The terminal UI's keys mean one thing on every page. Space plays and pauses everywhere,
tpicks rows out on the queue and History,vswitches a page's view, andVopens the visualiser picker, whose first choice is off. The page numbers run down the sidebar in order: Recent is now6, History7and Playlists8. The queue has no separate edit mode; its cursor and selection always work. - The terminal UI's transport and Now playing follow the apps. The transport has the apps' controls and links to the artist and album, and collapses to its own lines when there is nothing to show above them. Now playing lays out the cover, the signal path, loudness, the spectrum, lyrics and the EQ curve.
- The terminal UI's queue and playlists follow the apps. The queue and a playlist's page share the apps' rows and toolbar, grouped by album or a row per track, with each row's menu, and the playlists page lists playlists as the apps do.
- Settings and History in the terminal UI follow the apps. Settings has the apps' sections (library, server, account, people, playback, EQ, devices, integrations and terminal) beside a pane, and History's plays can be picked out and acted on together.
- The queue and playlist layout is one toggle. The album glyph is lit while rows are grouped by album and dimmed while they are one per track, taking one toolbar slot instead of two on iPhone, the Mac and Android.
- The Mac follows the kōan theme in three more places. The toolbar filter is the sidebar search's field with a lowercase prompt; album, artist and playlist pages and the library's own pages share one header, with the count under the title; the queue's undo and redo are ink like the controls beside them. Through the same header, History on iPhone puts its count under the title, and on Apple TV the playlist and History titles match the album page's size.
- The record wash is softer. It blurs a sleeve twice as far, so hard, high-contrast shapes no longer show as edges across the window.
- kōan theme. Most of the views that checked the theme themselves now take its value roles (
KoanTheme.metric,style,ground,UIFont.role,hasTextSize), so a look's values are set where the role is. Nothing on screen changes.
Fixed
- Terminal UI: smaller glitches. The transport's little spectrum no longer repeats the big one beside it, History shows plays as they are recorded, and
ain the Artists tree appends instead of also starting playback, as its hint says. - Terminal UI: scrolling the album grid with cover graphics. Covers out of view are now dropped least recently drawn first, instead of the whole set at once, so scrolling a long library no longer redraws and resends every visible cover. Dropped kitty covers are also deleted from the terminal, which kept them in its image memory until now. Over SSH covers are sent compressed where the terminal supports it, and kitty images now draw inside tmux. The minimum supported Rust version is 1.90.
- Terminal UI: a device like the apps. It is listed under Control on other devices and answers them, and
Copens Play on, to control another kōan, see its queue and transport, and move the music between them. Settings lists who is connected. While it controls another device, everything it shows and every key acts on that device, the media keys included, and a device out of reach is an error rather than music starting here. - Terminal UI: smooth album grid scrolling with cover graphics. While the grid moves, covers are drawn in half blocks, and they turn back into images once it stops. Kitty draws an image as a placeholder in every cell, and a screen of them moving each frame was more than terminals kept up with.
- Terminal UI: covers sized to the terminal's cells. Covers and the tiles around them take their shape from the cell size the terminal reports instead of assuming a cell twice as tall as wide, so a tile no longer has a blank row under its cover and does not change height when it turns from half blocks into an image. Stopping after a long scroll turns the grid's tiles into images a row at a time rather than all in one frame, and iTerm2 keeps its images while scrolling.
- A cancelled scan is reported as cancelled. A Cancel that landed between tag reads could end the scan as though it had finished, and then remove stale tracks and import playlists for it.
- Mac and iPhone details. The AirPlay icon's arcs run down to the triangle, so it reads as AirPlay. Popovers and menus at the right of the Mac window open leftwards and stay inside it. The full-size cover on iPhone and iPad fits the screen instead of being cropped.
- Playlists fill in when the library catches up. A server playlist pulled while the library lacked some of its songs kept only the songs the library had, and stayed that way until someone edited it on the server. kōan now remembers which songs were missing and puts them into their places, in the server's order, on the first sync after the library gains them, without asking the server for the playlist again. A playlist edited here in the meantime keeps the edit, and its push still leaves those songs on the server.
- Apple TV: focus in panels and after share codes. A choice opened from a row, such as an EQ's preset, takes focus from the page behind it as soon as it opens; it was drawn a point tall until it had measured itself, with nothing in it to focus. Closing a share code returns focus to the row it was shared from rather than the page's filter field, and the filter panel's year fields read "from" and "to" like its other labels.
- Terminal UI: fixes from review. History, the playing cover, the track info popup and Now playing's EQ curve no longer load on the frame thread, so typing in History's filter and changing track no longer stutter. Settings reports a setting it cannot write, asks twice before removing a library folder, applies a new download cache limit at once, and no longer offers "queue on server", which only the apps can turn on safely. Esc cancels History's "forget all", the output chooser no longer crashes on an accented device name and scrolls a long list, the 256-colour theme maps to the right colours, wide characters no longer misalign the transport and lyrics, and the queue and the other lists share one track info popup. Forgetting several plays in a row in History forgets each one, and a failed read no longer stops the page following new plays. The EQ curve stays up while unrelated settings are written. A grey sleeve with a small coloured logo leaves the accent mint, an accent too dark to read as text colours only marks and bars, and turning record colours off or on applies at once. A cover missing from a file still downloading is read again once it arrives. Wide device names no longer overflow the output chooser, and the choosers and menus keep their scroll position while the cursor moves within view. Shuffle on the browsing and artist pages plays shuffled, dragging a selection in the queue no longer sends it to the end, favouriting an album from its queue heading favourites the whole album, and a read-only playlist's page no longer offers to move or remove tracks. A server that is down or offline mode no longer holds up local covers, and the track info popup shows only its own track's cover.
- iOS: less running in the background. Pausing after a call or another app had stopped koan's audio no longer leaves the player waking twenty times a second and holding the audio session, and the next play is heard. An app iOS launches straight into the background to take a push no longer behaves as though it were open, with the link, nearby devices and syncing running until it was next opened and closed.
- Picked records keep their order, and browsers keep their filters. On the Mac, records dragged, played or queued together arrive in a predictable order: ⌘A and ⇧-ranges in the order the page shows them, single picks in the order they were picked, and dropping several onto the queue or a playlist no longer scrambles them. Leaving a browser and coming back, through the sidebar or back and forward, finds it with the filter it was left with, on the Mac and iOS; on the Mac the track and history lists also return to where they were scrolled.
- A scan that cannot write waits for its tag readers. When a scan's database transaction failed to begin, it returned while its readers were still reading tags, so the next scan could overlap them on the same files.
- A scan that loses a batch removes nothing. When a batch of a scan failed to commit, the scan went on to remove tracks whose files it had not found, so a file moved into the lost batch, even from another library folder, lost its track along with its favourites and play history. Progress now reports a track only once its batch is committed.
- Apple apps: a change of network reconnects at once. On macOS, iOS and tvOS, moving between Wi-Fi, a cable and mobile data now renews the connections to the server and retries one that was not answering, as Android already did, rather than waiting for a stalled read or a backoff to run out. A network change on a phone in the background, or with nearby devices turned off, no longer starts looking for nearby devices again.
- EQ import keeps what it saved. Importing several presets keeps them imported and playing when their group cannot be made.
- Terminal UI modes, pointer and keys. Closing an overlay returns to where it was opened; a picker closes before its items arrive; clicks no longer reach what the fullscreen visualiser, the help or a menu's border hide; a double click must land on the same row twice; a paste goes into the text field that has the keys; and the session is saved and Now Playing updated off the frame rather than on every one.
- Changing the look no longer stalls the app on a slow disk. Appearance settings are saved in the background, in the order they were changed.
- Mac: durations of an hour or more show in full in track and queue rows, rather than truncating to "1:02:…".
- Artist chips, empty sleeves, the search row under the pointer and the downloads bar are drawn in the kōan theme's tokens, and the chips square, rather than in the platform's grey.
- iPhone: VoiceOver treats the kōan theme's tab bar as a tab bar, as it does the platform's.
- API key row: "this device" in line with the key's name. In the account settings, in the kōan theme, the label on the key this device signs in with was in body type and sentence case and sat between the key's two lines; it is now in the smaller control type and lowercase, on the name's baseline, as the theme sets out for a value at the end of a row. The revoke button lines up the same way in both looks.
0.63.0
Added
- Album and artist pages in the terminal UI, and links to them. Artist and album names under a tile, in the queue's album headings and on the album page open the page, and
AandOdo the same from the keyboard. The key hints along the foot can be clicked, queue rows have a⋯menu button, and the browsing pages' scrollbars can be dragged, so nothing depends on a right click. - Artist pages in the terminal UI show the artist. A photograph and the opening of their Wikipedia article sit above the records, with play and shuffle buttons and a link to the article. The wheel and a draggable scrollbar now work on the album and artist pages and on the Artists tree.
- Covers in the terminal UI are drawn as images where the terminal supports the kitty or iTerm2 protocol, and in half blocks elsewhere.
playback.art_graphics = false, orIin the TUI, keeps half blocks. Ein the terminal UI chooses the EQ. It lists the profiles with the one in use marked, and plays the output through the one picked, askoan dsp assignand the apps do.- A Now playing page in the terminal UI. The cover, the signal path (source, output, DSP, and whether the stream is bit-perfect), level meters, the spectrum, lyrics, and the active DSP profile's frequency response. The transport bar carries a small spectrum.
- The terminal UI has pages. Queue, Now playing, Albums, Artists, Favourites and Recent, reached by number keys,
Tab, a sidebar or a tab bar, with back and forward like a browser. Albums, Favourites and Recent show records as tiles of cover art or as rows; the layout follows the terminal's width. Everything works with the keyboard and with the mouse. - History and Settings pages in the terminal UI. History lists every play under the day it was played, with the artist and record as links, a filter, and forgetting one play or all of them (on the account's other devices too, signed in to a koan server). Settings changes playback, terminal, visualiser, server and device settings without editing
config.toml. Albums, Favourites, Recent and Artists now show a clickable/ filterin their heading.
Changed
- The terminal UI is drawn in the kōan theme. The accent follows the playing cover, headings are lowercase over hairlines, and the transport bar moved to the foot of the screen. The visualizers follow the accent in every mode: the default
visualizer.paletteis nowtheme, andspectrum, which was the frequency rainbow, means the same. The rainbow israinbow.playback.tui_theme = "ansi"restores the terminal's own colours.
0.62.1
Added
- The GraphQL API accepts API keys. A key sent as
Authorization: Beareracts as its account, as on the Subsonic API, so a script or a GraphQL client need not sign in with a password and refresh a token every 15 minutes.
Changed
- The Mac's menu bar item shows the kōan ensō. It drew a music note, which did not say which app it was.
- Screenshots in the kōan theme. The site, README and guides show the Mac, iPhone and Apple TV apps as they are drawn by default, with the EQ page, queue, playlists and artist pages added; the homepage's iPhone and Apple TV strips are carousels that move when asked.
Fixed
- Android search headings sit at the start of the page. The Artists, Albums and Tracks headings in search results were centred.
0.62.0
Added
- Scrobbling to Last.fm. Accounts can connect Last.fm on the web UI's Scrobbling page, through Last.fm's own sign-in, and the server sends their plays and now-playing notices as it does for ListenBrainz. The server's admin registers an API key and sets
lastfm.api_keyandlastfm.secret, andsharing.public_url; connecting sends the last two weeks of history, as Last.fm takes no older plays. - An Android app. It links the same engine as the Apple apps and has the iPhone's pages: the queue, the library's shelves, records and artists, search with select mode, playlists, downloads and offline mode, history, Now Playing with lyrics and the sleep timer, and Settings down to devices, pairing and EQ. It plays gaplessly, in the background behind a media notification, drawn in the kōan theme or Material You. It is installed from an APK until it is on Google Play; see the Android guide.
- Bit-perfect output to USB DACs on Android 14 and later. When the DAC offers the track's rate and channels unmixed, kōan takes it, opens the stream in an encoding that keeps every bit and shows the playback as bit-perfect; otherwise it plays through Android's mixer and says so. It can be turned off in Playback settings.
- The Android mini player is always there. With nothing queued it says so, and while there is another device it carries Play on, so the phone works as a remote from a cold start, as on iOS.
- A play on Android says so at once. Playing a record or an artist names it, loading, on Now Playing and the mini player from the tap until its tracks are queued, rather than leaving the track it replaces on show; play and pause wait for it.
- Send logs from the Android app. Settings → About → Send logs shares the app's log since it started, with the build, the phone and what it was playing to, so a bug can be reported without a computer. A track that fails to start now says why instead of staying silent.
- The Android app shows what it is busy with, and why it could not start. Signing in, loading the library, syncing and clearing downloads show on a card over every page, as on iOS. An engine that fails to open says so with the reason. Choosing the open tab again returns to its first page and then to its top, and Appearance has the graphics level, which turns the record's colour off or holds it still.
- Track info on Android. Tapping the titles on Now Playing shows what the library knows of the track: the file's tags, the server's entry, its ReplayGain and its ids, selectable to copy. Opening Now Playing looks for renderers, so Output appears when one answers.
- Releases carry the Android APK. Each GitHub release now has
koan-android-arm64.apkbeside the macOS and Linux downloads, signed with a release key that CI builds share, so each one installs over the last. An APK installed before this has to be uninstalled once first.
Security
- rustls 0.23.46. Fixes RUSTSEC-2026-0346 to -0349 in the TLS client every HTTPS request goes through, among them a server able to downgrade later connections to classical key exchange.
Changed
- Web icons from the kōan set. The web UI and share page draw their transport, share, chevron and heart icons from the same SVGs as the apps (
just iconsnow emits a Rust module too), replacing hand-drawn glyphs and the share page's emoji skip buttons.
Fixed
- Scan and sync can be retriggered after a crash. A panic in a library scan or remote sync job now ends the job as Failed instead of leaving it Running and blocking every later run.
- EQ sync no longer lets a fast clock win. An edit stamped ahead of the server is counted as made on receipt, so edits from correct clocks made after it still win.
- Reconnecting no longer leaks a thread. The remote link spawned a fresh background wake-up thread on each connect after all links had dropped; it now starts one for the whole process.
- New link commands are closed to nearby strangers by default. The list of commands a device on the local network may send is now an explicit allow-list, so a command added later has to be opted in.
- A slow network mount no longer stalls playback. Checking that queued downloads still exist on disk no longer holds the queue locked while it waits on the filesystem.
- Repeat off no longer wraps after starting a new queue. Playing an album or a shuffled set while repeat was on could still queue a wrap to the first track at the end, because the decoder read the old repeat mode.
- Playing when the controlled device is out of reach plays here. A device controlled from this one and no longer reachable, by the network or the server, used to swallow every play. Now playing a record or playlist, resuming, skipping or adding to the queue does it on this device instead, stops controlling the other, and says so; the network is dialled once more before the device is given up. Pausing or seeking it says it is out of reach. A server's own refusal, such as an expired key, is shown as the server gave it, and Android shows command failures where it showed none.
- Play on and Output are separate on Android, as on iOS. Play on picks the device; Output, its own button on Now Playing, lists where the device in view plays: this phone's route and renderers, or while another device is controlled, that device's outputs with the one in use ticked and the EQ preset each is set to, picked there. The Play on button and the mini player name the controlled device in place of the old "Playing on" strip.
- The Android library behaves as iOS's does. A record's sleeve plays it and opens it, in the album grid, on artist pages and on shelves, and artist rows carry a play button; both ask before replacing a queue with anything in it. Track rows on record pages, shelves and search mark whether a track is downloaded, on the server only, downloading, or failed. A record that cannot be read says so, with Try Again and Go Back, instead of staying blank.
- Android picks the server up again after a change of network. Moving between Wi-Fi and mobile data makes the connections to the server afresh and tries it at once, and a track held up by a server that is not answering shows why in the queue.
- Android finds devices on the local network. kōan devices are found and announced over Android's network service discovery, as the Apple apps do over Bonjour, and UPnP/DLNA renderers are searched for from the Wi-Fi interface. On Android 17 the app asks for the local network permission this needs.
- Now Playing on Android follows iOS's choices. This phone's EQ preset is chosen on Now Playing while it plays; Output shows only with something to pick (a renderer, or the outputs of a device controlled), named only when the music goes somewhere particular, and each output there has its own preset menu. Play on shows once there is another device. Rows in Play on and Output share one leading edge.
- Android plays to UPnP/DLNA speakers. Play on lists the renderers on the network beside this phone's own output, searching as it opens, and says when one is connecting, playing or would not take the music.
- Android says where the music plays. While the phone controls another device, the mini player and Now Playing say "Playing on
", or that it is out of reach, with one tap back to the phone. A phone left controlling a Mac it could not reach looked as if it would not play. - Android finds renderers before Now Playing opens. The app searches for UPnP/DLNA renderers when it opens and once a minute while it is on screen, so the Output button is there for a renderer on a phone that is the only device on the account. Before, the only search ran as Now Playing opened.
- Android names its own output. Output and the now-playing row call the phone's route what it is, the phone speaker, headphones, or a Bluetooth or USB device by its product name, where they said "Android"; the row's buttons are spaced as on iOS and a long name is cut short. EQ profiles chosen per output follow the route, as on iOS.
- Playlists refill after signing out and back in. Forgetting a server's tracks emptied its playlists, and the next sync read them as unchanged and never pulled them again; they are now pulled whole once the library is back.
- Signing out ends offline mode. It stayed on, so the next account signed in showing only what was on the device.
- The queue keeps its tracks after a server's tracks are forgotten and synced again. A queued track could take on another track's cover, favourite and details when the library reused its id; the queue now finds each track again by its uid, and plays a track that is gone from its own file until it returns.
- The Mac app can find UPnP renderers and nearby kōans again. Its bundle declared no local network use, so macOS never asked and dropped the search; it now says why it wants the network and asks, as the iOS app does.
- EQ catalogue caches no longer show up in a version-controlled config directory. The
squig/andautoeq/folders now carry their own.gitignore, asauth/does, so a config directory kept in git does not need hand-maintained ignore entries for them.
0.61.13
Added
- The web UI makes the first admin. A server with auth on and no accounts shows a setup page instead of sign-in, so one in a container needs no shell to become usable; it closes once any account exists. Whoever reaches it first becomes the admin, so
graphql.setup_wizard = falsekeepskoan auth setupthe only way.
Fixed
- A generic EQ no longer unmatches the chain or warns. The EQ page draws a chain as matched when its first EQ is made for the correction's target; EQs after it that say no target no longer break that, only ones made against another target do. An EQ that does not say what it was made against is noted quietly rather than warned about.
0.61.12
Changed
- The web UI and share pages are drawn in the kōan theme. Square controls, one prominent action per page, bordered secondary buttons, flat list rows, lowercase labels and navigation, the theme's checkbox and seek slider, and the sidebar and transport on the page's own ground. Secondary text is a shade lighter everywhere, koan.rocks included, to meet AA contrast.
Fixed
- EQ sync keeps a profile the server holds a later edit of. A deletion the server refuses, because a device whose clock ran ahead stamped an edit after it, no longer drops the profile on the deleting device only to have it return on the next pull; the server's copy is taken at once.
0.61.11
Fixed
- An EQ's name stays in sight while it is typed. On iPhone the graph goes short and the field scrolls above the keyboard, as it does for the band figures.
0.61.10
Added
- Shuffle beside Play. Record, artist and playlist pages have a shuffle button next to the play button: it replaces the queue with the page's tracks, shuffled, starting from a random one. On an artist's page it shuffles all of their tracks, rather than fifty picked at random.
Changed
- Previous restarts the track. Once a track has played for more than a second, Previous starts it again; pressed again straight away, it goes back a track.
- Clicking a sleeve in search or on a shelf asks before replacing the queue. With anything queued, choose to play the record in its place or add it to the queue.
Fixed
- Splitting a squig.link preset no longer puts its headphones' treble in the tuning. The tuning is now taken against the correction the preset was fitted from. A tuning made by an earlier split keeps the old treble; split the preset again to replace it.
- Done above the keyboard works on an EQ's page. The Previous, Next and Done bar shows only for the band figures it moves between; the name field keeps its own return key.
0.61.9
Fixed
- The Mac app builds again. 0.61.8 shipped without it: a constant the phone's lists use was declared for iOS only.
0.61.8
Changed
- Tighter lists on a phone. The queue, playlists, search and the library's lists use the album page's row spacing, so a screen holds about twice as many tracks.
- Even spacing on the Mac's lists. Album, playlist and queue pages share one 16pt margin for the header's side and top and for the gap above the first track, and track rows are tighter.
0.61.7
Changed
- Album and artist pages on a phone. A larger sleeve with the title, artist and details on lines of their own, play beside the lesser actions, tighter tracklist rows that drop a credit repeating the album artist, and the artist bio above the records.
Fixed
- Share link text has correct spelling
0.61.6
Fixed
- Unbreak builds by gating toolbar probe
0.61.5
Added
- Share pages offer a Download. Anyone with a share link can take the shared tracks as one zip of the original files, streamed as it is written, so a visitor can keep what was shared without a koan account.
Changed
- The kōan theme's search field has no box. It sits on the page's ground; the toolbar's filter field no longer puts its text under the magnifier when focused.
Fixed
- Mac pages stay below the toolbar after a window resize. Lists and the album grid could end a resize under the toolbar and stay there; they now measure the toolbar from the window.
0.61.4
Changed
- Moved the album/artist on to two lines in tvOS
0.61.3
Removed
- Mac AirPlay button. The transport bar no longer has an AirPlay button, which did not work on the Mac. Choose an AirPlay speaker in System Settings or Control Centre; koan follows the system output as before. iOS keeps the button.
Fixed
- Context-menu icons follow the menu text colour. The kōan glyphs still drew black in the Mac app's menus.
- Mac pages after a resize. The first row of an album grid, artist list or track list no longer ends up under the toolbar when the window is resized or the toolbar settles after the first layout; the scroll position now follows the top inset.
0.61.2
Added
just releaseprepares a release PR. Given a version orpatch,minorormajor, it branches from main, bumps the version everywhere CI compares it, writes the changelog, commits and opens the PR.
Changed
- Shuffle no longer rearranges the queue. It picks the next track at random from those not yet played, each once per pass, while the queue keeps the order you gave it. A track is marked played when it plays, so turning shuffle off leaves exactly the tracks you heard marked, and Previous goes back through what actually played. Playing something from its play button now turns shuffle and repeat off, and its Shuffle action turns shuffle on and repeat off; adding to the queue leaves both alone.
- Mac text size. The kōan theme draws its type as large as the system's rather than about 15% larger, with spacing a little tighter, and Settings → Appearance → Text size and View → Bigger, Smaller and Actual Size (⌘+, ⌘−, ⌘0) scale it from 80% to 130%.
- Now Playing title. On iPhone the track title takes the full width of the sheet, with the heart and more button moved to the artist line.
- A closed pull request's CI runs are cancelled. Merged and abandoned pull requests no longer hold the macOS runners that main and releases wait for.
Fixed
- Library figures. The sidebar footer pads its top, bottom and sides equally instead of leaving extra space below the last line.
- Shuffle: a restored session or a repeated track no longer starts the queue over. Reopening koan at the end of a shuffled pass, with repeat off, carried on into a new pass instead of stopping, and repeating one track could clear the played marks. A new pass now starts only when you pick a track of a queue that has played out, or turn shuffle on over one. At the turn of a repeating shuffled pass, a track that failed to open no longer makes the next pass's first track play twice.
0.61.1
Changed
- Play on uses the devices icon, and the filter and AirPlay buttons the kōan glyphs. All three drew system symbols in the kōan theme.
- No library folder until you choose one. kōan no longer indexes
~/Musicwhen no folder is set, which on macOS asked for access to the Apple Music library. A library already indexed from~/Musickeeps it: the folder is written intoconfig.local.tomlthe first time this version opens it. - Glyphs on navigation in the kōan theme. With "Show icons" on, the iPad sidebar, the Library section and Settings lists on iPhone and iPad, and the Mac Settings tabs draw each place's glyph. The phone's tab bar and the television stay words alone.
Fixed
- Integrations. The Settings section for server-side features is called Integrations again, as the longer name wrapped in the heading.
- Mac: choosing an IEM correction's target no longer crashes. The Correction sheet fitted itself to its content, which changed with the chosen target and re-wrapped at each new width, so the sheet resized itself until the app ran out of stack. It now opens at a fixed size, can be resized by dragging, and remembers its size like the other EQ sheets.
- Mac rows keep their marks in line. The codec takes one width in the queue and playlists, and the format column keeps its place on a track without one, so the heart and availability mark line up down the list.
- Mac sidebar and filters in the kōan theme. The sidebar draws each place's glyph again when icons are on, and the library filter popover uses the theme's toggles, menus, fields and buttons in place of the system form.
- Recently deleted EQs are always listed. Manage EQ shows the section whenever the server keeps deleted EQs, saying so when it holds none, so the feature can be found before it is needed.
- EQ on iPhone. Typing a band's figure keeps its row in view: the graph goes short above it, and the bar over the keyboard steps between figures and has Done.
- Output on iPhone and Apple TV. The Output button is hidden while the only choice is the route iOS already picked; it appears once a UPnP amplifier answers, or while another device is controlled.
- Presets on iPhone. In the kōan look, Now Playing's preset choice opens the theme's tray, as Output and Control do, in place of the system's glass menu.
- Context menus tint the kōan glyphs. They drew black instead of in the menu's text colour.
- Search field. The theme's search field no longer grows taller once text is typed into it.
- Album and artist headers centre the play button on the title. The title sat above the button's middle.
- Mac: the theme's popovers no longer crash when what they show changes size. Play on, Output and the theme's menus sized their window to their content from inside the window's own layout, so a row that changed while one was open, or an EQ chosen from the output menu, had the window resize itself until the app ran out of stack. The window now follows the content's size once each layout is done.
- Availability marks. The cloud and on-device marks in track rows are larger, and a track kept on this device shows as a solid cloud.
0.61.0
This release manages app passwords from the Mac and iPhone, gives the kōan theme its own icons, and stops EQs kept on every device from being deleted without anyone deleting them; a kōan server now keeps a deleted EQ for thirty days. The schema stays at 23: the server's dsp_profiles table gains two columns, deleted_doc and deleted_at, added in place, so 0.60.12 still opens the database. Snapshot a server's database before upgrading all the same.
Added
- App passwords in the apps. Settings → Account on the Mac and iPhone lists, makes and revokes app passwords for Subsonic clients that sign in only with a token, through new
koanAppPasswordsendpoints. Shown only when signed in to a koan server that offers them. - New EQs, stereo bands, and EQ for speakers. Add EQ has New EQ…, which makes eight bands across the range, flat or from a bass boost, warm or bright starting curve. An EQ of bands can be stereo, with a list for each channel; going back to mono when the two differ asks which channel to keep. Correct for a headphone profile can be switched off for a device, such as speakers, which then plays a plain list of filters with no correction and nothing about targets; a preset keeps the setting.
- Recently deleted EQs. Manage EQ on the Mac, iPhone and iPad lists EQs deleted in the last thirty days, with the days each has left, and restores one on every device. Shown only on a koan server that offers it (
koanDspDeleted).
Changed
- The kōan theme draws its own icons. A set of thin, square-ended line glyphs replaces SF Symbols throughout the Mac, iPhone, iPad and Apple TV apps when the kōan theme is on, so the icons match its monospaced type and square, hairline controls. The system look keeps SF Symbols.
- Removing an EQ never deletes it. Taking an EQ out of a device's filters or a preset's layers says Remove everywhere, by swipe on iPhone and iPad, and on the Mac by right-click or ⌫; it leaves the EQ itself alone. Only Delete… in Manage EQ deletes one, after asking. What was called a device's tuning is now its filters.
Fixed
- Apple TV, in the kōan look: the tabs show only at a tab's root, and the share code, album tiles and filter panel are the theme's. On a page opened from a tab the tabs fade out, as with the system's tab bar, and their room is kept so the page does not move; Menu goes back, and at the tab's root they return. A share code opens in the theme's square panel rather than a rounded card. Album tiles take the accent ring in place of the rounded lift, the filter panel's year fields are the theme's boxes, and its Reset is lowercase like the rest.
- iPhone: Now Playing's close chevron and missing-cover sleeve. In the kōan theme the chevron sits in its own row on the sleeve's edge instead of over its top, and a record without a cover shows a flat placeholder rather than a framed grey square.
- The preset chip draws one outline. In the kōan look, the EQ preset chip under the iPhone's Now Playing drew its own outline inside a second, larger one from the menu's bordered button. The menu now leaves the frame to its label, and the device picker's preset glyph on a phone is a bare glyph again.
- Mac lists keep their columns beside the lyrics. Opening the lyrics narrowed the queue, album and other track lists without laying their rows out again, so each track's format and length sat hidden under the panel. History's day headings no longer float on AppKit's grey band in the kōan look. The sidebar's album and artist counts break onto two lines rather than leaving the separator at the end of a line, and the EQ chain is outlined in the accent, lines and boxes alike, when every EQ that plays is matched to the correction.
- Mac: Settings and the EQ sheets resize, and remember their size; the EQ graph stays in view and is drawn at the level it plays at. The Settings window, an EQ's page, Manage EQ, the import confirmation and the picker can be resized by dragging, open larger, and reopen at the size they were last given. An EQ's page no longer lays itself out wider than its sheet and clips. On the Mac and iPhone its graph stays at the top while the bands scroll under it. The graph is centred on a dashed line at the preamp, labelled with its value, and its curve moved by the preamp, so a profile reads the same whether its gain is stated as a preamp or as a gain filter.
- EQs are no longer deleted from every device unless you delete them. An EQ kept on every device could be deleted from the server and the account's other devices without anyone deleting it: assigning it to a built-in output or a phone's speaker, giving it an impulse response, or adding an EQ kept on one device to a stack or group made it count as kept on this device alone, and the next sync deleted it everywhere else. An EQ missing from a device for any other reason was deleted everywhere too. Now only deleting an EQ, or choosing This device for it, removes it elsewhere, and an EQ that is missing without having been deleted is taken from the server again. A kōan server now keeps a deleted EQ and its files for thirty days rather than discarding them at once.
0.60.12
This release fixes a library folder configured in another case than the disk's, such as ~/music on a Mac whose folder is ~/Music: 0.60.11 indexed every file in it a second time. The first scan after upgrading folds each duplicate back into its original track. The database schema is unchanged from 0.60.11.
Security
- Disconnect no longer shuts out the device another one claims to be. A device on the network that had not proved it is one of yours, including one shared from another account, was held off by the device id it gave as well as by its address. One giving your phone's id could therefore, once disconnected, cut your phone off from this device until the phone was played on, which also let it back in. Such a device is now held off by its address alone.
Fixed
- A library folder configured in another case no longer shows every track twice. With a folder set as
~/musicon a Mac whose folder is~/Music, 0.60.11 indexed each file again under the disk's spelling and kept the old rows. Scans now move the old rows to the disk's spelling and fold each duplicate back into its original track, keeping its history, favourites and playlist places. - Apple TV and iPad: the kōan look's own TV tabs, no grey slab above a text field, and the iPad sidebar on the page's ground. On the TV the tabs across the top are flat and lowercase in the theme's type, with the accent ring for focus, in place of the system's glass capsule and white platter; the remote moves through them and Menu reaches them as before. A filter field at the top of a TV page no longer paints a grey band up to the top of the screen. On iPad in dark mode the sidebar's library rows no longer sit on a black block, and the selected one has its accent rule.
0.60.11
0.60.10 was never published: its macOS and tvOS release builds failed in the Swift compiler, so its GitHub release, server image and TestFlight builds did not go out. 0.60.11 is the first release to carry its changes, below under 0.60.10. This release moves the database from schema 22 to 23, rebuilding the scan and lyrics caches (#1059), and builds older than 0.60.11 refuse a database that has been migrated. Snapshot the server's database before deploying.
Added
- Apple TV: a name filter on listings. Albums, Artists, History and Playlists have a field above the listing that narrows it by name.
- See and end the connections to a device. Settings → Devices → Connected now lists the link to the server, the account's devices that can control this one through it, and every connection on the local network in either direction, with when each began. A device on the network controlling this one can be disconnected, which keeps it out until it is played on or picked again, and one that has not proved it belongs to the account can be refused by address (
devices.refused), so unexplained battery use from another device driving this one can be seen and stopped.
Security
- Reports on nearby connections are signed. Between two signed-in kōan devices on the same network, what the controlled device reports back (what it is playing, and whether a command arrived) is signed for the connection, as commands already were, so it cannot be forged by someone able to inject into that connection. Older devices are read unsigned, as before.
Changed
- Apple TV: square text fields. In the kōan look, text fields on the TV are square boxes like the rest of the theme instead of rounded pills.
- The Mac sidebar is the page's ground in the kōan look. It no longer draws as a lighter grey panel, with the wash under the whole window or not. Its search field is the theme's square field, with suggestions in a square panel beneath it and
/to focus it; the selected row is marked by the accent and its leading rule rather than a rounded fill; and the library counts sit below a hairline. The system theme keeps the platform's sidebar.
Fixed
- Downloaded tracks marked as downloaded. A remote track whose file was in the cache but not recorded played from the cache while showing as on the server only, and was never evicted. Such files are now recorded when the track is queued, and at launch for the rest. A download two editions of an album share is counted against the cache limit once.
- Now Playing shows the bit depth of 24-bit ALAC files. It read 16 bits, because the depth of ALAC in MP4 is stored only in the codec configuration, which is now consulted. Lossy streams that state no depth show none instead of 16.
- Apple TV discovery no longer repeats the AirPlay lookup on every reconnect. An Apple TV with no matching AirPlay announcement is looked for once per address every ten minutes instead of at each hello. An error from that lookup can no longer hide, or stand in for, a local network permission error from the standing browse.
- Organizing into a folder with accents no longer duplicates the file. Organize stores the path as the folder spells it on disk, so the next scan finds the row it already has instead of adding a second. Scanning one directory reads the scan cache for that directory only, rather than the whole library's, and a track's scan cache entry and lyrics are now deleted with it by the database. The database moves to schema 23, which builds older than 0.60.11 refuse.
- Measurement source follows the last pick. In the measurement flow, choosing a file after fetching a squig.link measurement left the checkmark on the squig.link result. It now clears, as the site credit already did.
- Buttons take the click across everything they draw. On the Mac, the toolbar's back, forward, sidebar, lyrics, filter, sort and select buttons are now full-size cells, rather than only their glyphs, with a hover and pressed ground in the kōan look. The album page's play square, hearts, chips, the play/pause buttons, Control and Output, lyric lines and picker rows also take clicks across their outline and padding, not just the glyph.
0.60.10
Added
- Speaker measurements from Audio Science Review. The measurement importer reads Klippel Near-Field Scanner exports (
SPL Horizontal.txt,SPL Vertical.txt), whose frequencies carry thousands separators. With both planes the correction is made from CTA-2034's listening window, with one from the on-axis response, and the importer says which. A speaker is corrected to the new Flat target, offered with any targets added by hand but none of the headphone ones; Flat is not offered for headphones.
Changed
- No glass, no rounded controls in the kōan theme. With the theme on, popovers on the Mac (Control, Output, Filters) are square panels on the theme's ground with a hairline edge and no arrow; the sleep timer, EQ preset and sort menus open the same panel; dropdowns are square bordered buttons, choices in forms are ticked rows rather than radio buttons, and toolbar items, search fields and sheets lose their glass on every platform. The system theme keeps the platform's look.
Fixed
- A measurement the importer cannot read says so. Next on the measurement step refused such a file with a message below the fold, so it looked as if nothing happened. The refusal now scrolls into view and names what was expected (a two-column frequency and level CSV, a squig.link export, or a Klippel export) and what the file holds instead, including when a file's path was pasted in place of its contents.
- The Mac's Settings window is drawn in the kōan look. Its tabs were the system's glass toolbar buttons, with the chosen one dimmed almost out of sight. In the theme they are the theme's own tab row on the window's ground, lowercase, the chosen tab in the accent and underlined, with no glass anywhere in the window. The platform's look is unchanged.
- Mac search and shelf tracks line up with the page. Track rows under the albums on search results, Favourites and Recently played start on the same margin as the headings and tiles, with the play mark and the playing bars in a badge on the sleeve rather than in an empty column.
- Mac search and shelf track rows answer where they are drawn. The artist, the record and the sleeve took clicks and showed the pointing hand 8 pt to the left of where they sit.
0.60.9
Added
- Play on wakes a sleeping Apple TV. A phone or Mac records the TV's AirPlay announcement while it is awake, and opens a connection to it when kōan there is asleep, so the Bonjour Sleep Proxy wakes the box before the server's push wakes kōan.
Changed
- Select is a checkbox on iPhone and iPad. The word "Select" was cut short in crowded bars. An empty box starts select mode on every page that has one, shows ticked while the mode is on, and ends it when tapped again.
Fixed
- Lyrics no longer show another song's words. The lyrics panel shows only lyrics fetched for the track that is playing, so a quick track change can no longer leave the previous song's lyrics on screen. When LRCLIB has no exact match, a search result is used only if its title (ignoring featured artists) and length (within two seconds) match the track; otherwise the panel shows no lyrics.
- Play on no longer waits on an Apple TV that is out of reach. When nothing on the network answers for a TV on record (the phone is away from home, or the TV is unplugged), the push goes out at once instead of after twenty seconds of knocking.
- Apple TV: Menu goes back a page instead of leaving the app. Playing from an artist page, a shelf or a browser used to jump to the Queue tab with focus on the tab bar, so the next press of Menu left kōan. The queue now opens over the page you were on, and Menu returns to it. The EQ page's "Add a correction" and "Add EQ" choose from the corrections and EQs already on the TV, and search's artist pills and track rows can be selected with the remote.
0.60.8
Fixed
- A record without cover art no longer keeps the previous record's colours. The wash fades to the bare ground and the accent returns to mint, while a cover that is still loading keeps the current colours until it arrives.
- An Equalizer APO file's preamp stays a preamp. The same
Preamp:on each channel, as squig.link's two-channel export writes it, is imported as the EQ's preamp rather than a gain band on each channel, so the graph no longer draws it inside the curve. An EQ imported before keeps its gain bands until its file is imported again. - A correction with a tuning on top is not quieter than it needs to be. The chain's preamp is worked out from what the correction and tuning play together, rather than kept at the correction's own, so a layered chain plays at the level of a single EQ with the same curve.
- A tuning skipped under a mixed correction is said.
koan dsp setandkoan dsp showname the device's tuning when a correction that already includes one leaves it out, and--tuningtakesnoneor an empty value for no tuning,koan dsp responseincluded. - A tuning on a measured correction plays as squig.link would. Under a tuning made against another target, a correction built from a measurement is fitted again to that target rather than played with the difference between the targets added, which only came close to the same result (off by up to a decibel in places). The EQ page,
koan dsp showandkoan dsp responseshow the refit. Nothing is saved. - Opening EQ pages no longer slows the next track's start. Fits from a measurement are kept least recently used first, and those the playing chain uses are kept apart from the ones EQ pages make for their previews, so browsing targets never forces the player to fit its correction again before playback starts.
0.60.7
Added
- The EQ chain shows how each EQ meets the correction. The line into an EQ is drawn in the accent where it was made against the correction's target, shows the target difference kōan plays where it was made against another, and warns where Made against is not set, since a target may then be applied twice.
koan dsp show --jsongives each EQ'smade_for,matchedandjoin. - Track info and menu in Now Playing. On iPhone, tapping the track's title opens everything the library knows about it: each source's tags, the file path and server ids, MusicBrainz ids and ReplayGain, in selectable text. A … beside the heart holds the menu track rows have: go to the album or artist, favourite, add to a playlist, share.
- Select on the shelves. Favourites, Recently Played and Downloaded on iPhone and iPad have a "select" button too, picking artists, records and tracks together for the bar at the foot of the page.
- Made against explains itself. For a tuning that does not say what it was made against, kōan offers the target its curve fits, such as Harman for a tuning without Harman's bass shelf, on the EQ chain and the tuning's page; it is set only when accepted. The tuning's graph draws what it adds on the correction in use, and on a phone each choice shows that curve, so a wrong one shows as a bass shelf doubled. The chain draws the target difference it plays.
- EQ: graphic curves are editable. On a tuning's page, a graphic EQ opens a page of its points, each frequency and gain editable, with Reset to File for an imported EQ.
- EQ: edit a tuning on its graph. Drag a band for frequency and gain and pinch it for Q, or paint a graphic curve with a brush; the curve redraws as you drag and the edit plays as it goes. Save as Copy keeps an edit as its own EQ in the original's place in the tuning and leaves the original as it was.
Changed
- Neutral targets name their kind of headphone. The two diffuse-field targets read "Neutral, over-ear (diffuse field)" and "Neutral, in-ear (diffuse field)", so either reads right outside its heading, and Made against lists the targets for the device's kind of headphone first. Their ids are unchanged.
- Bit-perfect claims match the apps. The docs, site and README say what the phone and Apple TV do with sample rates: no resampling through a USB DAC that supports the track's rate, resampled by the system on any other route.
- Record and artist headers. A title that runs to two lines starts level with the top of the play button and wraps below it, and the heart sits close to its "favourited" label.
- EQ: the tuning's EQs are swiped. On the iPhone, swipe an EQ in the chain to remove or move it, or touch and hold it, in place of its Options menu. Add a Band is a button.
- Add EQ shows what each EQ was made against. Each row carries its Made against target, and EQs made against the correction's target are listed first, in the accent. Graphic EQs read "graphic, N points" rather than "1 band".
- Corrections from a measurement are squig.link's Auto EQ. kōan fits a correction built from a measurement as squig.link's Auto EQ does: peaking bands below 6 kHz, boosting by no more than 12 dB anywhere, and a preamp, kept as the correction's bands and fitted again when its target changes. From the same measurement and target it plays what a preset exported from the site plays. Corrections saved from a measurement by 0.60.6 or earlier are fitted the same way when they play, so they no longer correct above about 6 kHz: 0.60.6 applied up to 12 dB there up to 10 kHz and up to 3 dB above it, so on most earphones the treble changes by several decibels.
Fixed
- Now Playing and sheet buttons on iPhone. In the kōan look, Now Playing fills the screen with square corners instead of opening as a rounded sheet, and sheets' Done, Cancel and confirm buttons are plain text rather than glass circles.
- Target pickers on iPhone reach their last row. In the kōan look, the Made against, Corrected to, Target and Neutral is lists now open as pages that keep clear of the mini player and tab bar, so the bottom option can be tapped.
- Album pages no longer open empty. Each album page now keeps its own record, so a read for another page that finishes late can no longer replace it; before, the page showed "Album" with no tracks until the library next changed. A record that has gone from the library, or that could not be read, is now said as such, with a way back and, after a failed read, a retry.
- No spinner flash on album pages. The library is read locally, so a record nearly always arrives at once; the progress indicator now appears only if the read is still going after 300 ms.
- iOS and tvOS ask for each track's sample rate. The app never set a preferred rate, so a USB DAC stayed at whatever rate it last ran at and iOS resampled every track, while the format badge reported the track's own rate as the output's. The audio session is now asked for the track's rate as playback starts, and the badge shows the rate the hardware runs at.
- Opening koan on iPhone no longer stops other apps' audio. The audio session is now activated when koan starts playing, not at launch or on returning to the app. It is given back five seconds after playback stops, and the app koan interrupted is told it may resume.
- Settings saved at the same moment are both kept. Two config writes at once, such as the player saving the volume while a setting changes, could lose one; a read during a write could briefly see defaults.
- Red records give a red accent. A sleeve whose red sat close to the error colour had its accent turned to magenta or orange; the accent now keeps the sleeve's hue. Thin coloured strokes on a black sleeve are found too, rather than giving mint.
- Album tiles show downloads up the left edge. The bar fills from the foot of the sleeve's left edge, full height, so a half-downloaded record reads as half; it used to stop short of the heart, making a whole record look partly here. A record wholly on the device shows no bar.
- The iOS format badge follows a route change. Plugging in or pulling out a USB DAC while playing left the badge at the old route's rate. A route change now asks the new route for the track's rate and reports the rate it runs at.
- Unfavouriting sticks. Taking the heart off a record, artist or track while signed in to a server no longer turns it back on: a sync that read the server's favourites before the change reached it put it back. Changes now wait on the device until the server has them, which also keeps one made offline.
- Download cache size stays current. Settings' "Using" figure was read once when the app started and kept that value, so on a phone left running it could read "Zero KB" over gigabytes of downloads. The engine now keeps the count as downloads land and trims or clears remove them, and Settings follows it on the Mac and iOS. It reads "0 KB" rather than "Zero KB", Clear is a separate button, and the notice after clearing goes after a few seconds.
- Settings actions look pressable. Secondary actions in Settings, such as copy address, scan, sync and sign out, are outlined buttons, and links such as "find your token" are underlined, where before they were bare text in a row. The Integrations pane is now Server Capabilities, since what it holds is what the server does for the account. On iPhone, iPad and Apple TV, Playback no longer offers an output device: the system's route picker chooses it there.
- Pushed pages keep the wash. In the kōan look on iPhone and iPad, an EQ's management page, the options of a list picker and an AutoEQ maker's models drew a flat black ground instead of the record's wash; on Apple TV, settings opened from the sign-in screen did the same. Every pushed page now hands its stack the theme's ground, and
just theme-leaksflags a page that does not. - Music sent to an iPhone in the background is no longer silently dropped. iOS does not let a backgrounded app take the audio from another app that is playing, so the phone now shows a notification that starts playback when tapped.
- Square EQ sheets on iPhone. In the kōan look, Add EQ, the correction picker, AutoEQ, measurements, splitting, the role question, How EQ works and the browse filters open as the theme's square panel rather than a rounded card over the EQ sheet.
- Corrections and tunings add up as on squig.link. A tuning's difference from the correction's target plays in full up to 6 kHz and fades out by 12 kHz, the range squig.link's Auto EQ works in, so a correction to neutral with a target's tuning on top comes close to a correction to that target. Measurements fetched from squig.link have the site's calibration subtracted, as the site does before drawing or equalising them, and the shipped Harman in-ear 2019 target is squig.link's file. AutoEQ corrections moved to another target are rebuilt from AutoEQ's measurement with the same fade, and sound different above about 6 kHz: by up to 3 dB on a Sennheiser HD 650. An in-ear correction moved to Harman in-ear 2019 also changes slightly with the new target file. A measurement fetched from squig.link (Super* Review) before this needs fetching again to pick up the calibration;
koan dsp measuretakes a file as it is, so a site's raw left or right file is not calibrated. - EQ edits made with
koan dspreach the server. The CLI exited before the background sync an edit starts could run, so its imports and changes stayed on the machine; it now syncs before exiting, warning rather than failing when the server cannot be reached. - EQ sync forgets profiles no longer kept everywhere. A profile deleted or moved to one device left its record of local edits behind; that record is now removed once the deletion has reached the server.
0.60.6
Added
- Select several on iPhone and iPad. A "select" button on the queue, record, artist and playlist pages, history, search and the browsers ticks rows or records, and a bar at the foot of the page plays, queues, adds to a playlist, favourites or removes them together.
- Revert to a preset. An output changed since its preset can go back to it from the EQ page, and the quick preset menus list the edited chain and the saved preset side by side.
Changed
- The wash is the only gradient in the kōan look. The Mac transport no longer fades in over the page. With the wash under the whole window, toolbar, sidebar and transport sit on it with no ground, scrim or system glass, each set off by a hairline, and pages stop at their edges instead of passing under them. The Apple TV sign-in screen loses its glow, and lists in the picker end on a hard edge.
- No repeated titles on iOS tabs. In the kōan look the queue, library, search and settings pages leave their name to the tab bar, which already shows it.
- The Mac transport is the window's foot when the wash covers the whole window. It keeps the theme's ground and a rule along its top, as the iPhone's mini player does, and spans the window beneath the sidebar and lyrics, which stop at its edge. The wash fills everything above it.
Fixed
- Theme labels and tints. In the kōan look on Apple TV, Settings' picker rows are lowercased like their neighbours; in the system look on the Mac and iPhone, the queue's "…" menu keeps the record's accent.
- Importing an EQ. Importing no longer offers the new EQ for the output in use in a prompt that closed by itself; "What is this EQ?" appears straight away over Manage EQ rather than after leaving it. Import from a stage's Add… on the EQ page now imports at all on iPhone, and puts what it made into that device's chain as its answer says.
- Pages end above the mini player. In the kōan look on iPhone and iPad a page scrolled to its end leaves room under its last row instead of meeting the bar's rule.
- Even margins on shelf pages. Favourites, Recently Played and Downloaded laid their records out off-centre on a phone; the grid now spans the page between the same margins as its headings.
- Tapping the tab you are on goes back to its top. In the kōan look a tab chosen again returns to its root, and from the root to the top of the page, Settings' panes included.
- Small controls easier to hit on iPhone and iPad. The queue's ⋯, layout and follow buttons, a record's ⋯, hearts and the theme's compact buttons each take a 44-point tap, however small the glyph.
- Square trays on iPhone. In the kōan look, the Control and Output trays are a square panel across the bottom of the screen rather than a rounded, inset card, with the selected row lined up on the title's edge; other sheets lose their rounded corners.
- EQ names and targets. Preset and device names keep their case in pickers, roles read Correction, Correction + Tuning and Tuning, and Made against lists each target once, under Over-ear, In-ear and Added, so a choice there sticks.
- Device tray drag. In the kōan look on iPhone, dragging the Control or Output tray down closes it.
- EQ targets on iPhone. Picking the target an EQ was made against, made for or corrected to ticks it and closes the list, instead of leaving "Unknown" ticked until you go back.
0.60.5
Fixed
- The Apple TV in the kōan look. Focus is a 2-point accent ring with no platter or lift. Tab titles are in lowercase Geist Mono, and track rows are in Geist Mono with their titles as tagged. Settings, the filter sheet, pickers and track menus are drawn with the theme's rows on the wash, not the system's grey pills.
- No system chrome on the iPhone and iPad in the kōan look. The iPad draws the theme's own sidebar, mini player and full-screen Now Playing. Navigation bars, back buttons and search fields lose their glass, and settings labels are lowercase. In the platform's look, the wash is held to the same contrast limits on the iPhone and iPad. On the Mac and iOS, the queue header no longer repeats a single album's name, and its layout toggle and menu are drawn in ink.
0.60.4
Fixed
- No blank band at the foot of settings on iPhone in the kōan look. 0.60.3 listed this as fixed, but the band remained on the settings pages: it was the line reporting the last action's result, held open on a grey ground above the mini player. That line now takes no room until there is something to report.
- squig.link measurements fetch from every site, and a failed fetch says why under the result. Sites that keep numbered samples or a separate measurements folder (squig.link's headphones, listener, doltonius) now fetch instead of failing. graph.hangout.audio serves its measurements only to its own pages, so its results are listed last and open the site in a browser. The entry point is now Find a Measurement….
- Lowercase where the kōan look writes text. Empty pages, the Mac queue and history headings, search section headings and the iPhone's "nothing playing" follow the theme's case rule.
- The EQ options menu says where a profile is kept. On iOS the "Keep on Every Device" item came apart into a greyed row and a blank checked one. It is now one item naming what it does, "Keep on Every Device" or "Keep on This Device Only", and when a stack or layer pins the profile where it is, the item is disabled and says why.
- Mac controls in the kōan look. Pop-up pickers are menus in the theme's type rather than AppKit's bezelled buttons, sliders (graphics level, output volume) are the theme's, settings labels share one style, lowercase, and the sidebar opens wide enough for its labels. The EQ chain names its tuning once, and the window no longer keeps Downloads' title after leaving it.
- Build recipes honour
CARGO_TARGET_DIR.macos-ffi,install-dev,watch-dev,ios-smokeand the demo server looked for cargo's output undertarget/and failed when it was built elsewhere.
0.60.3
Changed
- Pull requests hold a macOS runner only when they need one. The macOS test, lint and build jobs and the app builds run when a pull request touches the apps, the FFI, dependencies, toolchains, workflows or Rust compiled for Apple targets. Release pull requests run everything.
- A correction plays as made; tunings of several EQs; presets. A correction's bands are no longer edited, in the apps or anywhere else: add a tuning on top, or make it a tuning to edit it. An imported EQ keeps what it was imported as, so
koan dsp revertputs an edit back andkoan dsp copykeeps one. An output's tuning can hold several EQs in order, each on or off, and a preset saves an output's correction and tuning together:koan dsp set --tuning,koan dsp preset saveandkoan dsp preset use. An EQ that played a correction with EQs on top became a preset. - The EQ page is the chain the music goes through. Pick a device and its preset at the top; below, the curve of everything it plays, then the correction and the tuning's EQs as blocks in order, each drawn in the graph in its own stroke, each switched on or off, moved or opened to edit. Processing can no longer be switched off: a device is made Flat, and configs that had it off open flat, what each device played kept as a preset. The page explains its words under ⓘ How EQ works.
- The iPad's sidebar is the Mac's. With room for it, the sidebar lists the library's sections and the playlists, each opening its page beside it, and opens by default; it no longer holds only the four tabs with the sections behind Library. At compact width the tab bar is unchanged.
koan dspreads like the EQ page.koan dsp(orshow) says what a device plays in the page's sentence;set DEVICE --correction … --tuning …sets the whole chain in one go and changes nothing when repeated;flat,listandpreset listcomplete it, and every read command takes--jsonfor scripts and assistants. Refusals name what is wrong and the valid choices.eq playsandeq switchreplacestackandlayer, androle … mixedreplacesbaked; the old names, anduse,clearandtuning, still work but are out of the help.- Manage EQ, and a preset menu. Every correction, EQ and preset is listed in Manage EQ, at the foot of the EQ page, with the devices each is used on; groups are headings over their members, and a group of EQs can join the tuning whole. Renaming, copying, reverting an import, keeping one on every device and deleting are in each row's Options. The preset menu in the transport and Now Playing lists Flat and the presets, reads the preset's name, Flat or Unsaved, and opens the EQ page with Edit…. The guide and the CLI's help use the same words throughout: correction, tuning, EQ and preset.
Removed
koan dsp offandkoan dsp on. Processing is no longer switched off as a whole.koan dsp flatmakes a device flat, with no correction and no tuning, andkoan dsp preset use NAMEbrings a saved setup back;koan dsp preset use flatdoes the same asflat. Scripts that callofforonfail with an unknown command.
Fixed
- No grey band at the foot of a page on iPhone in the kōan look. Pages scroll under the theme's bar again rather than stopping at an opaque band above the mini player. Settings' steppers, pop-up pickers and row labels are drawn in the theme's type and controls instead of the system's.
0.60.2
Added
- Find a headphone's measurement on squig.link. Use a Measurement… searches the reviewers' squig.link sites by headphone name and lists each measurement with its site, rig where the site says, and variant; picking one fetches it, averages its two sides and credits the site on the profile. Each site's catalogue is fetched at most once a day.
koan dsp squigsearches from the terminal and makes a correction from a result.
Security
- Answers to commands come only from the device they were sent to. A command's id could be read off the network, and a device nearby, a listener claiming another's id, or another account on the server could report the command done, which stopped it being retried, or refused. A sender now believes an answer only from its target: on the network, one that proved it is that device; through the server, a link of the target's own account.
- Commands for your devices go over the network only to the device itself. A device on the network could claim the id of one of your devices and receive commands meant for it, with the tracks they name. Commands for your own devices, and for devices shared with you, now go over the network only to a device that has proved it is that one; otherwise they go through the server.
Changed
- The Mac window in the kōan look. The wash runs under the whole window, with the sidebar, toolbar, transport and lyrics drawn clear over it; turning off "Wash the whole window" in Settings → Appearance gives them back their own grounds. The toolbar's icons and filter field drop their glass, rows have more room between them, and the playing bars move at every graphics level. A text field keeps ⌥←, ⌘Z and the other editing keys from the moment it takes focus, and Settings can be resized.
Fixed
- Sign in on iPhone with the keyboard up. In the kōan theme, a blank strip above the keyboard covered the controls at the foot of a page, Settings' Sign In button among them, so a tap there did nothing. The room a page keeps for the theme's bar now gives way to the keyboard.
0.60.1
Added
- Headphones, target and tuning per output. The EQ page reads as a sentence, such as "AFUL Performer 8S, corrected to Neutral (diffuse field), tuned with Lush", and each part is a choice of its own; kōan builds the chain, so no stack has to be made by hand. A tuning can say which target it was made against, and on headphones corrected to another, the difference between the two plays with it, so it sounds as made on any correction. A preset with a tuning baked in takes none on top, and says why.
koan dsp tuningandkoan dsp tuned-fordo the same from the terminal. - A baked EQ splits into a correction and a tuning. With a measurement of the headphones and the target a preset counts as neutral, "Split into Correction + Tuning…" takes a preset like Qudelix's "Lush" apart: a correction worked out from the measurement, and the rest as a tuning made against that target, previewed against the preset before saving. The outputs that played it play the two, and the tuning works on other headphones.
koan dsp splitdoes the same.
Changed
- Settings for the server come in sections. The Server page had grown with every feature. It now holds the address, sign-in, sync, downloads and what the server offers; Account holds the password and API keys; People holds accounts, for admins; Devices gains pairing and the server play queue; Integrations holds ListenBrainz and assistants. On the Mac each is a tab, and on iPhone and iPad a page under Settings. Each shows only where the server has what it holds. The Apple TV keeps one page for the server.
- Releases no longer queue behind stale runs. A newer push cancels an older run of the same pull request, or an older run on main that releases nothing; release runs and manual runs are never cancelled. On main, the macOS and tvOS app builds run only when releasing, since the pull request built them already.
- API key and account errors read as errors in the system look too. Settings showed them in the label colour there, and in the theme's red only under the kōan theme.
- EQ for headphones or speakers, and a steadier EQ page. EQ copy speaks of any device rather than headphones alone. An imported EQ's role is asked in a sheet with an example for each answer and a Decide Later that says what it leaves. The EQ page draws what the output plays at a fixed height, easing between presets, and edits happen on the profile's own page.
- The kōan look, refined after 0.60.0. Buttons come in three weights with at most one prominent action per screen, each on one line; lists, settings and the EQ pages sit on the theme's ground in square sections instead of black or carded rows; the EQ filter table is dense, with short type codes; checkboxes trail their labels; on iPhone, album and playlist headers scroll away and leave the title in the bar. The design rules are in
docs/design/koan-theme.md.
Fixed
- Shelf and search headings are readable when focused on the Apple TV. A focused "Artists ›" or "Albums ›" heading drew the header's light text on the white focus platter; it now takes the TV's row style, which darkens the text on focus.
- The kōan theme, finished in places. Large titles draw in Geist Mono's lighter weights; track lengths of an hour or more and long formats fit their columns; the Mac's output, control and filter popovers, and the last materials, draw on the theme's ground; the album grid's heart follows light and dark; and the iPhone's tabs tell VoiceOver which of four they are.
- The last rows of a long page are reachable on iPhone. In the kōan theme an album, artist, queue or other long list could stop scrolling with its last rows under the mini player and the tab bar. Each page now makes room for the bar itself.
- A tap in a long track listing no longer queues the whole library. Tapping a track in Tracks queued every track in the listing from that row, the whole library on a large server, which made a phone lag and crash. A listing longer than 500 tracks now queues 500 from the row tapped. The iPhone, iPad and Apple TV apps no longer list every track at the top of the Library; tracks are listed from a shelf's or a search's "See all", filtered.
- Play on a record starts at its first track. With the first track still on the server and later ones cached, playback could begin at the first cached track: a stream opened ahead of the download that gave out with nothing heard was taken for a track that had played. It is now waited for and played from disk when it lands; only a track that has failed is passed over.
- Search counts match the results shown, closest matches first. Each section of the search page is now the head of the listing its "See all" opens, ordered by how closely names match: the whole name, then its start, then a later word, then anywhere. Weak fuzzy matches (letters scattered across a name) are no longer listed; fuzzy matching is used only when nothing holds the query as typed, so typos still find what was meant. The album and track browsers gain a Best Match sort while searching.
- A queue of tens of thousands of tracks stays responsive. The engine sent the whole queue to the app on every track change and download, which on a phone meant decoding and regrouping every row each time until the app lagged and was killed. The queue is now sent whole only when it is edited, with the rows whose status moved sent on their own in between, and the iOS queue draws only the rows on screen.
- EQ fixes. An EQ's page on iPhone no longer shows the tab bar over its foot, and changing the target a tuning was made against now syncs to your other devices.
0.60.0
0.59.0 was never published: its macOS notarisation timed out on Apple's side, so its GitHub release and server image did not go out. 0.60.0 is the first release to carry its changes, below under 0.59.0, including the move from schema 20 to 21. Upgrading from 0.58.0 or earlier runs that migration; snapshot the database first.
Added
- The kōan theme. The apps on the Mac, iPhone and Apple TV are drawn as koan.rocks is, by default: Geist Mono, flat greys, square controls and lowercase labels, with the wash kept behind the bare ground. Settings → Appearance → Theme brings back the platform's look, and "Show icons" turns the theme's icons off. The design is set down in
docs/design/koan-theme.md. - Colours from the record, optional. Settings → Appearance turns off the wash and the record's accent together, leaving koan's mint in either theme; the playing bars and the graphics level are untouched (
appearance.record_colours). - Presets imported together become a group. Several whole EQ files chosen together (APO, AutoEQ or Qudelix presets, CamillaDSP YAML) become a profile each and a group holding them, named for what their names share and editable before importing. A group plays one member at a time, picked on its page, on the EQ page or in an output's preset menu; a stack of several layers can be made a group and back. Files that are parts of one profile, such as a response or Convolver
.cfgfor each channel or rate, a folder, a zip or REW's file for each side, still combine into one, and the app says which will happen before it imports. A name already taken gets a number, AutoEQ's fixed-band file is left out beside its parametric twin, each refused file is named with why, and import errors are written tokoan.log. - Headphones corrected from a measurement. Headphones AutoEQ doesn't cover can be corrected from a measurement (a squig.link or REW CSV) to any target, through a guided sheet that previews the result; the correction is worked out again for each target chosen. An AutoEQ install moved to another target is now rebuilt from the measurement AutoEQ kept, and a ready-made EQ can be told the target it was made for. A neutral in-ear target, diffuse field after ISO 11904-1, ships beside the over-ear one, and each target says in the picker what it does. "Headphone EQ, explained" in the guide covers measurements, targets and corrections.
Changed
- The accent follows the record more legibly. In either theme the record's colour is tone-mapped before it tints anything: its hue kept, its lightness held to a band per light and dark mode, its chroma floored so a dark or muddy sleeve still gives a clean colour, and moved away from the error red. Where it cannot reach 4.5:1 against the background it marks selection and progress but never colours text.
- A larger Settings window on the Mac. It opens at 820×780, can be resized, and keeps its size between launches, so the longer panes, EQ among them, no longer scroll on a laptop screen.
- A DSP change while playing no longer clicks. Editing a band or switching a profile used to cut the output mid-waveform and restart it. The old processing now fades out over 15 ms and the new one fades in over the same, a short dip in place of a step. Pausing keeps its own, longer fade.
- Each EQ profile says what it is for. A profile is a correction, a tuning, or baked (a correction with a tuning already in it, as most named presets are), shown as a badge wherever profiles are listed; imports ask which. A stack holds one correction: a second layer is refused, and a stack made before that rule still plays and says which two it holds. A correction's target is chosen inside it, and its bands and sync settings sit under "Bands, sync and more". "Kept: On every device" is now "Sync: Everywhere".
- A release no longer waits on Apple's notary. 0.59.0 never published because notarisation sat "In Progress" past the release's timeout. Releases now publish once everything is built and signed; a separate job notarises the macOS binaries and the app, staples the DMG into the release, and moves the Homebrew cask to it, re-runnable on its own without releasing again.
Fixed
- Find in AutoEQ stays open on iOS. Opened for the first time from Settings → EQ, it closed itself as AutoEQ's index arrived.
0.59.0
The library database moves from schema 20 to 21. The upgrade only adds tables: the EQ profiles a server keeps for its accounts, and a device's record of what it synced. Every existing row is kept as it was, and the upgrade runs in one transaction. Builds older than this one refuse a schema-21 database, so going back means restoring a copy taken before upgrading.
Added
- EQ profiles on every device. Signed in to a kōan server, a profile kept On every device is synced to the account's other devices: filters, preamp, target, layers and its files, but not which output plays it. AutoEQ corrections and profiles of bands go everywhere until chosen otherwise; room and speaker corrections stay on their device, as does everything a device had before it first synced, unless it came from AutoEQ. The later change to a profile wins, deletions reach every device, and a stack kept everywhere cannot layer a profile kept on one device. The server offers this as
koanDspProfiles, reached only with the account's password or an API key.
Changed
- EQ profiles play within fixed bounds, and DSP output never passes full scale. A preamp set by hand is lowered when the profile's filters or impulse response would push the peak above full scale, so a profile with a 0 dB preamp over a boost, or a room correction whose response peaks above 0 dB, plays quieter after upgrading; its page shows "preamp −X dB for headroom". Every profile is held within the bounds in Bounds: values clamped, and at most two seconds of delay and two graphic curves a channel, eight mixes, and impulse responses of 262,145 taps. A moved target counts as a graphic curve and is the one dropped past the count. Each profile's page says what was adjusted. Whatever the chain puts out is held within full scale, with anything that is not a number turned to silence.
- Opening the Output menu while controlling another device asks it for its outputs again. The menu showed whatever that device last published; it now lists its outputs and presets afresh each time the menu opens, as this device's own menu always has.
Fixed
- A maker AutoEQ files under two names is one maker. AFUL and AFUL Acoustics, HEDD and HEDD Audio, JQ and JQ Audio, OLLO and Ollo Audio, and Sivga and Sivga Audio were each listed twice under Find in AutoEQ, with their models split between the two; they are one now, in browsing, searching and offering a headphone's correction, and each result keeps the name AutoEQ gives it. Alpha Design Labs, Ambient Dynamics, Sound Intone and Sound Linear are no longer listed under their first word.
- Qudelix PEQ presets import. A preset exported from the Qudelix app was refused at its first line (
TYPE: PEQ). Its//comments, type line and closing impedance and sensitivity lines are now read past, each channel keeps its own preamp and filters, and a preset of another type, such as a graphic EQ, is refused by name. - A phone controlled from another device shows its real output. The output menu named the phone's route "System Output" with no preset, because the phone listed its outputs once, before it knew the route. It now publishes the route by its port name ("Qudelix-5K", "AirPods Pro") with the preset that route plays through, and again whenever the route changes.
0.58.0
The library database moves from schema 19 to 20 (new tables for Subsonic saved play queues; every existing row is kept). Upgrades now run in one transaction and roll back whole if any step fails, and a server finding the database newer than it knows drains and exits. Builds older than 0.58.0 refuse a schema-20 database, so going back means restoring a copy taken before upgrading.
Added
- Scrobbling is set up in the apps. Settings → Server → Scrobbling in the Mac and iOS apps connects the account's ListenBrainz with its user token, shows how many plays are waiting and any token ListenBrainz stopped accepting, and disconnects; the Apple TV shows the connection. It is offered where the server lists the
koanScrobblingextension, through which the server checks and keeps the token and never returns it. The web UI's Scrobbling page does the same. - Assistants in the apps. Settings → Server shows the server's MCP address to copy and links to its page on connecting Claude or another assistant, where the server knows its public address (
sharing.public_url). The server offers this askoanMcp. - API keys in the apps. Settings → Server lists the account's API keys, makes one for another Subsonic app (shown once, to copy), and revokes one, which is how a lost device is signed out. The server offers this as
koanApiKeys. - Passwords from the apps. An admin can set another account's password from Settings → Server, and anyone can change their own there, giving the current one. The device that changes its own stays signed in with a new key; every other device of the account signs out. The server offers this as
koanSetUserPassword(extensionkoanPasswords), and a wrong current password counts against the account's sign-in limit. - kōan's apps can keep their queue on the server. Off by default, Settings → Server → Keep the queue on the server keeps this device's queue in the account's saved play queue, so a queue started in Feishin, Symfonium or another Subsonic client can be picked up in kōan, and the reverse. Turning it on asks before replacing this device's queue with the server's. Edits are saved as they settle, a change of track or a pause with the playhead, and at launch the server's queue is taken only if another client saved it since (#874).
- Saved play queues over the Subsonic API. Clients that save their queue on pause or exit and offer to resume it on another device (Symfonium, Feishin, Supersonic) can now do so against a kōan server:
savePlayQueueandgetPlayQueuekeep one queue per account, and the OpenSubsonicindexBasedQueueextension (savePlayQueueByIndex,getPlayQueueByIndex) names the current song by its place, so a song queued twice is unambiguous. kōan's apps use it only when set to keep their queue on the server. The library database moves to schema 20 for theplay_queuesandplay_queue_entriestables; a build older than this one refuses it. - Your own devices are yours on the local network too. Devices signed in to the same kōan server prove to each other that they share an account, with keys the server publishes and signatures over fresh nonces, and a proven device has the account's powers instead of a nearby device's: handing your phone music it has not synced yet now syncs it rather than dropping it. Commands from a proven device are signed, so none can be replayed or slipped into the connection. Devices that prove nothing are trusted as before.
- Servers keep and publish device keys (
koanDeviceKeys). A device that links with an API key may register a public key, kept on that key, so revoking it drops the device's key too; the account's devices are sent each other's keys, and those of devices shared with them. The groundwork for a device proving on the local network that it is yours. - The Mac app can keep running in the menu bar. A Mac cannot be woken from another device, so a closed kōan was out of reach. With Keep running in the menu bar on (Settings ▸ Devices, off by default), closing the window leaves kōan running, signed in and listening, out of the Dock, with a menu bar item for what is playing, play and pause, next, opening the window and quitting. Open at login beside it brings the Mac back within reach after a restart. The Control menu now lists a Mac it cannot reach as not running, rather than asleep.
- An EQ page with a graph of what plays. The Mac, iOS and tvOS apps' EQ settings, and each profile's page, draw the response of the filters the DSP runs, each band behind the total, and for an AutoEQ correction the headphone as measured against its target and corrected. Parametric bands are edited in a table (type, frequency, gain, Q) or by dragging them on the graph, and heard at once.
- Layered EQ. A profile can play others first, in order, each switched on or off: a headphone's correction, then a bass shelf or a tilt on top, without editing the correction itself.
- Choose a target for an AutoEQ correction. A headphone installed from AutoEQ can be moved from the target it was made for to another: Harman over-ear 2018 or in-ear 2019 (with or without their bass shelf), oratory1990's, AutoEQ's in-ear, or diffuse field, each described in the picker. The difference between the two plays after the correction. A target of your own can be added from a CSV or a squig.link export.
- Find in AutoEQ by maker and model, before anything is typed, and AutoEQ offered for headphones whose own names leave the maker out, where the name still says which model and generation they are (Sony WH-1000XM4, AirPods Max). A name that says only roughly (AirPods Pro, a Bose QC45) is offered a search for the model instead, to pick the variant from.
- AutoEQ in the apps. Find in AutoEQ… in the Mac and iOS apps' EQ settings searches AutoEQ by headphone name and installs a result for the output in use. An output whose name ends with a headphone's full name, maker included, is offered AutoEQ's profile for it; the match is strict, and the offer can be turned down per device.
- Siri on Apple TV: play, pause and play a record. "Play a record in kōan" asks which, and finds it in the library as the search page does. "Play kōan" and "Pause kōan" act on the queue. They start audio with the app in the background, and wait for the engine if Siri launched the app.
Changed
- A schema upgrade is one transaction, and stops an older server sharing the database. A migration that fails part way leaves the database as it was, and another process reading meanwhile sees the old schema or the new one. A server whose database a newer koan has upgraded under it stops handing out connections, drains and exits, so it never writes to a schema it does not know.
Fixed
- The Mac and iOS apps say when a command to another device is waiting or did not arrive. "Waiting for Phone to wake" when it was queued for a device asleep, and "Couldn't reach Phone" with the reason when it was refused or failed. Moving the music goes by the answer to the Play it sends: there, waiting for a device asleep, or refused, in which case the music plays on where it was. A device that predates answers is still watched for the track, as before.
- A command to another device is no longer taken as delivered when it was only queued (#870). A device now answers each command once it has acted on it. With no answer the sender tries the next way through (the local network, the link, then one request to the server) with the same command id, and a device that gets it twice acts once. The server answers for a device that is away, once it has been woken to take the command, and takes a link that has sent nothing since the command for dead, dropping it and waking the device instead of waiting out the 100-second silence. Devices and servers that predate this are sent commands as before.
0.57.0
Added
- The web UI can sign in through an authenticating reverse proxy. With
graphql.proxy_auth_headernaming the header a proxy such as Authelia or Authentik sets (Remote-User), andgraphql.proxy_auth_fromthe addresses that proxy connects from, the web UI signs in the account the header names without asking for a password. The header is read only on web UI pages and the MCP consent page, ignored from any other address and when it carries more than one value, and an account the server lacks is refused, not created. The proxy must cover those pages and strip the header from incoming requests; Behind an authenticating proxy lists the exact paths to exempt, with Caddy and Traefik examples. A session through the proxy has no refresh cookie and is derived again from the header on each page load, so it lasts no longer than the proxy's say-so, and a browser whose proxy sign-in changes is handed to the new account. Turning proxy mode on does not end web sessions signed in with a password before it; the guide says how to. A header from the proxy that names no one account, or an account the server lacks, signs the browser out rather than leaving it on the session it had. It is on only with both settings set; the server refuses to start with one alone, with an entry it cannot parse, or with a range covering every address, and logs the header and addresses it believes when it is on. The Subsonic API, GraphQL, MCP and kōan's apps keep kōan's own sign-in. This is Navidrome'sND_REVERSEPROXYUSERHEADER. - AutoEQ search from the command line.
koan dsp autoeq searchfinds a headphone in AutoEQ's index by name, andkoan dsp autoeq installsaves its parametric EQ as a profile, optionally for an output device. The index is kept beside the config and refreshed at most daily. playback.mutedandplayback.renderers. Muted, playback runs as usual and plays silence; with renderers off, no UPnP renderer is looked for. The iOS and tvOS UI tests set both, so a walk on a shared machine is not heard through its speakers and cannot reach a renderer on its network.
Security
- An app password could make accounts, invites and keys. The account endpoints kōan's apps use (
koanUsers,koanCreateUser,koanInvite,koanSetUserRole,koanDeleteUser) and approving a device's pairing (koanPairApprove) accepted any Subsonic credential. Someone holding an app password, or a capturedt/stoken for one, could sign a device in as the account and keep its API key after the app password was revoked; an admin's could also create an admin account, invite or reset its own account, and change roles. These now need an API key or the account's own password. The shared secret is refused too.
Changed
- One server scans a shared library at a time. Servers sharing a state directory, as two do while one replaces the other, take turns: the one holding
watch.lockbeside the database scans and watches the library folders, and the other serves without scanning until it can take the lock. A server whose database a newer koan has migrated now exits with that reason instead of a panic. - Rescans stat each file once. Removing tracks whose files are gone checked every row under the folder again after the walk had just found them; it now asks only about the rows the walk did not find, which still have to be confirmed missing before they go. Importing dropped files skips the ones already read, as a scan does.
Fixed
- Large form POSTs to the Subsonic API no longer fail. A form body past about 64 KB was refused with an empty 400, because it was rewritten into the request's URL, which is capped there;
createPlaylistorupdatePlaylistwith more than about 1,600 songs failed. Forms are now read beside the URL up to 1 MiB, and one past that is refused with a Subsonic error. - Subsonic clients showed no hearts outside the starred list. Songs, albums and artists never carried
starred, so a client that reads it on album pages, search results and album lists showed nothing as favourited. They now carry the time the account favourited them, asgetStarred2always implied. - Folder-browse Subsonic clients get hearts and ratings too.
getIndexes' artists and the albumsgetMusicDirectorylists under an artist carried nostarred,userRatingorplayed, so a client browsing by folder (DSub and similar) showed none of the account's favourites or ratings there. They now carry the caller's own, read for the whole listing at once (#864). - Cancelling a library scan stops the folder watcher's too. The watcher's scans had no way to be stopped, so the apps' Cancel did nothing to the scan the activity row was showing. Forgetting a library folder now also stops a scan of it, rather than leaving it to index again what was just forgotten.
- Scans no longer run over each other. A full scan and the folder watcher's rescans now take turns, instead of reading the same files twice and pruning what another was about to index. An import of dropped files does not wait for them: it only adds, and it is for playing now.
- Moving the music to another device says when it has not arrived. A hand-off paused the music here and counted it as delivered once the command was queued, which it was even on a link that had died unnoticed or for a device asleep. The Mac and iOS apps now wait for the other device to report the track, and otherwise say it has not picked the music up yet; the music stays paused where it was.
- The Live Activity's buttons go by the server first. iOS runs them without waking the app, whose link is then most likely dead, and a command put into it was lost. The server knows whether the device is linked and wakes it if not; a device only on the local network is still reached directly.
- A command from another device no longer holds up the link. One that needed a library sync first ran on the link's own thread, which left the socket unread for as long as the sync took. Commands from other devices now run on their own lane, in order.
- The Live Activity's timer no longer jumps back when the device list is published again for another device's change. Each device's playhead is given as of publishing, not as of its last report.
- A library folder removed and added back left its server-held tracks without their files. A track also on the server outlives its folder being forgotten, as the server's copy, and kept its file's scan cache entry, so a scan after re-adding the folder took the file as already read and never linked it again. Forgetting a folder now clears the folder's entries.
- Full scans indexed what the folder watcher ignores. Syncthing's
.stversionscopies, macOS's._AppleDouble files and the like were indexed by a full scan and by a rescan of a directory, though the watcher skips them. Both now skip the same names. Tracks already indexed from such paths stay until their files go. - The folder watcher ignored music whose name starts with a dot. It skipped every name with a leading dot, so an album such as "...Baby One More Time" was indexed only by a full scan. It now skips only the names Syncthing, macOS and version control leave in folders.
0.56.0
Added
- An Apple TV finds its server on its own. kōan on a phone or Mac announces the server it is signed in to on the local network, without the account, and a signed-out TV lists each server it hears of on its sign-in page, a press away from a pairing code. It keeps looking while the page is open and asks for kōan to be opened on a signed-in device; typing the address stays as the fallback. A device that is not discoverable announces nothing.
Security
- Password guessing is limited per account, whatever the address. The per-address limits on failed sign-ins did not stop a guesser with many addresses. A username now has 60 failed password sign-ins a minute across every address and every door that takes a password: Subsonic
p=and token sign-ins against app passwords,/auth/loginand the web UI's form. That is far more than a person mistyping reaches. So that an outsider spending the budget cannot lock an account out, the networks it signed in from in the last week (by password, or by a browser refreshing its session) are spared it. API keys and the Subsonic shared secret are random and not counted, so a flood of wrong passwords cannot lock out apps signed in with them. - A Subsonic password guess could skip the sign-in limits. A request for the shared username carrying
tbut noswas exempted as a shared-secret token, while the server checked itsp=instead. The exemption now requires both, exactly as the check does. - Per-address limits count an IPv6 client by its /64. One subscriber is usually given a whole /64, so keying on the full address gave a client a fresh allowance per address. IPv4-mapped IPv6 addresses now count as the IPv4 address they carry.
- The web UI's sign-in shares the server's ceiling on password checks. It ran argon2 with only a per-address limit, so requests from many addresses could run any number of checks at once. It now goes through the same verifier as the Subsonic API and
/auth/login. - An account's name could run script on an admin's Users page. The Delete button's confirmation put the escaped name inside a Datastar expression, which the browser decodes before evaluating. The name is now passed as data.
- Sockets close when their account changes. A GraphQL subscription socket or an app's link kept the access it opened with: a demoted admin kept admin over
/graphql/ws, and a deleted account, a new password, a revoked key or app password, or a device's key replaced when it signs in again left both open. They now close when anything about the account that can narrow its access changes, and a subscription socket also closes when its token expires. Clients reconnect and are authenticated as things then stand; kōan's apps treat it as any dropped link.
Changed
- Tapping the server's address in Settings → Server copies it, in the Mac and iOS apps, for signing another app or device in to the same server. The row reads Copied for a moment.
Fixed
- The Apple TV's filter and sort did nothing. In the navigation bar they took focus, but tvOS never showed the sheet or menu they open. They are now a row of buttons above the album, artist and track listings, named in full.
- The Mac sidebar's footer no longer draws over the last playlists. In a window too short for every playlist, the rows scrolled under the library counts and both were unreadable. The footer now has the sidebar behind it and a line above it.
- Playlist sync no longer removes songs from the server's copy. A server playlist naming a song the library had not synced yet was stored without it, and the next edit pushed that shorter list back, deleting the song on the server. Songs the library does not have now stay on the server: every push puts them back where they were. A database error while reading a playlist is reported rather than read as an empty list, and a playlist whose entries are all local files no longer empties its server copy; only one emptied by hand does.
- A server that lists no playlists no longer deletes yours. A playlist the server stops listing is now deleted locally only once the server, asked for it, says it does not have it; a listing that comes back short or empty deletes nothing. A failed lookup no longer creates a duplicate of a playlist, and a playlist's name, owner, contents and sync state are stored together or not at all.
- Organize keeps playlists read from M3U files. Moving an album moved its
.m3uwith it, and the next scan read the list as deleted, made a new playlist under a new id, and dropped every entry whose file had been renamed. Organize now rewrites the M3U files in the library to name the files where they went, and moves the playlist with its file; undo puts both back. - Organize undo survives an unplugged drive. Undo dropped the record of any move whose destination it could not see, including every file on a drive that was disconnected. It now drops one only when the file is gone while the library folder or drive it was moved to is still there, and otherwise keeps it for when the drive is back. An album deleted by hand after organizing still leaves the batches before it undoable.
- A symlinked share going away no longer deletes its tracks. With part of the library linked in from a network share, the share being unmounted made every file under the link read as deleted, and a rescan removed those tracks with their play history, whatever the size of the removal. A file is now taken as deleted only when the folder that should hold it is there.
- Moving or renaming files outside kōan keeps their history. A file that disappeared from one path and appeared at another was indexed as a new track and the old one deleted, with its play history, favourites, ratings and playlist places. A file found at a new path now takes over the track of a file gone from the index's view, when it is the same recording, the same place on the same release with the same size or length, or, for an untagged file, the same size, length and modification time; when more than one gone file fits, none is taken. This holds within one scan or one batch of the folder watcher, and across library folders in a full scan.
- Files whose names are not UTF-8 no longer lose their history on every scan (Linux). The name was stored altered, so the same scan that added a track removed it. Such files are now skipped with a warning.
0.55.0
Added
- kōan on Apple TV. The engine and the iOS app's pages on tvOS, built for the remote: Now Playing is the first tab, with the sleeve, controls and what comes next; the tabs run across the top; a long press opens a row's menu; Play/Pause works from anywhere. A TV is a device the phone and the Mac play to with Play on, and plays gaplessly through HDMI. It signs in with a password, an OpenSubsonic API key, or a koan invite pasted from a phone, so any OpenSubsonic server works. Share links show as a code to scan, since a television has no pasteboard. tvOS keeps app data only in a cache the system may empty; the configuration, sign-in included, is mirrored into the app's preferences, which tvOS keeps, and put back after a purge. The library is synced again.
- Signing in with an API key. The account form takes an OpenSubsonic API key in place of a password, on every platform: one key per device, revocable on its own.
devices.nearby. Off, a device takes no part in the local network: it neither listens nor announces itself, and neither looks for other devices nor dials them, reaching them only through the server. For a shared network, and for test runs that relaunch an app over and over, which would otherwise announce it to every device in the house each time; the television's UI tests set it.- Sign an Apple TV in by pairing. Signed out, the TV asks for its server's address and shows a QR code and a code. Scanning the QR code with kōan on a phone signed in to that server, typing the code under Settings → Server → Pair a device on a phone or Mac, or entering it on the server's
/pairpage signs the TV in at once. Every ending says what happened and offers a way back: a declined or lapsed code is asked for again, and a server without pairing is pointed to the account form, which takes a password, an API key or an invite as before.
Changed
- Signing in to a kōan server with a password ends in an API key (#819). The apps and terminal UI send the password once, over plain HTTP too, to the new
/rest/koanSignIn, and keep the API key it returns for the device in place of the password, as an invite does. Signing in again from the same device replaces its key rather than adding one. An app password or the shared secret typed in place of the password is kept as before. Signing in over plain HTTP no longer fails with error 41. Other Subsonic servers are unchanged, and error 41 from one now reads as needing an app password or API key. Servers list thekoanSignInextension.
Fixed
- A device whose sign-in the server refuses now says so. When a key is revoked or a password changed, the server answers every request from that device with error 40, 41 or 44, and the apps went on showing an empty library as if a sync were still to come. The refusal is now noticed on sync or when the server is asked what it offers, and Settings → Server, the iOS Library tab and the empty Albums, Tracks and queue pages say Your server refused kōan's sign-in. Sign in again in Settings → Server. until the device signs in again or the server accepts the credential once more. See Authentication.
- A playlist's play button played the wrong tracks. It looked its tracks up by the playlist's entry numbers rather than the tracks' own, so it played whichever tracks happened to share those numbers, often one already queued. It now plays the playlist. The transport also names what is loading from the moment play is pressed, and play and pause wait until it has loaded rather than acting on the queue it replaces.
- A long Ogg track streaming from a server showed no length. Ogg keeps its duration on its last page, which arrives last; a track opened before then now runs on the library's duration, so a nine-hour recording shows its length and progress from the start.
0.54.2
Changed
- The sleep timer eases you to sleep. A timer set for a time now fades over a tenth of its length, between one and five minutes (90 seconds for 15 minutes, 5 minutes for an hour), reaching silence at the deadline; the end of a track or record fades over the track's last minute. The level falls evenly in decibels rather than over six seconds, and the timer shows Fading meanwhile. Playback is not bit-perfect during the fade, since it is a gain on the samples; a UPnP renderer's own volume is stepped down instead and put back after. Cancelling or changing the timer mid-fade brings the level back over a second, and pausing by hand cancels it.
Fixed
- Seeking or skipping at the end of the queue could freeze playback. When the player was busy, the decoder reporting the end of the queue and the player stopping that decoder could wait on each other indefinitely.
- A rare crash when the Mac or iOS app changes track or output. When CoreAudio could not confirm the output had fully stopped, its playback data was freed while the audio thread might still read it. It is now kept instead.
- One failed command no longer stops the Mac and iOS apps' controls. An error such as importing a malformed EQ or convolution file stopped every later play, queue and transport command until the app was relaunched; the failing command now reports an error and the rest carry on.
- The iOS Live Activity no longer busies the app for a record without art. Controlling another device playing a record with no cover, or whose cover could not be fetched, asked for the cover again continuously.
- The Mac's lyrics panel opens without tearing the window. Opening or closing it slid the panel while the album grid and track lists jumped to their new width at once, so for a moment the two halves of the window were out of step and the sidebar was pushed off the left edge. The panel now opens and closes in one step, with every page laid out alongside it.
- The sleep timer's moon is lit only while a timer is set. On the Mac it showed in the accent colour with no timer set.
0.54.1
Added
- Downloaded, and offline mode on iOS. A Downloaded page on the Mac and iOS lists the records with files on this device, fully there first, each with a bar showing how much of it is. On iOS, when the server has been out of reach for a few seconds with the app open, the library narrows to what is on the phone: every list, browse, search, shelves and playlists, shows only that, and the queue greys out what cannot play. It lifts by itself when the server answers, and Settings → Offline mode turns it on by hand.
- A Tracks browser, and Recently Played filters, in the Mac and iOS apps. Tracks is a new browser beside Albums and Artists (⌘7 on the Mac), and the browsers gain a Recently Played filter and a Last Played sort, which a shelf's headings open (below). The Favourites and Recently Played pages no longer have a filter field: narrowing them is what a heading opens.
- Covers from image files beside the tracks (#814). A
cover,folderorfrontimage (JPEG, PNG or WebP, any case) in an album's folder is now its cover, ahead of art embedded in the files, in Navidrome's default order, so a library that keeps its art that way shows it everywhere: the apps, the terminal UI, the web UI, share pages, the Subsonic API, GraphQL and UPnP renderers. An album split into disc folders takes the image from the folder above them. Adding, replacing or removing an image is noticed by the folder watcher; the apps drop the cover they had cached for that folder's records. - A shelf's headings open its browsers, in place of See all. On Favourites, Recently Played and search, in the apps and the web UI, each section's heading reads as a link: its name, how many there are in all, and a chevron. It opens the browser filtered to the shelf, whether or not the section shows all it has. The separate See all is gone.
Changed
- The Control menu lists only devices you use. A device out of reach was kept, asleep, until it was forgotten, so every phone, simulator and stranger ever seen stayed in the list. Now one is kept asleep only if this device has controlled it or sent it music; one never used goes once it has been gone for a heartbeat. On upgrade only the device being controlled is kept from the old list. Forget still removes one you have used.
- Now Playing on iOS has room for its controls. The row under the transport held the lyrics, the sleep timer, the device, output and preset buttons, the format and AirPlay, and at a phone's width the output and preset were cut to a letter or two. It is now two rows: the lyrics, the sleep timer, the format and AirPlay; then the device being controlled, the output and the preset, each named in full where it fits, spread evenly, and shortened only when a name will not fit beside the others.
Fixed
- The Mac's shelf, search and album grid follow the window when it widens. Opened in a narrow window, Recently Played, Favourites, search and the album grid kept their narrow layout when the window grew.
- The web UI on a phone. A favourite track shows its heart beside the row's ⋯ again, as a mark; the heart to press is in the menu. History rows give the title the width the tick boxes took: on a phone a play is removed with Remove from History in its menu, as in the apps, and the time is set smaller. On a wide screen the Tracks browser's name field is wide enough for its hint.
0.54.0
The library database moves from schema 16 to 19 (new tables for ratings, bookmarks, scrobbling and smart playlists, and the play history table rebuilt for sharing between devices; every existing row is kept as it was). Builds older than 0.54.0 refuse a schema-19 database, so going back means restoring a copy taken before upgrading.
Added
- Sign in a device by approving it. The server side and the approving side of pairing, for the Apple TV app still to ship: a device with no keyboard can open a pairing on the server and show a code and a link instead of asking for a password. Opening the link in kōan on a phone or Mac, typing the code in Settings → Server → Pair a device, or typing it on the server's
/pairpage asks whether to sign the device in; approving signs it in as you, with an API key of its own named after it, revocable like any other. The device hears the answer the moment it is given, over the socket it opened. Each approval screen says where the request came from, and whether that is your network or the internet, since anyone can send a link to approve. A pairing lasts ten minutes and is kept only in memory; web pages cannot open one, and one address can have three waiting. Servers list thekoanPairextension. - Bookmarks over the Subsonic API. Clients that save a place in a long track (audiobooks, podcasts, mixes) and offer to resume from it can now do so against a kōan server:
createBookmark,getBookmarksanddeleteBookmarkkeep one position and note per account and track. kōan's own apps do not use them. The library database moves to schema 18 for thebookmarkstable; a build older than this one refuses it. - The Subsonic API transcodes for clients that ask. A client that asks
streamfor amaxBitRatebelow the file's, or forformat=opus,format=mp3orformat=aac, gets an Opus, MP3 or AAC (ADTS) encode made byffmpeginstead of the original, so a lossless library no longer costs full bandwidth on mobile data.format=rawanddownloadstill return the original. Seeking within a transcode usestimeOffset(OpenSubsonictranscodeOffset). The container image now includesffmpeg; elsewhere[subsonic] ffmpegnames it, and where it does not run, or a server or account is at its limit of concurrent transcodes, originals are served as before.[subsonic] transcode = falseturns it off. - Ratings over the Subsonic API. Clients that rate songs, albums and artists from one to five can now do so against a kōan server:
setRatingstores a rating per account (0 clears it), every song, album and artist carries the caller'suserRating, andgetAlbumList2?type=highestlists rated albums best first instead of nothing. kōan's own apps do not show ratings. The library database moves to schema 17 for the three rating tables; a build older than this one refuses it. - Favourites in the web UI. The signed-in account's favourite artists, records and tracks on one page, laid out as in the apps: artists as pills, records as tiles, and the tracks as a list that plays on from the one picked. On a phone it sits under a new Library tab with Playlists, which the tab bar had no room to add beside; the sidebar lists both.
- Recently played in the web UI. The artists, records and tracks the signed-in account played in the last 30 days, each once and newest first, on the same layout as Favourites.
- See all, and a Tracks browser, in the web UI. Favourites, Recently played and search show the first few of each kind, with a count, and See all opens the album, artist or track browser filtered to the same set in the same order, so the count and the list always agree. The browsers gain a Recently played filter and a Last played sort, and Tracks is a new browser with the same filters, paged at 200.
- Hearts in the web UI. Tracks, records and artists can be favourited from the browser: a heart on every track row, record tile, album and artist page. It is the same favourite the apps and the Subsonic API's
starmake, per account, so the account's apps pick it up at once. Read-only accounts see no hearts. - A track menu in the web UI. Right-click a track row, or press and hold it on a phone, for what the apps' context menu offers: Play, Play Next, Add to Queue, favourite, share, Go to Album and Go to Artist. On a phone a row shows only a ⋯ button for it, so its title has the width.
- History in the web UI. What the signed-in account has played, most recent first, grouped by day in the browser's own time zone. Tick plays and forget them, as in the apps; only the account's own plays can be forgotten.
- Sleep timer (#795). Stop playback after 15, 30, 45 or 60 minutes, fading out over a few seconds, or at the end of the track or record playing. It pauses rather than clearing the queue, so playing again carries on from there. The timer is the player's, so it holds while iOS suspends the app, and it is set on the device playing: a phone controlling a Mac sets the Mac's, over the link. From the moon in the Mac and iOS transport,
Tin the terminal UI, andsetSleepTimerOnClientfor assistants. - Scrobbling to ListenBrainz. Each account can connect ListenBrainz on the web UI's Scrobbling page, under Account, by pasting its user token. The server then sends the account's existing history, and from then on every play kōan's apps and other Subsonic clients report, with now-playing notices; no client needs configuring. Plays wait in the database until ListenBrainz accepts them, so an outage or restart delays them rather than losing them. The library database moves to schema 19 for the new
scrobble_servicesandscrobble_outboxtables; a build older than this one refuses it. - Smart playlists. A playlist can hold whatever matches a set of rules instead of a list: text, number and date conditions over title, artists, album, genre, format, path, year, duration, bit depth, sample rate, play count, last played, date added and favourites, grouped with all/any, sorted (or shuffled) and limited. Plays and favourites are the owner's. kōan evaluates the rules when the playlist is read, at most once a minute (a random order once a day), and at once when a scrobble or a favourite the rules read reaches the server, telling linked devices to pull; it rewrites its contents only when they change, keeping entry ids so a queue following it keeps its place. Every client sees an ordinary playlist that cannot be edited: Subsonic apps get OpenSubsonic's
readonly, kōan's apps refuse drops, removals and reorders and leave it out of Add to Playlist. Made withcreateSmartPlaylistand changed withsetPlaylistRulesover GraphQL, so an assistant connected over MCP can make one, or read from Navidrome.nspfiles in the library folders, which scans and the folder watcher pick up; the file names the playlist and decides its rules, so neither is edited in kōan. A playlist a Subsonic server marks read-only is mirrored read-only and never pushed back. The library database moves to schema 19 for the playlist columns; a build older than this one refuses it. See Smart playlists. - M3U playlists in the library folders are imported.
.m3uand.m3u8files become playlists of the tracks they list, with paths relative to the file, absolute orfile://, Windows separators understood, plain.m3uread as Latin-1 when it is not UTF-8 and UTF-16 read behind a byte order mark. Entries naming tracks not yet indexed fill in after the scan that adds them. The file decides what the playlist holds: scans and the folder watcher follow its changes, deleting it deletes the playlist, and the playlist cannot be renamed or edited from any client. See Smart playlists. - Play history is shared between devices on a kōan server. Signed in to a kōan server, History on each device shows the plays the account's other devices made alongside its own, arriving as they are scrobbled. Forgetting a play or clearing history, in the apps or on the web UI's History page, does so on every device on the account. A device's skips stay on that device, since the server keeps only plays heard long enough to count. Servers list the
koanHistoryextension. The library database moves to schema 19 for the newplay_history_forgottenandhistory_outboxtables, andplay_historyis rebuilt so its ids are never reused; a build older than this one refuses it. - Recently played. A page in the Mac and iOS apps, laid out like Favourites, for "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, at most 50 of each. It is worked out from play history, so it follows each play as it is recorded, and History now does too. On the Mac, ⌘6.
Fixed
- Two Subsonic error messages read wrongly.
getCoverArtfor a record with no art said "No cover art embedded not found"; it now says "Cover art not found". Error 41 pointed at an "API keys page" that is now the Account page. - Resuming on an amplifier after it was stopped while paused continues from where it was. koan reads a renderer's state and position with two separate calls, so a stop landing between them read as paused at 0:00, and resuming could start the track again. A paused renderer's position now moves only when two readings agree.
- Plays made offline reach the server. A scrobble the server did not take was dropped. It now waits on the device and is sent, dated to when the track started, once the server answers again, to Navidrome as well as kōan.
0.53.0
Added
- App passwords for Subsonic apps that only sign in with a password token. Many Subsonic clients sign in with
t = md5(password + salt), which needs the password on the server, and kōan only keeps a hash of yours, so they were refused with error 41. On the Account page you can now make an app password per app: generated, shown once, stored encrypted under a key derived from the server's signing key, and usable as a token or as a password. It is never your real password, it can be revoked on its own, and changing your password revokes them all. The error 41 message says so instead of describing a sign-in that no longer existed. The database moves to schema 16 for the newapp_passwordstable.
Fixed
- The web UI's account settings can be reached on a phone. Users, API keys, Assistants and signing out sat under the page on a phone, behind the player and the tab bar, and at the foot of a sidebar that could not scroll in landscape. They are now one Account page, reached from an Account tab on a phone and from the foot of the sidebar, which scrolls when the window is shorter than it.
/keysredirects there.
0.52.9
Changed
- Opus is decoded by
opus-rsinstead ofopus-decoder.opus-rsis a maintained pure-Rust port of libopus 1.6;opus-decoderhas had no release since the one whose slow transform 0.52.8 patched around. Against libopus itself,opus-rsreproduces a 48 kHz stereo music file at 71 dB SNR whereopus-decodermanaged 55, matches it within a few dB at 24 and 32 kbps, and decodes about a quarter faster: 0.20% of a Mac core for a stereo stream. kōan no longer carries a patched decoder of its own. - Seeking in Opus starts clean. A seek now decodes from 80 ms before the target and discards that, as the Opus spec asks, so the decoder has settled by the first sample heard; it used to start cold at the target. A seek into the first 80 ms also drops the stream's encoder delay again, which it skipped before.
0.52.8
Fixed
- The server's container image builds again. 0.52.7's failed, because the patched Opus decoder in
vendor/was not copied in before the dependencies were built. 0.52.7's other changes ship in this release.
0.52.7
Fixed
- Opus playback uses a fraction of the CPU it did. The Opus decoder computed the transform inside every audio frame term by term, with a sine and cosine per term: about a third of a phone CPU core to play one stream, which emptied an iPhone's battery overnight while playing in the background. It now runs a real FFT. The fix is a patched copy of
opus-decoderinvendor/, kept until upstream releases one. - The server stops when asked to.
koannow shuts down on SIGTERM as well as SIGINT. In a container it runs as PID 1, where an unhandled SIGTERM is dropped, so every stop waited out the grace period and ended in a kill: about 30 seconds of downtime added to each Kubernetes deploy. Shutdown waits up to 10 seconds for open connections, since subscription websockets and audio streams never close on their own. - A device that keeps dropping off the network no longer sets every other kōan dialling. Each time one reappeared, or a connection to it ended, every device was dialled again at once with its backoff started over, so one flapping device (here a tvOS simulator) had a phone playing in the background connected to about 800 times in a night. A redial now goes only to the device concerned, and a connection must last 30 seconds before its backoff starts over. On Apple platforms an incoming connection also failed its handshake whenever the request arrived a moment after it, which made the dialler try again; it now waits for the request.
0.52.6
Added
- Share a device with other accounts on your server. On the device, Settings → Devices → Shared with other accounts names another account, offered from the server's accounts as you type. That account then sees the device in its Control menu from any network, labelled with whose it is, and controls it as a device on your own network would: play, pause, skip, the queue, the output, preset and volume, and moving the music to its own devices and back, waking it by push as its own. It acts as itself, never with the owner's powers: nothing of the owner's library, settings, favourites, playlists or history. Stopping the share ends its control at once. Servers list the
koanSharesextension. The library database moves to schema 15 for the newlink_grantstable; a build older than this one refuses it.
Changed
- Devices on the same network get Full control by default. A kōan on the same network can now choose this device's output, preset and volume, and move its music here or away, not only play and change the queue; on a household network that is what is wanted. It still acts as itself: nothing reaches this device's library, files, settings beyond what plays where, or the account's favourites, playlists and history, and music it moves away goes over the network or to its own devices, never to this account's other devices. Settings → Devices → Devices on this network → Playback only restores the narrower rules, for a network shared with strangers.
- An asleep device signed in to another account can be woken from the same network. Choosing a suspended iPad signed in as someone else on your server now wakes it by push, through its own account, when your device links from the same address as it last did: everyone behind one router is treated as one household. The address is kept in the database, so this holds across server restarts. A device on mobile data does not match; sharing it covers that case. A wake grants nothing beyond the network's playback rules.
- Asleep devices stay listed until you forget them. A device out of reach no longer drops off the Control menu after 30 minutes; it stays, asleep, with when it was last seen. Forget, from its context menu on the Mac or a long press on iOS, removes it: from this device, and for one of your account's from the server too, with its push token, and from your other devices. A forgotten device that comes back is listed again. The server still forgets an account device unseen for 30 days on its own.
devices.asleep_grace_minsis gone.
Fixed
- The queue's follow button goes plain when following stops on iOS. A second tap stopped following but the button could stay lit. It is now drawn plain when off and sits on a tinted disc while following, on the Mac as well.
0.52.5
Changed
- Devices that stop answering stay listed, asleep. A device that went quiet dropped out of the Control menu at once, and a phone iOS suspended a moment ago vanished from every other device's list. A device now reads as reconnecting for one heartbeat (45 seconds), so a single missed signal does not mark it asleep, and is then shown asleep with when it was last seen. One a push can wake stays listed and can be chosen. One that nothing can wake from here is shown, cannot be chosen, and is dropped after
devices.asleep_grace_mins(30 by default). Whether a device can be woken is the server's word: it has the device's push token and a push key to send with. The server sends when an absent device was last seen, which older apps ignore. - Choosing an asleep device wakes it, and says how. It is dialled on the local network if it was there within the last minute, then sent a background push, and after about six seconds a notification to tap ("Mac wants to play here"), since iOS delays or drops background pushes and never delivers one to an app that was swiped away. The device's row shows the stage, and why if it did not wake. Each step is logged with its timing on the device choosing, the server and the phone, so a failed wake shows where it stopped. Wake pushes carry a collapse id and expire after a minute.
0.52.4
Added
- The queue can follow what is playing. The jump-to-playing button now also follows: the queue keeps the playing track in view as it moves on, through gapless transitions, skips and repeats, sliding by a row rather than jumping. The button is tinted while it follows; pressing it again, or scrolling the queue yourself, stops it. On the Mac the track keeps its place on screen; on iOS it is kept centred.
Fixed
- Hand-off from a nearby device stays on the network. A device on the same network could make another kōan hand its music to a device on that kōan's account, sent through its server as that account. A hand-off asked for by a device on the network now goes over the network or not at all; "Move here" between devices on one network works as before.
0.52.3
Added
- The playing bars follow the device being controlled. While one kōan controls another, the bars beside the playing track show that device's levels rather than this one's silence. The device sends its levels only while a controller has bars on screen, about forty bytes a frame at its analyser's rate, and stops when the bars go. Frames are drawn a couple of frames behind the playhead and interpolated, so a late one is not seen, and the bars settle to rest when the music pauses or the link stalls. A device on the same network may watch the bars of one it can already see playing; through a koan server, only the account's own devices can. The server must be this version or later to relay them; with an older one the bars stay at rest.
Fixed
- Quitting while playing to an amplifier no longer leaves two things playing at the next launch. Quitting stops the amplifier, which otherwise played on until its buffer ran out. At launch, a session that was playing waits while kōan looks for the amplifier it used, and plays there if it turns up, or here if it does not, rather than starting here at once. An amplifier still on a track a kōan on this machine sent it is taken back, not left as someone else's.
0.52.2
Changed
- Control and Output are separate menus. The one Play on menu mixed two choices. Control picks which kōan the transport and queue command; Output picks where the device in view plays, with each output's preset and the amplifier's volume. While another device is controlled, Output lists that device's audio devices and amplifiers, and picking one switches it there with the music carried over, playing or paused. Linked devices publish their outputs with what they are playing; changing another device's output, volume or presets is open to the account's own devices only, not to strangers on the network. The Output menu for a device linked through the server needs the server updated as well.
Fixed
- The Mac app takes the record's colour again. Opening an album could leave the play button and the page's controls in koan's mint while the window behind them was washed in the sleeve's colour. The colour was worked out while the page drew, and when it landed just before the room went to look for it, nothing told the room, so it kept the accent until something else redrew it. Mint is now only for a record with no artwork or no colour in its sleeve.
0.52.1
Added
- Shuffle and repeat. The transport has a shuffle button and a repeat button that steps through off, the whole queue and one track: on the Mac's transport bar, in Now Playing on iOS, under
sandRin the TUI, through Control Center's shuffle and repeat controls, and through GraphQL (nowPlaying { shuffle repeat },setPlayMode,setPlayModeOnClient). Repeating the queue runs the last track into the first without a gap, and the first is downloaded ahead of time like any other upcoming track. Repeating one track plays it again without a gap; each pass is its own entry in history, and Next and Previous still move on. Shuffle reorders the rest of the queue itself, so what the queue shows is what plays; turning it off puts the queue back in its original order, with anything added in the meantime left where it was put, and ⌘Z undoes it as one step. While shuffle is on, a new queue (an album played, a hand-off) starts with the track asked for and plays the rest shuffled. Controlling another device shows and sets that device's modes. The modes are saved with the session. MPRISLoopStatusandShuffleon Linux are not wired yet: souvlaki has no events for them. - The output is remembered across launches, amplifiers included. kōan goes back to the UPnP renderer it last played to if it turns up on the network within a few seconds of launch, carrying on with the restored session where it stood. Playing something or picking an output before then keeps the music where it is. An audio device that is absent at launch falls back to the system default, as before, and is still remembered.
- The route's preset in iOS Now Playing. Beside the AirPlay button, the preset of the route playing (AirPods, headphones, the speaker), or "Off"; tapping it picks another for that route. It follows the route as it changes, shows a UPnP renderer's preset while the phone plays to one, and is tinted while what is heard is processed.
Changed
- The preset menu says when processing is off. With DSP off everywhere, choosing a preset on the Mac or the phone did nothing audible; the menu now says processing is off and offers to turn it on.
Fixed
- The server no longer grows with use. Opening an album grid on a fresh server took it from about 170 MB to over 1 GB, which it then kept. Two things held it. Covers were also kept in memory, 512 of them, alongside the copies on disk; they are now read from disk, where the kernel caches them without counting against koan. And each cover was decoded on whichever thread served the request, so a grid of hundreds decoded in parallel, and glibc's allocator kept every thread's share. Decoding now runs on at most four threads, and koan uses mimalloc, which returns freed memory to the system.
- A cover two clients asked for at once is cached whole. Both wrote the same temporary file, so the cache could keep a truncated cover, shown as missing or broken until the file changed. Each write now has a file of its own.
0.52.0
Added
- EQ and convolution on UPnP amplifiers. An amplifier can have a profile of its own. With one, kōan decodes and processes the queue itself and sends a single FLAC stream (WAV for an amplifier without FLAC), dithered to the source's bit depth, in place of the original files; without one, it is handed the original files as before. Tracks follow one another inside the stream, so gapless does not depend on the amplifier, and with one convolution filter the stream runs unbroken across the whole queue. Where an amplifier shows ICY titles, it shows each track's. The progress bar follows the amplifier's clock through the stream.
- Presets in the Play on menu. On the Mac each output's row says which preset it plays through, and a menu beside it changes that output's preset without switching to it. While what is heard is processed, the speaker button carries a dot.
- Mixers, delays, first-order filters and graphic EQ in DSP profiles. Imports from CamillaDSP and Equalizer APO no longer stop at a
Mixerstep, APO'sCopy:, aDelayfilter orDelay:, a first-order shelf or pass (APO'sLS 6dB/HS 6dB, CamillaDSP's…FObiquads), orGraphicEQ:— AutoEQ'sGraphicEQ.txtand squig.link's "Export Graphic EQ" now import as they are. A profile's filters run in the order the configuration gives them, since a band before a mix is not the same as one after it. A graphic curve becomes a minimum-phase FIR designed at the output rate, so it neither pre-rings nor delays playback. A mixer that changes the channel count, or one placed after a convolution, is still refused by name.
0.51.0
Added
- EQ and convolution. A profile of impulse responses, EQ bands or both is chosen per output device, so headphones get their correction when they are the output. Profiles are imported from what other tools write: Roon zips and Convolver
.cfg(Acourate, Audiolense, Home Audio Fidelity), impulse WAVs from REW or rePhase, CamillaDSP configs, Equalizer APO and REW filter settings, AutoEQParametricEQ.txtand squig.link's exported filters for IEMs and DACs with no EQ of their own, and raw or text coefficients — in Settings on macOS and iOS, through the iOS share sheet and "Open in", or withkoan dsp import. Each profile's page shows what it holds: every response's rate, channels, taps and routing, any bands, and the headroom koan gives it. An impulse response is used at its own rate; a track at a rate with none is resampled to the nearest, so with one response everything plays at one rate and gapless holds across rates. Routes that mix channels (crossfeed) and per-channel delays from a.cfgare honoured. Linear-phase delay is trimmed, so the seek bar and synced lyrics stay with what is heard. The chain runs in 64-bit floating point; against a textbook convolution its output differs by −152 dB, the rounding of 32-bit output. On iOS a profile follows the route, so AirPods and wired headphones are separate outputs. On a device without a profile nothing runs, and the format badge in the apps, the TUI and GraphQL (nowPlaying.track.dsp) names the processing when something does. See Equalisation and convolution. - Play to UPnP/DLNA amplifiers and streamers. Renderers on the network are listed under Play on in the Mac app and in the TUI's output device list. Picking one makes it this device's output, as a DAC would be: the queue, transport and history stay here, and each track goes to the amplifier as the original file, so playback is bit-perfect up to its DAC. Gapless where the renderer takes the next track in advance; its own volume from the picker; formats it does not list are skipped with the reason shown in the queue. The progress bar follows the renderer's own position. Tracks are served from a port opened only while a renderer plays, each under a random URL, so nothing else is reachable through it. See Playing on another device.
- One Play on menu on the Mac. This Mac's outputs (audio devices, shown by how they are connected, and UPnP amplifiers) and other kōan devices to control are listed together, each row marked with what picking it does. The separate output menu in the transport bar is gone; the menu's button is a speaker, with the name of wherever the music is going when that is not this Mac. Beside it, the system's AirPlay button; playing to the system default, the music follows the output it picks, from where it was.
- Downloads to the cache are pinned. "Download to Cache" fetches tracks with no queue entry and marks them, so eviction takes them only once nothing fetched for playback is left to remove. Before this release it gave up after five seconds without fetching anything.
Changed
Track identity is rebuilt on source rows. Each file and each server entry now keeps its own tags in a row of its own, and a track's names, path and server id are derived from them, the file's first. One function decides which file and which server entry are the same track, and it runs whenever either's tags change. This replaces eight separate matching and repair passes, and fixes the problems they shared:
- A track held both on disk and on a server no longer changes between the file's names and the server's on every sync and rescan. A tag corrected in the file is no longer put back by the next sync.
- Correcting a file's tags pairs it with its server copy, or splits it from one it no longer matches, whatever the artist credit says.
- Names match whatever their case or Unicode form, so
SIGUR RÓSon a server isSigur Róson disk. - A file and its server copy are not paired when the server has two candidates; they used to be paired with whichever came first.
- A moved file takes over the server copy its old path held, along with its history.
- Merging two rows keeps the older one's id and history, and the koan server's uid.
- Two editions of a record with the same title are two albums when their MusicBrainz release ids differ, and a release id is no longer rewritten by whichever file was scanned last.
- A record the server names differently from the files is one album, holding the server's album id, with the tracks only the server has listed alongside the files.
- Artist names match whatever their case or Unicode form, so one act no longer appears twice.
- A server's track number fills in one the file lacks.
- A database error while matching is reported rather than adding a duplicate.
Upgrading builds the source rows from the existing library, so the first scan afterwards reads every file again and the first sync walks the whole server.
Favourites belong to the track, album or artist, not to a path or a name. They follow a track through a merge, a moved file and a file that goes while the server still streams it. A favourite of something no longer in the library is dropped on upgrade.
Downloads follow the playlist. The player owns the download queue, which fetches whatever the playlist is waiting for, from the cursor to the end and then from the top, and re-sorts when the cursor moves. Front ends add tracks and nothing else, which removes the race between adding and requesting and the five-second wait that covered it. Transfers are keyed by track, so a track queued twice is fetched once; in the app bindings,
TransferandTransferFigureare identified bytrackIdand no longer carry aqueueItemId.Playing on another device hands over in one step. The receiving device replaces its queue and opens the track at the source's position, playing or paused, as one command and one undo step. A session restored at launch opens at its position the same way, waiting for the track if it is still downloading.
Devices that cannot be reached are no longer listed under Play on. A phone that left the network, or another person's app that is not discoverable, showed as a row with only a reason.
Music moved back to a device that was controlling another takes control back. Moving music from the Mac to a phone leaves the Mac controlling the phone; moving it back now returns the Mac to its own playback, on the renderer it was playing to if there was one, instead of it going on showing the phone. Only a hand-off does this: a device told to play something by another keeps whatever it was controlling, so two devices can still control each other on purpose.
The web UI lists every album and artist on one page, as the apps do. Pages of 60 albums and 100 artists behind a Load more button made a large library tedious to scroll and broke find-in-page. Covers load lazily, so the whole listing costs markup rather than images.
The web UI's name and year filters apply as you type. A pause in typing replaces the listing under the toolbar and leaves the field focused; the URL is replaced rather than pushed, so back does not step through each keystroke. A year applies once it has four digits. On a phone the sheet's Apply still applies everything.
Fixed
- The cache limit holds with a long queue. Eviction skipped every album with a track in the queue, and the queue was downloaded in full, so a queue larger than the limit filled the cache past it and kept it there: 38 GB against a 10 GB limit. The queue is now fetched only as far ahead of the cursor as the limit allows, and eviction keeps just that window; played tracks and anything past the window are evicted file by file, least recently used first.
- Rebuilding the index keeps play history, playlists, favourites and lyrics. It now forgets only what each file and server entry said, and the next scan and sync read them all again into the rows they had.
- A track still downloading behaves like one that has arrived. Pausing it, with the button, space or the media keys, holds it paused: it used to start when the download landed, and a paused stream restarted from the beginning when its download completed. A restored session that was stopped stays stopped, and a restored position is kept through a resume. Adding tracks while one is on its way no longer starts the first of them over it. Skipping to it clears the previous track from the transport, and a seek or output change while it downloads no longer reopens the previous track. Undoing the add of a track being waited for forgets it.
- Gapless playback follows the queue as edited. The decoder queues the next track a few seconds before the current one ends, and removing, moving or inserting a track in that window had no effect: a track added with "play next" was skipped and shown as played. An edit that contradicts what was queued now restarts at the current position. A track added after the last one has finished decoding follows it without a gap. A track still downloading is no longer passed over for the next one that has arrived, which moved the cursor beyond it so it was never played; playback waits for it, leaving a gap only if it is still downloading when the track before it ends.
- Removing the paused track, or undoing past it, leaves the player paused on the track that follows instead of starting it. With nothing loaded, removing the track under the cursor moves the cursor and starts nothing.
- A skip or seek arriving as a track finishes decoding no longer jumps a track further.
- Skipping is no longer rate-limited for remote control. The player dropped a next or previous within 150 ms of the last one, which swallowed rapid skips from the apps, GraphQL, MCP and the link. The TUI keeps the limit for its own keys, against terminal key repeat.
- A track queued twice no longer plays a deleted file when its download fails. The second entry was told the track was ready, pointing at the removed
.partfile, and stayed waiting forever if the first entry had been removed. Every entry waiting on a download now gets its result, and the second entry streams and shows progress from the one transfer. - Replacing or clearing the queue stops downloads nothing wants. Entries from an old queue stayed queued, each holding a download worker for five seconds, and a transfer ran to the end once started. A transfer the playlist no longer wants now stops within a quarter of a second, and one the new queue still wants carries on.
- Playing from the middle of a long queue fetches what comes next first. The queue was fetched from the top, so playing track 105 of 192 downloaded the 104 before it first. Tracks behind the cursor no longer show a spinner unless one is actually downloading.
- The track under the cursor shows its download progress in the apps. It showed a static arrow for the whole transfer; it now shows the ring, as every other downloading row does.
- The seek bar's download mark moves smoothly. It redrew a few times a second, when the download rate was sampled; it now follows the bytes at the display's rate, like the download rings, without re-running the transport bar.
- A record with no artwork shows the ensō in the web UI, not a broken image. The cover route answered 404, and the browser drew its broken-image icon until the page's script caught the error. It now serves the placeholder the macOS and iOS apps draw: the app icon's ensō, faded. It is cached for an hour rather than for good, since art added beside the files does not change the cover's URL.
Removed
koan play --serverno longer plays audio locally. It is a remote control for the server, which plays the audio, as--jukeboxdid;--jukeboxis still accepted and changes nothing. The local mode streamed one track at a time into a cache of its own, outside the download queue, and the queue mirror it shared the TUI with overwrote what it had fetched every 100 ms, so it rarely played. To listen to a koan server's library on this machine, sign in to it as a remote library (koan remote login, or Settings in the apps): its tracks then play through the local engine and download into the cache like any other remote library's.
0.50.3
Added
- The album and artist browsers offer the same filters on every client. The macOS and iOS apps filter by favourites, lossless, codec, release years and genre, behind one control that shows how many are on; the filters persist across launches and apply to both browsers. The web UI's toolbar gains the name filter the apps had, carried in the URL with the others. Every client narrows in the same SQL query.
- Admins set passwords. The Users page and GraphQL (
setUserPassword) set a chosen password; inviting with a reset generates one. Either signs the account out everywhere. - The apps can sign in with an API key (
remote.api_keyinconfig.local.toml), which is what an invite stores.
Changed
- Invites carry a token, not the password. The link holds a JWT signed with the server's key, good for a week on any number of devices. The app trades it for an API key of its own (
/rest/koanJoin, thekoanInviteextension), so each invited device appears under API keys and can be revoked alone. Creating an account still generates a password and shows it once in the email, for the web UI and other Subsonic apps; inviting an existing account sends only the link. A password change withdraws every link sent before it, so a reset takes back a link that went to the wrong place. Opening a link again on the same device replaces its key rather than adding another (/rest/koanRevokeKey). Links made by older servers, which carried the password, are no longer read, and an app older than this cannot read the new ones. - Linked apps are scoped to the account that linked them, admins included. An admin's
clientsand…OnClientmutations used to reach every account's devices, so on a shared server a command withoutclientcould land on someone else's phone or fail on the ambiguity. Lists of devices to choose from now give each one's platform and id, since the iOS app names itself "iPhone" on every phone. - The MCP server tells assistants to choose music by style from their own knowledge. Genre tags in most libraries are sparse, so an assistant asked for a genre filtered on them, found little, and then guessed artist names a few at a time, which took minutes. It is now told to list what fits, look it all up in one aliased query, and read the library's artist names when its guesses miss.
koan authdoes not prompt without a terminal. Run from a script, CI or an agent, its prompts took their defaults:koan auth setupsaved the new account to 1Password and overwrote an existingkoan@<hostname>item. With stdin not a terminal, or with--non-interactive, credentials come only fromKOAN_USERNAMEandKOAN_PASSWORD(loginnow readsKOAN_PASSWORDtoo), and a missing one fails naming it. 1Password is written only with--save-to-1password, anddelete-user,regenerate-keysandresetneed--yes.- The web UI and share pages are styled with Tailwind utilities in their markup, as koan.rocks is, rather than by hand-written rules addressed by class name. The stylesheets keep the element defaults and the states the pages' scripts set. Pages look as they did. Stylesheet and script URLs carry a hash of their contents, so after an upgrade a browser fetches the new ones rather than pairing new markup with an hour-old cached stylesheet. Pages use the whole window: they stopped at 1200px wide before, leaving most of a large display empty.
- Download rings and bars in the macOS and iOS apps move smoothly. They were fed from the engine's transfer figures, which change a few times a second when the download rate is sampled, so they moved in visible steps, and every step reconfigured the rows of the list showing them. They now read the byte counts on each display frame, at up to 60 Hz, while a transfer is running and something on screen shows it, and draw them as layer geometry without SwiftUI or the table redrawing anything. Rings on playlist pages and in search results, which previously did not move at all until something else changed on the row, move too.
- The macOS and iOS apps tint in koan green when a record gives no colour: no artwork, a sleeve with no colour in it, or nothing playing. They tinted in grey before, which drew the playing row's title and borderless controls as if disabled. The green is the one koan.rocks and the web UI use, darker in light mode.
- The format engine comes from sift. koan's
formatmodule and sift's were the same code kept in two places; koan-core now depends on sift (sift-musicon crates.io) and re-exports its engine askoan_core::format, so templates behave exactly as before. Tagging and importing will come from sift's importer rather than a second implementation here.
Removed
- Recoverable passwords. The server no longer keeps each account's password encrypted beside its hash, which let an admin read it back through an invite. Schema version 13 drops
users.sealed_password; a database opened by this version is refused by older ones. The key they were encrypted with,subsonic.keyin the auth directory, is deleted when the server starts. - Subsonic token auth (
t/s) for accounts. It needed that readable copy. Clients get error 41 and should send the password (p=, over HTTPS) or an API key; the[subsonic]shared secret still accepts it. A koan app signed in to a koan server over plain HTTP needs signing in again, or an invite.
Fixed
- Move here resumes where the source stopped. The source read its playhead before sending and paused afterwards, so whatever played during the send and the fade was heard again on the destination; the destination then started the track from the top and seeked, letting its opening through. The source now pauses first and reports where the fade went silent, and the destination opens the track at that point. A track the destination has to download waits for the whole file rather than starting early, and a paused source arrives paused.
- ALAC tracks from a koan server no longer show as "BIN". The server had no suffix or content type for ALAC, PCM or
.aif, so it published those tracks asbin,application/octet-stream, and an app syncing from it storedbinas the codec. Every codec the indexer records now has its suffix and content type. Since a suffix cannot tell ALAC from AAC (both arem4a), a koan server also sends the stored codec in acodecattribute, which koan clients prefer over the suffix. Tracks already synced pick up the correct codec on the next full library sync. - A reinstalled iOS app keeps its device id. The id lived only in the app's container, which iOS empties when the app is deleted, so each reinstall appeared on the server as a new "iPhone" beside the old one. It is now kept in the Keychain as well, which survives a reinstall. The app also reports the phone's own name; iOS returns "iPhone" for it until the app holds Apple's user-assigned-device-name entitlement.
- A command reaches a suspended iPhone after the app has been reinstalled. A reinstall gives the app a new device id and leaves the old one's push token behind under the same name, so the server answered "several can be reached: iPhone, iPhone" and sent no push. It now wakes the device seen most recently.
- A reinstalled app's old entry no longer appears among the account's devices. The server forgets a device, with its push token, once it has been unseen for 30 days. A phone in use gives its token again each time it links, so only entries nothing answers to are dropped.
- New playlists on iOS. The Playlists page has a button to make one, and "New Playlist…" in a context menu now asks for a name. The naming dialog was hosted only by the Mac's window, so on iOS the menu item did nothing.
- The macOS app's output device menu works on macOS 27. Its button in the transport bar was not drawn in dark mode, and the menu showed no checkmark against the output in use. The button is now drawn by SwiftUI and the menu is a picker.
- An output device connected while the macOS app is running appears in the device menu. The list was read once at launch; it is now re-read whenever CoreAudio's device list changes.
- The macOS window can be tiled to half of a 2560pt display. Its minimum width was 1320pt; it is now 1260pt, with the lyrics panel opening at 280pt rather than 320pt.
- No white or black band above the sidebar in full screen. In full screen the toolbar moves into a separate window, where AppKit backs the sidebar's part of it with an opaque view; koan now hides that view so the sidebar's wash shows through.
0.50.2
Changed
- The web UI, share pages, koan.rocks and the documentation share one look. The server's pages take the site's typeface (Geist Mono) and greys, the site takes the web UI's green, and the server's pages follow the system's light or dark setting as the site already did. Both are built with Tailwind from one theme,
site/src/theme.css, so a colour or the font changes in one place.
Fixed
- The Mac no longer claims the local network is blocked by iOS. A connection to a nearby device that failed with "no route to host" was taken to mean the system had refused koan the local network, which is how iOS reports it. On macOS it means only that the address is unreachable, such as a phone asleep or a stale link-local address, and one such device kept the warning up. The Mac now trusts only the Bonjour responder's refusal, and the warning names System Settings there.
0.50.1
Fixed
- A release no longer publishes without its binaries. A push to main cancelled the previous run's builds and tests, and the publish jobs treated a cancelled dependency as a pass: 0.50.0 went to crates.io, npm and TestFlight with an empty GitHub release and no Homebrew update. Pushes to main no longer cancel each other, and publishing stops if anything it depends on was cancelled or the binaries were not built.
0.50.0
Added
- A koan server is its own MCP server and OAuth provider. Adding
https://<server>/mcpas a connector in Claude, or any MCP client that supports OAuth, opens the server's own sign-in page; approving connects that client as the signed-in account. No gateway or external identity provider is involved. It needssharing.public_url, since every address OAuth hands out is built on it. Through MCP an admin account acts asuser, because track metadata reaches the model and can carry instructions;KOAN_MCP_ADMIN=1lifts the cap. MCP never runsorganizeExecute,organizeUndoorupdateConfig, whatever the role, and a connection's tokens are good at/mcponly, so GraphQL cannot be used to get round either limit. Any client may register, and the consent page names it by the host it returns to, which it cannot fake;mcp.redirect_hostsrestricts registration to listed hosts. The web UI's Assistants page gives the address and the steps, and a browser opening/mcplands there. See MCP Integration. - Open MCP sessions end at shutdown rather than holding it up until the process is killed.
- A spent OAuth refresh token or code presented again revokes its connection, since it means a copy is in someone else's hands.
- koan's icon beside its connector. The MCP server names its icon, and
/favicon.icoand/apple-touch-icon.pngare served at the root; without them, clients showed the icon of the server's parent domain. - Playlists in the web UI. A Playlists section lists the account's own playlists and everyone's public ones; a playlist page plays, shuffles or queues it like an album. Viewing only; editing stays in the apps.
Removed
--mcp-bind(KOAN_MCP_BIND),KOAN_MCP_REQUIRE_LOGINand the gateway credential headers. MCP is served at/mcpon the main port. The Pulumi component'smcpandnetworkPolicy.mcpoptions are gone with them, and are now rejected; drop them from the stack's config.
0.49.2
Removed
- Radio. It is to be rebuilt from scratch, and until then it is gone everywhere: the toggle and settings pane in the macOS and iOS apps,
Rin the TUI, the[radio]config section,enableRadio/disableRadio/radioStatus/setClientRadioandradioonclientsin GraphQL, and the link'sradiocommand and state field. What only radio used goes with it: acoustic analysis (koan analyze,koan scan --analyze,library.analyze_on_scan, the bliss-audio dependency) and thesimilarTracksquery; the similar-artist cache fed by ListenBrainz and MusicBrainz relationships, with the Similar Artists section of the artist page, thesimilarArtistsquery and Subsonic'sgetSimilarSongs2, which now answers as unsupported. The schema moves to version 11, dropping thesimilar_artistsandtrack_vectorstables and the saved radio toggle; a database opened by this version is refused by older ones. Leftover[radio]andanalyze_on_scankeys inconfig.tomlare ignored. An older app sending the radio command to a newer one has it logged and dropped.
0.49.1
Changed
- One sync, and it runs when the server changes. "Sync" and "Full Sync" are one action, and every sync walks the whole library: the incremental kind was walking all of it anyway — every album looked changed every hour — without the part that notices a track deleted from an album. What made it cheap now comes first instead: before walking, koan asks the server when its library last changed (
getIndexes'slastModified) and walks only if that moved since the last complete walk. Favourites and playlists are reconciled every time, which is a request or two. A koan server already tells its linked apps when its library or a playlist changes, so they no longer sync on a timer; Navidrome and other Subsonic servers are checked on the timer, and synced only when something moved. A favourite made on another device costs a favourites reconcile rather than a walk of the library.koan remote sync --fullis accepted and does the same askoan remote sync. - A koan server's
getIndexeslastModifiedmoves when anything is added or removed, not only when a file changes, andifModifiedSinceis answered with the timestamp alone when nothing has.
Fixed
- A sync whose album listing came up short no longer removes or relinks tracks. An album deleted on the server mid-walk shifts the next page of the listing, and the album pushed out of view had its tracks treated as gone. The album itself was already checked before being removed; its tracks now wait for a listing that is whole.
- The start of a track at a new sample rate is no longer lost. Switching the output device's rate makes it relock its clock, and interfaces such as Focusrite's mute until it has — about a second, during which koan was already playing. A rate change is now followed by a second of silence before the track, and the playhead waits with it.
playback.rate_switch_lead_in_mssets the length for a device that needs more or less; macOS only, where koan changes the device rate.
0.49.0
Changed
In the background, the iOS app does nothing it was not asked to. Playing or paused, a backgrounded phone used to keep its link to the server open, browse and dial the network for other koan devices, sync every hour and rescan a library folder iOS does not have every fifteen minutes. All of that now waits until the app comes forward, and catches up then. A phone playing in the background still listens and advertises itself, which costs nothing until someone connects, so a Mac can find and control it; paused, it is not on the network at all. Controlling another device keeps it awake, since the Live Activity follows that device, and a push from the server holds it awake while it links and does what was asked.
The player sleeps until there is something to do. It woke every 50ms to copy the playhead into shared state, playing, paused or stopped — a hundred and sixteen wakes a second from a paused Mac with nothing on screen moving. The playhead is now read off the samples played when it is asked for, and the player wakes only for a command, for the moment the playhead reaches a queued track, or while a pause fades out. Listening time for history is counted at those moments instead of being summed tick by tick. The decoder, which looked at a full ring buffer every 10ms, now sleeps until half of it has played. Measured on a Mac: 200 context switches a second playing becomes 89, nearly all of them the audio output's own callback; 116 paused becomes none.
Removed
- "Stay reachable when paused" (non-App Store builds). It played silence to keep a paused phone running so its link to the server stayed up, which pushes now do without keeping the audio hardware awake.
Fixed
- The Play on sheet stays open on iPad. It belonged to the device button in the mini player, which iPad rebuilds while a sheet is up, and the sheet closed with it as soon as it opened. It is now held by the screen around the button.
- Opening koan with the music paused stays silent. The player had no way to load a track without starting the output, so restoring a paused session played it, seeked it and paused it, and a moment of the track got out before the pause. Seeking while paused had the same shape. A track can now be opened paused, and a restored session is cued at its position in one command, playing or not.
- A device found twice on the network is no longer dialled every two seconds. A Mac that reached a phone both by Bonjour and by a remembered address kept one connection and hung up the other, and the hang-up reset that dialer's backoff, so it connected, handshook and hung up every two seconds for as long as both were awake. Overnight that was over twelve thousand connections waking a phone playing in the background. A duplicate now backs off to once a minute, and takes over as soon as the connection it deferred to goes.
0.48.2
Fixed
- Playing a record that is not downloaded starts it downloading, every time. Queueing a track sends the player the command that adds it and starts its download together, and a download worker already running could begin before the player had the track. Until then the track read as taken out of the queue, which is what cancels a download, so it cancelled itself before a byte moved and nothing tried again; the record sat waiting until a track was tapped. It happened most around a sync or on waking, when the player is slower to take the queue. A download now waits for its track to reach the queue, woken when the queue changes. 0.48.1's fix was to the same symptom and a different cause.
0.48.1
Fixed
- The first album played after launch downloads at once. The download queue, and the watcher that sends the playing track ahead of everything else, are made by the first downloads queued. When the player moved its cursor between the queue looking at it and the watcher starting to listen, neither saw the move, and the track waited its turn behind every other download — a minute or more with one download at a time. The watcher now looks as it starts. 0.46.3 closed the other order of the same race.
0.48.0
Changed
- The Mac app's queue and playlists are AppKit tables too. They were the last lists on SwiftUI's
List, which sets up every row before drawing: a long queue or playlist stalled the page on arrival. Grouping, statuses, the playing bars, reordering by drag, drops from elsewhere, jumping to what is playing and the menus behave as before. - The Mac app's artist list, history, favourites, search and record pages open faster. SwiftUI's
Liston macOS sets up every row in a page's data before drawing it, about a millisecond a row, so these pages stalled on arrival. In a scripted run the artist list and history settled in under half the time and sixteen page switches took a third less. On the Mac these are now AppKit tables and collections whose rows are layers and labels, made only as they scroll in. Behaviour is as before: selection and its keys, the menus, dragging, hover links and hearts, search's pick. iOS keeps its lists. - The Mac app's album grid scrolls at full frame rate. SwiftUI's grid rebuilt each tile as it scrolled in and re-laid out every tile on screen on each step, about 22–27 ms a step on a 4K display, short of a 60 Hz frame. On the Mac the grid is now an AppKit collection view that reuses its tiles: 11–12 ms a step. Clicking, hover, the heart, picking several records, dragging and the context menu behave as before. The codec badge is a dark scrim rather than clear glass, since a glass view per tile cost more than the rest of the grid. iOS keeps its SwiftUI grid.
Fixed
- ⌘Z undoes edits to the playlist on screen. Removing, reordering, adding to or shuffling a playlist could not be undone; ⌘Z went to the queue whatever the page. The engine now keeps each playlist's earlier states, as it does the queue's, and puts them back exactly — entry ids included, so a queue following the playlist stays locked to it. Undo and redo take an optional playlist, and act on the queue without one.
- Play starts the queue when nothing is loaded. After a start that failed, or a session restored stopped, play and resume did nothing until a track was double-clicked: there was no playback to resume. They now start the track under the cursor.
0.47.2
Fixed
- The shuffle button only appears when albums are sorted at random. 0.47.1 showed it for every sort.
- Reshuffling keeps the album grid where it is. 0.47.1 remembered the grid's place by the album at its top, so a reshuffle followed that album to wherever it landed. The place is now a scroll distance, which a reshuffle leaves alone and a visit back to the page still restores.
- The Mac app's colour no longer flashes to the accent on the way to a record. Opening an album from the grid found its sleeve already decoded and took that to mean its colour was too, which the grid never works out; playlists were not warmed at all. The room fell back to the accent for the moment the colour was missing, then eased back over two seconds, taking every tinted control with it. Both are now warmed on their own account, and a colour still being worked out keeps the room in the one it is wearing.
0.47.1
Fixed
- Moving between pages in the Mac app no longer stalls for half a second. Most page switches added or removed toolbar items (the filter field, album sorting, selection), which makes AppKit re-tile the toolbar and lay out the whole window again, including the album grid and artist list kept mounted behind the page on screen. The toolbar now keeps the same items on every page, and the album and artist browsers are rebuilt when visited and put back where they were scrolled to instead of being kept mounted. In a scripted run over fourteen page switches the main thread stalled for 3.3 s in total, down from 5.5 s.
- A sync that meets another writer waits for it instead of losing tracks. Sync pages, scan chunks and other read-then-write work opened deferred transactions, which SQLite refuses to upgrade to a write, without waiting, once another connection has written since their first read. A full sync started while an automatic one was still reconciling favourites failed hundreds of track writes this way, and paused while other statements waited out the lock. They now take the write lock when they begin, and only one sync runs at a time.
- A sync that could not write some tracks says so and tries again. Failed track writes were logged but not counted, so the sync reported nothing failed and an incremental one moved its high-water mark past them. They now count as failures, which leaves the mark where it was.
koan.logis kept to a size. It grew without limit; a run of lock errors took it to several gigabytes. Above 16 MiB it is moved aside tokoan.log.1, replacing the one before, checked when opened and every few thousand lines.- Choosing a playlist lights its sidebar row at once. The row followed the page, so it went dark while the playlist loaded and the previous row lit up again until it arrived.
0.47.0
Changed
- Fuzzy search reads the library once per change, not once per keystroke. The command palette, the GraphQL
fuzzySearchand the TUI pickers read every track, sorted on a collation implemented in Rust, on each search; the sort was discarded by the matcher. The match text is now read unsorted and kept until the library changes. The TUI picker loads off the render thread. - Queueing tracks reads them in one query. Each track added to the queue cost three queries, and through GraphQL a configuration file read and parse as well; a batch now costs one query and one configuration read whatever its size.
- Radio tops up with a fraction of the queries. The queue's rows are read in one query, configuration is reread once a minute rather than every two seconds, and a top-up that found nothing waits for the queue to change, or a minute, before trying again.
- A server process has one connection pool. GraphQL and MCP kept their own pools beside the one Subsonic and the web UI use, each connection with its own page cache. GraphQL still holds at most one connection per core at a time.
- GraphQL
lyrics,coverArtandsimilarTrackshold no connection during network, file or ranking work, so a slow LRCLIB answer cannot keep connections from other requests.artists(ids:)andalbums(ids:)read only those rows. - Fewer queries on common Subsonic requests.
search3reads its albums in one query,getSimilarSongs2in one bounded query,getAlbumderives genres and totals from the tracks it already read,getPlaylistreads the playlist once,getScanStatuscounts only tracks,getArtistsandgetIndexesno longer count every track,getIndexesrereadslastModifiedonly when the library changes or every five minutes, and an artist's cover art reads its albums' tracks in one query.getSimilarSongs2lists a track shared by two similar artists once. - Opening the database no longer takes the write lock. Every open ran the schema DDL and a dozen repair sweeps, each an
UPDATEorDELETEthat waits for the lock whether or not it changes a row, so the folder watcher, auto-sync, cache eviction, radio and the server's post-scan work could each stall up to 30 seconds behind a scan or sync. The DDL and sweeps now run only when the schema version moves;PRAGMA optimizeon open is skipped while another connection is writing. The schema version is now 9: existing databases run the sweeps once more on upgrade, and builds before this one refuse the upgraded database. - A resync of an unchanged library writes nothing. Every synced track rewrote its row, its ten index entries, its search-index entry and its album, about 220 MB of WAL for a 51,000-track library; an unchanged track is now compared and left alone, which also makes the resync about seven times faster. A track new from a koan server is inserted with the server's uid instead of being given one and then having it replaced.
- The playing position is saved without rewriting the queue. It shared a row with the saved queue, which SQLite rewrites whenever the row changes size, as it does on every track change and when the position passes 32.8 seconds. It now has a table of its own. The queue itself is rewritten only when its contents change, not on every track change or finished download.
- Subsonic API-key requests no longer wait for the write lock. Each one recorded the key's last use with an
UPDATE, which waited behind any scan or sync; the stamp is now written only when it is stale, and skipped when the lock is held. Share pages count visits the same way. - Multi-row edits are single transactions: playlist edits (including Subsonic
createPlaylistandupdatePlaylist), favourite imports, the offline queue for linked devices, andscrobblebatches. Readers no longer see a half-applied edit, and a scrobble batch naming a track that does not exist records none of its plays, so a retry does not duplicate them. - Clearing all downloads rewrites only the tracks that had one, rather than every row in the library.
- Indexes for the genre list and filter, and for deleting or merging artists and tracks (similar artists, organize history, shares, favourites by path, a track's last play).
Fixed
- Favourites streamed and never downloaded count in every listing. A track that has never been downloaded is favourited by its stream URL, and the favourite album and artist filters, and the GraphQL
favouritesandtracks(favouritesOnly)listings, compared only file and download paths. On a library synced from a server most favourites were missing from them. - Radio's same-artist and genre picks are by that artist and in that genre. Both were drawn from a random sample of the whole library and only ranked by the preference, so on a large library they were almost always neither. They are now drawn from the artist's or the genre's tracks, and with no play history the seed's genres are those of the artists in the queue rather than of random tracks.
- Radio no longer queues a track already in the queue that has not been downloaded. Queued tracks were excluded by file path, which a streamed track does not have; they are now excluded by id.
- Subsonic's
playeddates are the caller's own. Songs and albums reported the last play by any account, so one account could see when another last listened to something. - Recently played tracks are ordered by their latest play. Radio's seed took a track's position from an arbitrary one of its plays.
- Lists longer than 32,766 ids work. A queue, playlist or selection past SQLite's parameter limit came back empty, published without album ids, or gave radio nothing to pick from. Id lists are now bound as a single JSON array.
0.46.3
Fixed
- The first album played after launch downloads and plays. The download queue is created by the first download, and its watcher, which sends the track under the cursor to the priority lane, started listening after the cursor had already moved: the first play's track never got there. Queuing downloads now promotes the cursor's track as well as moving the cursor does.
- Downloads no longer wait on a track nobody is playing. Since 0.46.2 workers hold back while the cursor's track downloads, but one that looked before a new queue reached the player waited on the old cursor's download. A cursor move now wakes them.
- Pressing play tries the server at once. After a failed request every download waited out a backoff of up to a minute, which a flaky connection or a phone in a pocket keeps extending. Queuing music, and the app's link to the server reconnecting, now makes the next try due immediately; a further failure carries the backoff on.
- Only tracks being fetched show a download spinner. Every track waiting its turn showed one, which read as the whole album downloading at once.
0.46.2
Fixed
- The queue plays after the iOS app is updated. iOS moves an app's data to a new path on every update, and the saved queue named tracks by their old file paths: items it could not match came back waiting for a download that was never started, and the playing position was lost, so nothing played until the queue was cleared. A restore now finds each track by its library id, and keeps its place in the queue.
- Downloads survive an iOS update. The paths stored for downloaded tracks named the old location, so every download looked missing: tracks were fetched again beside the copies already on the phone, and the old copies could no longer be evicted. On launch, paths under a moved cache are pointed at where the files now are.
- The track you play downloads first, on its own. Playing an album that was not downloaded started every track at once, each taking a share of the connection, so on a slow link the first track arrived no sooner than the rest. Other downloads now wait until the track under the cursor has arrived.
- The parallel-downloads setting takes effect when changed. It was read once at launch.
0.46.1
Changed
- Unused code is removed, including twelve koan-ffi exports the apps no longer call. No behaviour changes.
Fixed
- The empty library points somewhere useful. On iPhone and iPad it said to run a scan, which the app cannot do, and on the Mac it named a terminal command. It now points to Settings → Server on iOS, and to adding a folder or signing in on the Mac.
- Settings and CLI help describe what koan does. The sample-rate note says the device is asked to match the source and that nothing is resampled unless it refuses; sync, devices and invite descriptions match their behaviour;
--headlessand--subsonichelp match how the server mounts its APIs. - The documentation and site match the code: five crates,
Config::persistfor config writes, current GraphQL operation names and configuration keys, radio's use of ListenBrainz and MusicBrainz, and where the Mac app keeps its data.
0.46.0
Changed
- Subsonic password checks are bounded. argon2 costs about 19 MiB and a core per check, and any client could ask for one, known username or not; a few hundred concurrent requests with made-up usernames exhausted memory and stalled every other route. At most one check per core (2 to 8) now runs at once, and a request that finds them all busy is answered "server busy" instead of queued. Requests carrying the same credentials share one check, so a client's burst of requests on first contact still signs in.
- Failed sign-ins on
/restare also counted per address, 30 a minute whatever the username, alongside the 10 a minute per address and account. Changing the username on each guess no longer resets the allowance. The shared username's tokens are exempt only when a shared secret is configured; without one the name is an ordinary account's. - A password reset signs the account out everywhere, as the Users page says it does: its API keys are deleted and its open links to the server are closed, as well as its refresh tokens. A key made by whoever else had the password would otherwise have outlived the reset. Deleting an account closes its open links too.
- Roles and accounts are read from the database on each GraphQL request and web UI page, not taken from the access token. A demoted or deleted admin kept admin until the token expired, long enough to restore it. Account ids are no longer reused after a deletion (
users.idisAUTOINCREMENT; existing databases are rebuilt once, keeping every id). /auth/login,/auth/refreshand/auth/logoutshed load and time out after 10 seconds. Each allowed two requests at a time and queued the rest with no deadline, so two connections that never finished sending a body blocked every sign-in or refresh from the CLI and TUI.- GraphQL request bodies are limited to 2 MiB. async-graphql reads the whole body before parsing it, with no limit of its own.
- Subsonic
getCoverArtserves from the same cover cache as the web UI. Covers are kept on disk at a few fixed sizes, keyed by the source file so a re-tag is picked up, and an album with no art is remembered rather than reopened on every request. An album whose first track has no art now shows the art of the next. Responses are always JPEG; a request withoutsizegets the largest kept size (1200 px) rather than the original. - Server shares are always made on the server. The web UI and GraphQL
createSharemade the link on an upstream Navidrome when[remote]was configured, where it belonged to the upstream account and could be neither listed nor revoked here, and failed outright for local-only tracks. They now make the same native link SubsoniccreateSharedoes. - Syncs no longer re-star every favourite. Each sync sent one request per local favourite; it now reads the server's stars first and sends only those the server lacks.
- Rescanning from the app walks each folder once. The file count for the progress bar came from a separate walk of every folder, and files were checked against the scan cache one at a time; the count now comes from the scan's own walk and the checks run in parallel.
Fixed
- The upstream server's password no longer appears in error messages. A failed stream proxy or share returned reqwest's error, which names the request URL and with it the upstream account's credentials, to any signed-in caller, readonly included. Errors from the Subsonic client and downloads drop the URL, so logs are clean too.
- The dedicated Subsonic port (
[subsonic] port) knows its clients' addresses. It was served without connection info, so the sign-in throttle believed anyX-Forwarded-Fora client sent and a new one per request bypassed it. A request whose peer is unknown is no longer taken as coming from a trusted proxy. - MCP requests act under the signed-in account's name. Every request ran as "anonymous", so a non-admin account saw none of its own devices, and an account named "anonymous" would have been visible to all of them. The name is now reserved.
- Linked devices no longer stall the server. Every state report from a linked app opened the database afresh, running the schema migrations and a checkpoint on an async worker, and could wait up to 30 seconds behind a scan's write lock; a few devices could stall every request. The link's bookkeeping now uses the shared connection pool and runs off the async workers, and the device list is only read when a linked app has asked for it.
getAlbumListandgetAlbumList2honour every list type.starred,byGenre,byYear,recentandfrequentreturned the whole library in storage order; they now return the starred albums, the genre or years asked for, and albums by play history.newestmeans recently added, as clients expect, rather than latest release date.highestis empty, since koan keeps no ratings, and an unknown type is an error. Each page is ordered and cut in SQL instead of loading and sorting every album.getRandomSongsfilters by genre and year before drawing. A genre that is a small share of the library came back almost empty, because the filter ran after a draw from the whole library.fromYearandtoYearare now honoured,sizeis capped at 500 like the other list endpoints, and the draw no longer joins every track to pick a few.scrobbleaccepts several plays at once. A repeatedid(with itstime) was rejected with a bare HTTP 400, so a client flushing an offline session lost every play.- Playlist edits made through Subsonic reach the account's other devices and the upstream server, as GraphQL edits already did. The koan apps edit playlists on a koan server through these endpoints, so a playlist changed on the phone did not appear on the Mac until it next synced on its own, and one deleted there came back with the next upstream sync.
- "Play on" notifications show the album cover. The command's track uid was parsed as a row id, which never matched.
- Server reads that scaled with the library now scale with the answer:
getArtistandgetMusicDirectorylook up one artist rather than aggregating all of them,getStarred2reads each kind of favourite in one query rather than one per item, GraphQLfuzzySearchmatches on the request's thread after returning its connection instead of building a thread pool per call, and local files stream in 256 KiB reads rather than 4 KiB ones. - A server can no longer make koan write outside its cache. A remote track's file extension came straight from the server's
suffix, so a value containing/and..placed the download anywhere the user could write. Extensions are now ASCII letters and digits only, an artist, album or title of.or..becomes_, and a download whose path would leave the cache directory is refused. - Cancelling a large library scan no longer hangs. The tag readers blocked on a full channel that nothing was reading any more, which left the scan unfinished and every rayon worker parked for the rest of the process. The readers now stop on cancel and the channel is closed before the scan waits for them.
- Signing in to a different server or account keeps your playlists. Each playlist's server id is now recorded against the account it came from. Playlists from another account become local ones and are pushed to the new server as new, where before the first sync read every one of them as deleted and removed it.
- Playlist sync keeps local files and stops rewriting every playlist. A sync compared the server's timestamp with a copy of itself, so every sync fetched every playlist and replaced its contents with only the tracks the server knows, dropping local files and renumbering every entry (which also ended a queue's lock to its playlist). Each side is now judged against its own record of the last sync: an unchanged playlist is not fetched, a pull keeps local-only entries and the ids of entries that did not change, and conflicting edits still go to the later writer.
- Quick successive playlist edits reach the server in order. Each edit pushed on its own thread, so two in flight could create the playlist on the server twice or land out of order. Pushes of one playlist now run one at a time, each reading the playlist when its turn comes.
- Merging duplicate tracks keeps them in playlists and shares. Entries for the row being merged away were deleted with it; they now move to the surviving row.
- Downloads follow sign-in changes. The download queue built its server client once per process, so after signing out, changing password or signing in elsewhere it kept using the old credentials until relaunch. The client is now looked up per download.
- Downloading albums for offline listening no longer evicts them first. Cache eviction ranked albums by last play, so ones fetched but not yet played were the first to go. A download now counts as a use.
- A track id koan cannot find no longer stalls playback controls. A pushed command naming a track the library lacked ran a sync on the same lane as pause, skip and seek, and repeated it for every command naming a track the server had deleted. The sync now runs off that lane, an id a sync failed to find does not start another for five minutes, and commands from devices on the local network, which need no account, never start a sync.
- An album is removed only when the server says it is gone. The album list is walked by offset, so a deletion during the walk could push a different album off a page boundary and have its tracks and play history deleted. An album missing from the list is now checked with
getAlbumfirst.
0.45.1
Fixed
- The apps open again. 0.45.0 crashed on launch on macOS and iOS: the invite confirmation added to the scene root read the app's state from an environment it sits outside of.
0.45.0
Added
- The apps open invites (#572). 0.44.0 made the links but no app claimed them: the join page's button failed with "address is invalid" and an invite pasted into Settings did nothing. The iOS app now claims
koan.rocks/join/as a universal link, and both apps registerkoan://join. Opening an invite signs in, runs a full sync and shows the albums. If a different account is already signed in, the app asks before switching. An invite pasted into Server URL, or through the Paste button beside Sign In, fills in the account; so does a server address carryinguser:password@. - People in Settings, for an admin signed in to a koan server: the server's accounts, each one's access level, and Add, Invite and Delete, over the same Subsonic endpoints the web UI's Users page uses. An invite opens as a sheet to share, mail or copy as rich text, with the plain details for other Subsonic apps. On any other server, or for an account that is not an admin, the section does not appear.
- The lock-screen remote shows the record's sleeve. The server puts a small cover in each Live Activity push, so it is there with the app suspended.
Changed
- The DMG opens to an install window: the app beside an Applications link to drag it onto, over a background in koan.rocks' colours. Finder draws icon labels in black whenever a window has a background image, so each label sits on a light plate. The layout is written by dmgbuild rather than by scripting Finder, so it builds on CI runners with no logged-in session.
- koan.rocks links the DMG directly. "Download for Mac" points at the latest release's
Koan.dmg, which GitHub redirects to whichever release is newest, so the site never needs updating for a release.
Fixed
- "What the server offers" fills in as soon as you sign in. Signed out, the link thread rests for a minute between checks, and signing in did not wake it, so Settings said "Not reached yet" and the link stayed down for up to a minute while the library synced.
- A phone stays controlling the Mac across backgrounding and relaunches, and the Live Activity stays with it. The device being controlled is kept on disk and is never let go of because it dropped out of a list, which happened whenever the link reconnected before the Mac's did (a server restart, the Mac asleep); it shows as out of reach until it is back.
- Other devices appear the moment the app opens. The last device list is kept on disk and drawn at once. Coming to the front, every connection is pinged and one that does not answer within two seconds is replaced, rather than waiting up to 45 seconds on a socket iOS closed while the app was suspended; the server's profile is no longer asked again before each reconnect.
- Devices on the same network are found reliably. Each device's last address is dialled at launch before Bonjour answers, and Bonjour browsing, the listener and the announcement are restarted when iOS has closed them. A device that is announced but cannot be reached is listed with the reason, and the picker says when iOS is keeping kōan off the local network, with a button to Settings, instead of showing nothing.
0.44.1
Added
- Search results can be selected like the album grid: artists, albums and tracks, with Select in the toolbar, ⌘-click, ⇧-click for a range and ⌘A, then Play or Add to Queue. A pick survives a new query, so it can gather from several searches, and dragging a ticked result drags the whole pick.
Changed
- Releases build each thing once. The binaries CI already builds for every commit on main (the CLI for macOS arm64 and Linux x86_64, and the macOS app) are passed to the release jobs as artifacts, which sign, notarise and package them rather than compiling the same commit again; the crates publish no longer waits behind notarisation. The TestFlight job no longer builds the engine a second time for the Mac to generate the Swift bindings: they are read from the iOS build, by a bindings generator that is a crate of its own (
tools/uniffi-bindgen) and builds nothing else. - CI caches what it builds. The cache was over GitHub's 10 GB limit, so entries were evicted before they were reused and the TestFlight job compiled everything each time. Pull requests now read the cache without writing to it. The iOS job's cache covers its own target directory and is kept when the archive fails. The container image caches its dependencies in a layer of their own (cargo-chef), which survives source changes.
Fixed
- The iOS app builds for release again. The Live Activity code handed an
Activityacross actors, which Swift 6 rejects, and 0.44.0's TestFlight archive failed on it.just ios-typecheckchecked types only, and a data race is found after that, so it had passed; it now runs the same checks the archive does.
0.44.0
Added
- Invite links and account management (#572). Admins create accounts, pick their access level, change it and delete accounts from the web UI's Users page, over GraphQL (so from MCP too), with
koan auth invite, and through koan-specific Subsonic endpoints (koanUsers,koanCreateUser,koanInvite,koanSetUserRole,koanDeleteUser). Creating or inviting an account produces an invite: a koan.rocks link carrying the server, username and password in its fragment, and an email to send it in (copy as rich text,mailto:, or the share sheet; the server sends no mail). The details are shown in plain text for other Subsonic apps. An invite reuses the account's password, recovered from its sealed copy, so its other devices keep working. - koan.rocks/join is the page an invite opens where the app is not installed, and koan.rocks serves the app-site association that makes
/join/a universal link into the iOS app. - Play on another device (#574). The Play on button lists the other kōan apps this one can reach: the account's devices on any network, through a kōan server, and anyone's on the local network, found over Bonjour. Picking one makes it the device the app controls: this one pauses, and the transport, queue, heart and Now Playing (Control Center and the media keys included) act on that device until another is picked. Move here sends the controlled device's queue and playhead to another and controls it there, so a Mac's music can be taken out on the phone or sent back. Tracks the server does not have stay behind, and the app says how many. See Playing on another device.
- A lock-screen remote on iOS. While the phone controls another device, a Live Activity shows what is playing there with previous, play-pause and next. The server pushes it each change once iOS has suspended the app (with the
[push]key), and its buttons reach the server in one request when the app's link is down. - Devices on the same network, and by address. Each app listens on port 5626 and announces itself as
_koan._tcp;[devices]turns that off, or lists addresses to dial where Bonjour does not reach, such as a tailnet. A device on the network may control playback and the queue, never the library or the files on disk. - The client knows what it signed in to. koan's extensions are listed in
getOpenSubsonicExtensions(koanLink,koanDevices), and the app probespingand that list once per sign-in rather than checking whether the server calls itself koan, so a feature is offered only where the server has it. Settings → Server shows the server, its version and the extensions it listed.
Changed
- Every artist, album, track and playlist has one id on every device (#501): a UUIDv7, published as its id over Subsonic, GraphQL and the link. Row ids are numbered per table, so an endpoint that takes any kind (
createShare,star,getCoverArt) read album 5 as song 5; they are also numbered per database, so an id meant nothing on another device. A client syncing from a koan server takes the server's uids for its rows, including rows it merged with local files, so the server and every device name a track the same way. Bare and prefixed row ids (5,al-5) are still accepted everywhere. GraphQL id fields are nowIDstrings rather thanInt. The library upgrades itself, and a build older than this one then refuses it. Each client's first sync after the server is upgraded re-reads the whole library, since every id changed; rows, history and favourites are kept. A device still on an older build lists each remote track twice after its next sync, because older builds keep two remote rows with different ids apart; updating it, or running a full sync, folds them back into one. - The link to the server reports on change rather than every few seconds. It waits on its socket and on the engine's change signal, so a pause on one device shows on the other at once and a quiet link wakes only to ping.
- Favouriting on one device has the account's other linked devices sync, so the heart lights on the Mac for a track favourited on the phone.
- TestFlight builds say what changed. Each upload's "What to Test" is that version's changelog section (#581).
- GraphQL:
handOffClient(to, from)moves one linked app's music to another, andClient.deviceis each app's stable id.
Fixed
- iOS builds reach TestFlight again (#580). CI signed each archive with a fresh Apple Development certificate until the account ran out, and 0.43.0 never uploaded; it now reuses one stored certificate.
0.43.0
Added
The "Play on …" notification shows the album's cover. The server puts a link to the cover in the notification, and a notification service extension in the iOS app fetches and attaches it before iOS shows it. The extension holds no sign-in, so the link authorises itself: an HMAC over one track and an expiry ten minutes out, keyed by a secret that lives only in the server's process, opening that one cover and nothing else. Needs
sharing.public_url; without it the notification shows as before.Favourites, playlists, play history and shares belong to a user (#576). On a server with several accounts, one account no longer sees or edits another's favourites, playlists, plays or share links, through koan's own clients or Subsonic ones.
Select mode on an artist page's albums (#569), as the library grid already had. A click on a record there played it and replaced the queue, which was easy to do by accident when picking a few to add.
Changed
- The library watcher scans only the directories a change touches (#568), ignores events that cannot change the index, and keeps its watches in step with the folder list and mounts. It ran a whole-library scan for any event, which on a large library on a spinning disk was a steady stream of walks that found nothing.
- A burst of library changes wakes a suspended phone once (#565). Each change sent every absent device its own background push, so downloading several albums sent a phone a burst of them; wakes now wait for the library to go quiet and collapse per device.
Fixed
- Pause, seek and stop reach the server's Now Playing (#570). Only starts and scrobbles were reported, so Navidrome's Now Playing ran on through pauses, ignored seeks and stayed up after a stop.
- An unreachable server is waited out (#421). Every download spent its retries and failed, and the player skipped through the queue; downloads now wait for the server to answer again.
koan play --serversigns in with the stored refresh token (#173). It sent no credentials, so a server withauth_enabledrefused every request, reported at startup as "error decoding response body".- The server sign-in fields say what they want on iOS (#571). An iOS form shows a field's prompt and not its label, so the fields were labelled only by examples.
- koan.rocks no longer renders new pages against an old stylesheet. The server caches every file for a year as immutable, and the stylesheet lived at a fixed URL, so a browser that had visited before kept the old rules under new markup (the header nav lost its spacing). The stylesheet's URL now carries a hash of its content.
- Lyrics cached before a synced copy existed upstream now upgrade to it (#215). Any cached copy used to be final, so a track first fetched as plain text never highlighted. A plain copy older than 30 days is checked against LRCLIB again when it is next shown, and kept (with its clock reset) if there is still no synced one. Synced copies are never re-fetched.
0.42.1
Changed
- Music for a sleeping phone is a notification at once. iOS does not let an app it woke start audio, which the phone's log showed plainly: the woken app took the command and the output unit refused to start. So a request to play on a phone iOS has suspended is sent straight away as the "Play on …" notification, time-sensitive so it reaches through Focus, rather than after a wake and a wait that could not succeed. Every other command still goes to the outbox and wakes the phone to take it. The app no longer switches to a mixable audio session when woken.
- Release notes no longer carry the quarantine workaround. Every release since 0.40.0 is notarised, so the
xattrinstructions only applied to builds nobody downloads.
Fixed
- A remote server is sent a scrobble only once a track has been heard (#546): half the track or four minutes, and never a track under thirty seconds, as Last.fm counts a play. Scrobbling at the start sent skipped and failed tracks to Last.fm. When a track starts the server is told it is now playing, so koan shows in Navidrome's Now Playing, and each scrobble is dated to when the listen began. Local play history is unchanged and still records every start.
- koan sends a User-Agent to the server (
koan/<version> (Macintosh),(iOS)or(Linux)), so Navidrome lists a Mac and a phone as two players rather than onekoan [].
0.42.0
Added
- Music starts on a sleeping phone without a tap. Any command to an iOS device that is not linked (play, queue, skip, radio) goes into its outbox and the server wakes it with a background push; koan links and runs it as if it had been open. Woken, the app takes a mixable audio session, which iOS lets a background app start, and returns to the ordinary one once playing. For music, the server checks the device is playing within 25 seconds and otherwise sends the "Play on …" notification instead, taking the command back out of the outbox so the tap does not play it twice. That covers the one case iOS will not wake: an app the user force-quit.
Changed
- macOS release binaries are signed with a Developer ID and notarised. Downloaded through a browser, the ad-hoc signed binaries were quarantined and Gatekeeper refused to run them until the quarantine attribute was cleared.
Fixed
- koan.rocks no longer scrolls sideways on narrow phones: the header nav wraps under the logo instead of pushing the page wider than the screen.
0.41.0
Added
- A koan server reaches a phone iOS has suspended (#520). The iOS app registers for push and sends its token up the link; the server keeps it per device. When something waits for a device that is away (a sync, an eviction), the server sends a background push that wakes the app to link and take it. A request to play on a device that is not linked becomes a notification, "Play on …", that plays when tapped: iOS does not let a suspended app start audio itself.
playOnClientand the MCP say when a notification was sent rather than music started. Needs the team's APNs key in[push], which the Pulumi package takes as a Secret (push.existingSecret). - Interruptions are logged. Each audio interruption on iOS, and each move between foreground and background, goes to koan's log, to find why playback sometimes does not resume after one.
- The iOS app shows its version, at the foot of Settings and under the ensō while it starts: which build is running, for a bug report or to see a TestFlight update arrived.
Changed
- The macOS app is notarised. From 0.40.0 releases are signed with a Developer ID and notarised, so
Koan.dmgopens like any other download; the README, the site and the Homebrew cask no longer carry the quarantine workaround.
Fixed
- Play works after an audio route drops mid-interruption. A Bluetooth speaker losing power, or a voice assistant handing the speaker back, interrupts with a route disconnection that iOS never ends; the session stayed inactive and every play afterwards was silent. koan now takes the session back, and again whenever it returns to the front with an interruption still open. It stays paused when the route that went was the one it was playing through. Route changes are logged beside interruptions.
- Playback resumes after an interruption that iOS announces more than once. A voice assistant taking the audio sends several "interruption began" in a row; the later ones found playback already paused by the first and recorded that nothing had been playing, so when the interruption ended with iOS asking koan to resume, it did not. What the first one saw now holds until the interruption ends.
- A failed release can be re-run. The release job created the tag first, so re-running it after a failed upload failed on the tag it had already made. It now skips a tag that exists and goes on to the uploads.
0.40.0
Added
- iOS releases go to TestFlight (#540). Each release archives the iOS app, signs it and uploads it to App Store Connect, so a build reaches the phone over the air with no cable and no seven-day expiry. Signing is cloud-managed through the App Store Connect API key the macOS release notarises with, so no certificate or profile is kept in a secret. Without the key or the
APPLE_TEAM_IDvariable (a fork) the upload is skipped rather than failing the release.just ios-testflight BUILDdoes the same from a Mac. - Privacy manifest and policy for the App Store (#541). The iOS app ships a
PrivacyInfo.xcprivacydeclaring no tracking, no data collected, and the reasons for the file-timestamp, disk-space andUserDefaultsAPIs it calls; App Review rejects an app without one. koan.rocks has a privacy page, which the App Store listing links to. - The App Store listing is kept in the repository (#544).
apps/ios/store/listing.tomlholds the listing text and App Review notes;just ios-storepushes it, screenshots and the newest processed build through the App Store Connect API, and never submits.just ios-signinsigns a simulator in through Settings as App Review would, which is how the store screenshots get a library of Creative Commons music rather than anyone's own.ios-walkandios-signinshut their simulator down when they finish; a booted simulator left behind is a running copy of iOS. - A spinner while a track arrives. Playing a track that is not on the phone yet parks the engine until the first of it has downloaded; the play button in the mini player and Now Playing now shows that wait instead of a play button that looks as if the tap did nothing.
- Framed App Store screenshots.
just ios-store-shotsputs each screen of a walk on a blur of its own colours with a caption fromapps/ios/store/captions.toml(orcaptions-ipad.toml), at the size App Store Connect asks for.just ios-storeretries App Store Connect's occasional server errors. just ios-useuses the app on a simulator as a listener does and checks each step: browse, play, pause, skip, favourite, queue, Now Playing, lyrics, playlists, search, playing on in the background, and seeking far into a track still downloading. What to run before an App Store submission, on an iPhone and an iPad.
Changed
- App Store builds cannot stay reachable by playing silence (#542). The iOS keepalive plays silent audio so a paused, backgrounded phone keeps its link to the server; App Review rejects background audio that plays nothing (guideline 2.5.4). Builds archived for TestFlight and the App Store are compiled with
KOAN_STORE, which turns it off and hides its setting. Development builds keep it; push notifications (#520) are what replaces it. - iPad uses the tab layout. The iPad took the Mac's split view, built for a pointer: its lyrics inspector could not be closed by touch and choosing a page in its sidebar did not navigate. It now uses the same shell as the iPhone, whose sidebar-adaptable tab bar is iPadOS's own layout, a bar across the top that opens into a sidebar.
- An empty library on iOS says how to fill it. The queue's empty state points to Settings → Server when there is no library yet, which is what anyone opening the app for the first time sees.
Fixed
- iOS builds carry koan's version (#543). The generated
Info.plisthad XcodeGen's defaults, 1.0 (1), whatever the build settings said, so every TestFlight upload claimed version 1.0 and could not be attached to the App Store version it was built for. It now readsMARKETING_VERSION(the workspace version) andCURRENT_PROJECT_VERSION(the build number). - Organize Files is not offered on iOS. The long-press menus offered it on a phone, where it opened nothing.
0.39.4
Fixed
- The cache limit is enforced. Settings' cache limit was read only by
koan cache evict, run by hand, so the apps' caches grew without bound: an iPhone reached 29 GiB and ran out of space. Once a limit is set, the download queue trims the cache after downloads (at most once a minute) and at launch, least recently played albums first, never an album with a favourite or a track in the queue. The limit is read afresh each time, so a change in Settings applies at once. - Playing a playlist from a row plays that row (#417). The page sent the row's position, and the engine applied it to the playlist as it re-read it, keeping only entries whose track the library still has. After a sync changed the playlist, or with a track the server no longer has earlier in it, the two disagreed and a different track played.
playPlaylistnow takes the entry id.
0.39.3
Fixed
- A playlist's page fits a phone. Its header was the Mac's, side by side: wider than the screen, so the title and Shuffle wrapped a letter at a time, the artwork was clipped, and every row below was laid out at the header's width and cut off on the right. On a narrow screen the artwork, title and controls now stack, as a record's page does, with Shuffle as an icon beside the queue buttons.
0.39.2
Added
- A release that cannot open the library is never rolled out. The Pulumi package runs a Job with the new image before touching the Deployment:
koan check-dbsnapshots the live database withVACUUM INTOand applies the new build's schema and migrations to the snapshot, leaving the original untouched. The Deployment is Recreate, so a migration failing on the real library (as 0.38.5's did) used to stop the old server with nothing to replace it; now the Job fails, the deploy stops, and the running version keeps serving. A fresh install with no database passes.
0.39.1
Fixed
- Playback on iOS recovers from an interruption. After a phone call, Siri or another app taking the audio, the output unit was left stopped and nothing played until the app was killed. When an interruption ends, and when iOS resets its media services, the audio session is reconfigured and the output rebuilt on the current track. Playback resumes when it was playing before and iOS marks the interruption as one to resume from (a call or Siri ending); otherwise it waits, paused, for play.
- Covers no longer show for the wrong album (#526). The cover cache is keyed by album, artist and track id, and SQLite hands a deleted row's id to the next one inserted, so a removed album's cover could appear on whatever took its id. The database now logs deleted ids, and the apps evict exactly those entries whenever the library changes and at launch.
0.39.0
Added
- What the server changes reaches every device by itself. The server now remembers each app that has linked to it, per account, and keeps an outbox for each: a command for a device that is away waits and is delivered the moment it links again (an iPhone brought to the foreground, a Mac app opened). Creating or editing a playlist, and a library scan that adds or removes albums, queue a sync for every device; syncs waiting for one device collapse into one.
syncClients(full)does the same on request, andevictOnClientsnow reaches devices that are away. Playback commands never wait: "play this" delivered tomorrow would be wrong. - A link sync is a whole sync. It pulled the library only; it now also reconciles favourites and playlists, as the app's own sync does, so a playlist made on the server appears.
addToPlaylistWhenAdded(playlistId, artist, album, titles). Adds an album, or the named tracks from it, to a playlist once it is in the library, for music being fetched with slsk. With the above, "make me a cyberpunk playlist" can start with what is in the library and grow as the rest downloads, on every device, without anyone asking again.
Changed
- Standing orders survive restarts.
queueOnClientWhenAddedand the new playlist orders were held in memory, and every deploy dropped them; they are kept in the database now.
0.38.6
Fixed
- kōan starts on a library where two spellings of an artist share an album title. 0.38.5's merge of case-duplicate artists moved every album onto the kept spelling, and an album both spellings held under the same title broke the one-album-per-title rule, so the database refused to open and the app would not start. The second copy's tracks now join the kept album instead.
0.38.5
Fixed
- Artist names that differ only in case are one artist. Tags spell an act "The Squire Of Gothos" on one record and "of" on the next, and each spelling was its own artist, so a track's artist link could open a page owning none of the albums. New spellings now join the existing artist, and duplicates already in the library are merged when it opens, onto the spelling that owns the most albums.
- An artist with tracks but no albums has a page. A guest or compilation credit opened a blank "Artist · 0 albums"; it now lists the tracks they appear on, each with its album.
- The library catches up with moves the file watcher misses. A scan that runs while a folder is half moved sees both the new files and the old, and with no later event the old paths stayed in the library, unplayable, until a restart. The watcher now also rescans every 15 minutes; unchanged files are skipped on mtime and size, so an idle rescan costs about a second.
0.38.4
Added
evictOnClients(trackIds): have every linked app drop its downloaded copies of some tracks. A device keeps the copy it downloaded, so a track cached while the server's file was damaged kept playing as noise after the file was replaced. This sends the linked apps a newEvictlink command; each deletes its cached files for those tracks and fetches them again on the next play.
Fixed
- A track removed because the server deleted it takes its downloaded file with it. The row went and the file stayed in the cache, where nothing would play or clean it up.
0.38.3
Fixed
- What the server deletes, clients delete. A sync only ever unlinked tracks that had a local file, so a remote-only track deleted on the server stayed on every client, unplayable, until its database was wiped. An album gone from the server's listing now goes on any sync (every sync lists every album), and a single track gone from an album goes on a full sync, which lists every track; the albums and artists that leaves empty go with them. An empty or short listing is still treated as a fault, not a deletion.
0.38.2
Fixed
- An assistant pauses when asked, whatever the device last reported. An app older than 0.38.0 reports nothing, so
clientsshowed it idle and an assistant told to pause it answered that nothing was playing.clients.playingis null for an app that has not reported, and the MCP instructions say to send pause, skip and resume as asked rather than judge them from reported state.
0.38.1
Fixed
- An album moved or deleted on disk leaves the library. Removing its missing tracks left the album row, empty, and a server kept listing it, so every client's full sync brought it back (a duplicate Consume The Power, one copy of which had been moved away). Stale-track removal now drops an album and artist it empties, and empty albums already there are cleared when the database opens.
0.38.0
Added
- A linked app is a full remote. Each app now reports what it is playing, where in the track, whether radio is on, and its queue;
clientsshows all of it, so "what's playing on my phone" has an answer. New mutations skip to a track (jumpOnClient, from the queue or slotted in), seek, play next, remove, clear, toggle radio and sync the app's library. - Queue an album once it has downloaded.
queueOnClientWhenAdded(artist, album)waits for an album to reach the library (after slsk'sgrab, say) and then queues it on the device, so "play them, and add their latest album when it lands" needs no one to come back and check. - The server works out which device is meant. Without a
client, a command goes to the app that is playing, else the one that played in the last six hours; with several linked and none of them recent, it answers with the choices so an assistant asks. - iOS: stay reachable when paused. A backgrounded app that is not playing is suspended by iOS, which cuts its link. With this on (the default), it keeps running after a pause by playing silence: indefinitely on the charger, and for a chosen time on battery. Opening the app relinks at once rather than at the next retry.
Changed
- The MCP says what it is for. Its tools and instructions described a music player and led with
pauseandnowPlaying, which on a server drive a headless player nobody hears, so an assistant asked to pause the music paused that, found nothing playing and blamed the browser. Served over HTTP, the instructions now lead with the linked devices and say outright that the server's own player is never the user's music; on stdio, where it is, they still lead with it. The tool descriptions name the requests they answer ("pause the music on my desktop"), so an assistant picks kōan without being told to.
Fixed
- The time labels no longer wrap for tracks of an hour or more ("9:02:03").
- An app's library pages show what a push brought in. A pushed track the app had not synced yet triggered a sync, but the pages did not know to read again.
0.37.0
Added
- A kōan server can play music on a linked phone or Mac. The apps, signed in to a kōan server, keep a WebSocket open to it (
/rest/koanLink, authenticated like the rest of/rest), and the server can send them a list of tracks to play or queue, or pause and skip. GraphQL lists them withclientsand commands them withplayOnClientandcontrolClient, so an assistant on the server's MCP can build a playlist from the library and have it start on the phone in your pocket. Subsonic has no way for a server to reach a client, so this is a kōan extension. An app is linked while it runs; iOS suspends one that is backgrounded and not playing, and the server drops a link that goes quiet.
0.36.10
Fixed
- Artists sort by name. The listing ordered by the artist's sort name where it had one, and syncs before 0.36.2 stored a server's missing sort name as an empty string, so 1,800 artists sorted as blank, in no order, ahead of the rest. It orders by the name as it reads; tag sort names are too erratic to order by. Empty sort names, labels and genres left by those syncs are cleared when the database opens, and a sync no longer stores an empty genre or label.
- An artist with no biography found is asked about again. A lookup that found nothing was cached for a month, so an artist that could not be resolved then (as with the empty ids fixed in 0.36.9) stayed blank. Misses are no longer cached, and those already cached are dropped. The page says it is looking the artist up while it does.
- iOS: artist rows give the name room. The album and track counts sit under the name instead of in two columns beside it, which cut names to four letters.
0.36.9
Changed
- The Helm chart is replaced by a Pulumi component package, published to GitHub Packages with each release at the app's version. The estate this server deploys into is managed with Pulumi, and its updater follows npm packages rather than an OCI-hosted Helm chart.
Fixed
- Artist bios and photos show for artists synced from a server. Syncs before 0.36.2 stored the server's empty
musicBrainzIdas an empty string, and artist info took that for an id: it looked "" up instead of finding the artist's real one, so Crass and 1,800 other artists showed nothing. Empty ids are cleared when the database opens, and artist info treats one as missing.
0.36.8
Fixed
- An hourly sync picks up albums changed on the server. An incremental sync fetched only albums created since the last one, and a retag keeps an album's creation date (and can give it a new id), so the client kept the old tags until a Full Sync. It now also fetches any album it does not hold, or holds with another title, artist, track count or length than the server lists. The album list is already fetched every sync, so this costs no extra requests to decide. Above 200 changed albums it pages every song instead, about a hundred requests for the whole library.
- The album page gives titles room, and the heart bounces. A title beside the play button was held to one line although two were allowed, and the page's track titles truncated to their date. The header wraps to two lines, track titles do too on iOS, and a leading date is left off both. Favouriting bounces the heart, and on a phone taps the hand.
- iOS: the queue gives titles room. Track and album titles wrap to two lines instead of truncating to a date. A record that is a single track of the same name (a mix, a single) is one row with its sleeve and artist, not a heading and a row saying the same thing twice. The header names what is playing on its own, without "Playing" taking half its width. A leading date ("2022-03-12: ") is left off displayed titles, since the year is shown beside them; the tags keep it.
0.36.7
Fixed
- Failed Subsonic sign-ins are throttled. Every Subsonic request carries a credential, and a wrong password (argon2 per guess) or a wrong token against an account's password (an MD5, and cheap) could be tried without limit. Ten failures in a minute for one account from one address now refuse that account's password sign-ins from there for the rest of the minute. Only refusals count. API keys and the
[subsonic]shared secret's token are random and never throttled, so a flood of wrong passwords cannot lock out apps signed in with either. The web sign-in's limiter now takes the client's address from a trusted proxy'sX-Forwarded-For, rather than counting everyone behind the proxy as one client. - iOS: the queue is not in selection mode until asked. Every row showed a selection circle and a drag handle all the time. Select, in the queue's menu, turns them on, and Done turns them off and clears the selection.
- A downloading MP4 or M4A starts playing before it has all arrived. MP4 bounds its top-level boxes by the end of the file, and the fallback probe gave it the end of what had arrived, so a
moovlarger than the first 256 KB overran it and the track waited for the whole download: two hours of mix, over a phone connection. MP4 now gets the whole file's end, as Ogg does. The probe also read a download's extension aspart(fromtrack.m4a.part), so neither rule nor Symphonia's format hint applied to any download in progress. - Sharing a whole album from a koan server shares that album. koan numbers albums and songs separately and publishes album ids bare, and its
createSharereads a bare id as a song, so album 46215 was shared as whichever song had that number. A client talking to a koan server now names the albumal-46215. Other servers are sent their ids unchanged. - iOS: a share link is reported as done, not as an error. "Share link copied" appeared under "Something went wrong"; it is now a notice, as on the Mac.
- iOS: the queue header in selection mode fits a phone. The count, Clear and Remove were squeezed by the rest of the header and wrapped a few letters to a line. Each now keeps its own width, and on iOS Clear and Remove are icons.
- iOS: queue rows give the title the width. A duration of an hour or more wrapped onto two lines in its fixed column, and the codec repeated what the album heading says. The duration keeps one line at whatever width it needs, and the codec is left off on iOS.
0.36.6
Fixed
- Fuzzy search ignores case, and finishes. The album and artist results in the apps' search, and GraphQL's fuzzy search, matched with smart case: a query with a capital letter matched case-sensitively, and a phone keyboard capitalises the first letter, so "Spfdj" missed "SPFDJ" and matched unrelated text instead. They also snapshotted the matcher after a fixed number of ticks, which on a slow device or large library could return a partial result. Matching is now case-insensitive and runs until every item has been seen.
0.36.5
Fixed
- Album and artist favourites over Subsonic. A koan server's
starandunstarhandled one song per request:albumIdandartistIdwere refused, a repeatedidwas a plain-text HTTP 400, andgetStarred2listed songs only. So starring an album or artist from the koan apps against a koan server failed, and favourites made elsewhere never reached them. All three parameters now repeat and combine, anidmay name an album or artist by prefix, andgetStarred2returns starred artists and albums alongside songs.
0.36.4
Added
- A Helm chart for the headless server, published to
oci://ghcr.io/radiosilence/charts/koanwith each release at the app's version. What a koan server needs in a cluster is koan's own knowledge -- the Deployment, its init container, Services and NetworkPolicy -- not a copy of it kept in every deployment's own repository.
Fixed
- iOS: the Albums page can be sorted. The sort menu lived only in the Mac's window toolbar. It is now in the navigation bar, with the reshuffle button beside it under Random.
0.36.3
Changed
- Releases publish the container image as
latestandvX.Y.Z. The image was built by a workflow of its own and only ever tagged with the commit andmain, so a release had no image of its version andghcr.io/radiosilence/koanwithout a tag resolved to nothing. It is now a job in CI/CD, which knows when a commit is a release. Pull requests build the image only when theDockerfileor.dockerignorechanges; the Rust jobs already cover the code it compiles.
Fixed
- A koan server answers
download. It implemented onlystream, and koan's download queue fetches throughdownload, so every track from a koan server failed to load in the iOS and macOS apps (and in any Subsonic client that caches offline).downloadnow serves the original file, asstreamdoes.
0.36.2
Added
The web UI and share pages have a favicon and home-screen icon: the app icon, as on koan.rocks.
The web UI spells its name kōan in the sidebar, the tab title, the sign-in page and the version label.
koan runs on iOS. The same engine, models and pages as the Mac app, in a phone's shell: a tab bar (Queue, Library, Settings, Search), a mini player above it, and a full-screen Now Playing with the seek bar, lyrics in place of the sleeve, radio, the output format and an AirPlay picker. Every page stands in the playing record's wash, as the Mac's window does. An iPad with room for a sidebar gets the Mac's layout instead; the choice follows the width, not the device.
just ios-runbuilds it for a simulator. iOS 26 or later.Output goes through RemoteIO, from the same
engine.rsthe Mac uses; the two differ only in which output unit they open and whether a device can be named. The decode pipeline, timeline, gapless cursor and teardown are shared rather than rewritten. What iOS costs is the bit-perfect claim: everything crosses the system mixer, so koan plays at whatever rate the session settles on.Built for a battery. The spectrum analyser behind the playing bars stops while the app is in the background, runs at no more than 60fps on a phone, and at 30 in Low Power Mode, which also stills the wash's drift and the bars. RemoteIO is asked for a 93ms buffer, so the render thread wakes a twentieth as often as the default.
A phone call pauses playback, and so does unplugging headphones. After an interruption koan resumes only when iOS says it should.
Changed
- koan.rocks is styled with Tailwind. The page keeps its hand-written HTML and takes blit's look: Geist Mono, lowercase thin headings and one red accent, dark by default. The stylesheet is compiled by the standalone Tailwind CLI (
mise run cssinsite/), so the site has no package manifest; the Site workflow builds it before the image and it is not committed. The app screenshots are cropped to the window, so nothing behind it shows at the edges. - The product is spelled kōan wherever a person reads it: the README and guides, the macOS and iOS apps (window title, settings, errors, the iOS home-screen name), CLI help, and the messages the CLI, daemon and MCP endpoint print. The command, crates, paths, URLs, environment variables and config keys stay
koan. - The decode thread sleeps 10ms, not half a millisecond, while the ring buffer is full. A full ring is where playback spends nearly all its time, so the old wait was two thousand wakes a second for the length of every track, on every platform. The ring holds a second or more of audio at any rate koan plays.
- The Subsonic API, share pages, sign-in and token refresh reuse database connections. Each request opened its own, which applied the schema DDL and ran a WAL checkpoint first, and a Subsonic client syncing a library makes thousands of requests. They now share one connection pool per server, as GraphQL and the web UI already did; account password and token checks for Subsonic and MCP over HTTP use it too. The radio's top-ups, background playlist pushes and organize by path use pooled connections as well.
- Subsonic, sign-in, token refresh and sign-out no longer run on the server's async workers. Their SQLite queries and argon2 checks ran inline, so a few concurrent Subsonic calls could occupy every worker and stall unrelated routes, the web UI included. They now run on the blocking pool, as GraphQL, the web UI and share pages already did.
- A first or full remote sync pages songs instead of fetching every album. It fetched each album with its own
getAlbum, one round trip per album, which for about 5,500 albums over a phone's link took minutes. It now reads album metadata fromgetAlbumList2and every song fromsearch3with an empty query, 500 per page and four pages in flight, joining the two and writing each page in one transaction: about 110 requests for 50,000 tracks. A server that answers an empty query with no songs gets the per-album walk, as before; an incremental sync still fetches only its new albums. A page that fails after three attempts leaves the run incomplete, solast_syncstays put and the next sync walks the library again. - Syncs report progress.
sync_librarytakes a callback carrying the phase (albums, tracks, artists, finishing) and done/total counts, the total from the albums'songCountsum orgetScanStatus. The CLI draws it on one line; GraphQL jobs gaindoneandtotal, with the phase inmessage; the FFI publishes it as aSyncstate slice for automatic and requested syncs alike, and the macOS activity row shows "12,400 of 49,700 tracks" with a determinate bar.
Fixed
- Web UI: the signed-in username gets a line of its own above API keys and Sign out, instead of being truncated beside them.
- Subsonic
search3pages.artistOffset,albumOffsetandsongOffsetwere ignored, so every page repeated the first. An empty query (query=orquery="") lists the whole library in id order, straight off the primary keys, so an offset walk neither skips nor repeats. Counts are capped at 1,000 per kind. - Empty OpenSubsonic ids no longer pair unrelated tracks. A koan server sends
musicBrainzId: ""andsortName: ""where it has no value, and the client kept them as present. Every untagged remote track then matched every other on the MusicBrainz dedup (recording""on release""), which could fold a remote track into an unrelated local file with the same track number and made each insert scan the whole table, so a 50,000-track sync slowed as it went. The client now reads empty ids as absent, and the dedup ignores an empty id. - The macOS app shows the automatic sync and the startup scan. The engine never published the
Tasksslice, so neither row ever appeared. - iOS launches to the icon's ensō rather than a blank screen and a spinner. The launch screen was empty; it now draws the ensō on its ground, and the app draws the same image in the same place until the engine is up. The mini player's sleeve and buttons also clear the capsule's curved ends.
Internal
- koan-core's suite runs on the iOS simulator. It found
DestinationLedgertreating iOS as a case-sensitive filesystem.case_only_rename_keeps_the_fileis macOS-only: the simulator's sandbox answersstatandopen(O_EXCL)inconsistently for a case-only rename, so it cannot be detected there. - The shared SwiftUI sources build for iOS, and CI checks it (
just ios-typecheck). Images go through aPlatformImagealias. The views that move layers in the render server (the wash, the playing bars, the seek bar) share aLayerViewbase and aPlatformViewRepresentablebridge, so AppKit and UIKit run the same code. Startup, search scheduling and search submission moved out of the macOS scene root intoAppStateandSearchModel, where any shell reaches them.
0.36.1
Added
- The web UI shows the server's version under the account controls (the sidebar on a desktop, the footer on a phone), linked to its release notes.
Changed
- The README and koan.rocks describe koan as a server: web UI, share links, OpenSubsonic, accounts and API keys, MCP over HTTP.
0.36.0
Added
- Subsonic token auth for koan accounts. Most Subsonic clients (Play:Sub, and koan's own releases before this one) sign in with
t=md5(password + salt), which cannot be checked against an argon2 hash. Each account's password is now also kept sealed with AES-256-GCM underauth/subsonic.key(created on first use, 0600), bound to the username, and token auth opens it, compares the token, then checks the password against the hash as usual, so a password changed elsewhere stops working. The sealed copy is written whenever the password is proven: web sign-in, ap=sign-in,koan auth create-userandkoan auth reset-password. An account without one still gets error 41, so clients can fall back. - OpenSubsonic. Every
/rest/*response carriesopenSubsonic,type="koan"andserverVersion, andgetOpenSubsonicExtensionsanswers without sign-in. Extensions:apiKeyAuthentication(apiKey=andtokenInfo; keys made withkoan auth api-key createor on the web UI's API keys page, stored assha256, shown once, acting at their account's current role),formPost(parameters in anapplication/x-www-form-urlencodedbody, merged with the query string, repeated keys included) andsongLyrics(getLyricsBySongId, from the lyrics koan has cached, LRC split into timed lines). Token auth for a username other than the shared secret's is now error 41 rather than 40, which is what tells a client to fall back to a password or a key. Songs, albums and artists carry the OpenSubsonic fields koan has data for: MusicBrainz ids, sort names, display artists, genres as lists, the album date asreleaseDate, record labels, last played, and bit depth, sample rate and channel count; albums also gain thedurationandcreatedSubsonic always required, and list fields are arrays in JSON even with one member. - koan.rocks. The project website, as hand-written static HTML and CSS in
site/with no build step and no tracking. The Site workflow buildsghcr.io/radiosilence/koan-site(nano-web) on every push to main, taggedsha-<commit>andlatest, and asks the jaritanet deployment to pick it up. - Web UI. A server serves a small browser UI at
/: sign in, browse albums (newest first), artists and search, and play in the browser. Tracks the browser can decode are decoded ahead and started on the sample the last one ends, the same engine as the share page, now one file both load. The queue lives in the browser and survives a reload; the transport has lock-screen controls through the Media Session API. Server-rendered HTML with Datastar for search, paging and the share button; navigation swaps only the page content, so playback continues across pages. Sign-in is koan's own session inHttpOnlycookies: a lapsed access cookie is renewed from the refresh cookie (/auth/resumefor page loads,/auth/renewfor an open page), so no token reaches page script. - Native sharing. A koan with no remote Subsonic server makes share links itself, at
{sharing.public_url}/share/{id}: a page anyone can open without an account, with cover art, the track list and a player per track, and no script at all. The page and its audio serve the share's own tracks and nothing else, by position rather than library id, and an expired, revoked or unknown id is the same 404. Shares are listed withshares, renewed withupdateShareand revoked withdeleteShare(GraphQL and MCP), and koan's Subsonic API implementscreateShare,getShares,updateShareanddeleteSharewithshareRoleon, so Subsonic clients' own share buttons and a koan app pointed at a koan server create native shares. Sharing no longer needs Navidrome behind it. - MCP over HTTP for a headless server.
--mcp-bind ADDR:PORT(orKOAN_MCP_BIND) serves the same two MCP tools at/mcpover streamable HTTP, on a listener of its own, for an authenticating gateway to proxy. It carries no credential check, as stdio does not, so it stays off the public port. - A headless server keeps its index current. It scans the library folders at start and whenever they change, as the macOS app already did; new music needed
koan scanor thetriggerScanmutation before. - Container image. A
Dockerfilefor the headless server (Debian slim, non-root, state in/config), published toghcr.io/radiosilence/koanfrommain, tagged with the commit.
Changed
- Shares are slices of the library. A single track shares its album, opening cued to that track; an album shares the album; an artist shares a page of their albums in release order, each playable; several tracks from different places stay a track list. The slice (kind, subject, start track and the explicit track list) is fixed when the share is made, so an artist share does not grow with later albums and the page and its audio still answer for exactly those tracks. Subsonic
createSharepicks the slice from the ids given; GraphQLcreateSharetakesalbumId,artistIdandstartTrackIdbesidestrackIds, andsharesreports each link'skind. The web UI shares albums, single tracks and artists. Schema version 5. - Share links unfurl. Share pages carry OpenGraph and Twitter card tags (title, a description with tracks and duration, and the cover as an absolute
og:imageonsharing.public_url), so messaging apps show a card with the cover. - The web UI sorts and filters. Albums sort as the macOS app does (recently added, title, artist, year, random) and artists by name, album count or recently added; both filter by favourites, lossless or a codec, a year range and a genre. The sorting, filtering and paging are done in SQL, and the state is the page's query string, so reload, back and a copied link all show the same listing. On a phone the controls fold into one "Sort · Filter" sheet.
AlbumQueryandArtistQuerygain theAlbumFilterthat does this, andArtistQueryanArtistOrder. - Covers load fast in the web UI and on share pages. They were served as embedded, often several hundred kilobytes each, re-read from the audio file on every request; an albums page pulled about 15 MB. They are now resized to the size shown (400 px tiles, 800 px headers and previews), encoded as JPEG, kept on disk under
covers/in the config directory and in memory, and addressed by a URL that carries the album's file mtime so browsers cache them for good. An album with no art is remembered rather than re-read. The same albums page now fetches about 2.3 MB. - The MCP over HTTP acts as the gateway's signed-in koan account. The gateway sends
x-koan-usernameandx-koan-password; thegraphqltool runs at that account's role (admin, user or readonly), checked the same way as Subsonic'sp=. A request naming no account keeps the transport default (User, orAdminwithKOAN_MCP_ADMIN=1), unlessKOAN_MCP_REQUIRE_LOGIN=1refuses it. stdio is unchanged. - Subsonic clients sign in with koan accounts.
/rest/*acceptsp=(plain orenc:hex) checked against the account's argon2 hash, so the web UI login works in Subsonic clients too; a successful check is remembered for ten minutes, keyed on the stored hash so a password change ends it. Token auth needs the plaintext on the server, so it remains only for the[subsonic]shared secret, which is now optional.readonlyaccounts get code 50 from every endpoint that writes (stars, scrobbles, playlists, shares) andgetUserreports each account's real roles. koan's own client sendsp=enc:over HTTPS and the salted token over HTTP. - Releases of the macOS app are signed with a Developer ID and notarised. The release job imports the certificate into a keychain of its own, signs the app with the hardened runtime and a secure timestamp, signs the DMG, has Apple notarise it and staples the ticket, so a downloaded
Koan.dmgopens without the quarantine workaround.just macos-notarizedoes the same locally. Without the signing secrets (a fork) the build is ad-hoc signed as before. - The server sign-in fields say what they are. An iOS form shows a field's prompt and not its label, so the prompts were the only text on screen, and they were examples (
https://music.example.com,your account,hunter2). They now read Server URL, Username and Password. - The share page plays gaplessly, and looks like the rest of the estate. Tracks the browser can decode are decoded ahead and each is started on the sample the last one ends, so albums that run into each other play without a gap; a track too long to hold decoded (over fifteen minutes) streams instead. One player with previous, play and next, a seek bar, and lock-screen and headphone controls through the Media Session API. The script and stylesheet are served by koan (
/share/assets/*) and the CSP allows those and nothing else; without script, each track is a plain link.
Fixed
- Sound with the iPhone on silent. Decoded audio is now heard through a media element (a MediaStream destination played by
<audio>) rather than straight from Web Audio, which iOS silences with the ring/silent switch however the page declares itself. Scheduling stays on the AudioContext clock, so gapless playback is unchanged, and a media element also keeps playing on the lock screen and in the background. Browsers without MediaStream output play to the context directly, as before. - The seek bar follows the track again. It stopped updating once clicked, because the position updater skipped a focused range and a clicked range keeps focus; it now skips only while the range is being dragged, and resets as soon as the track changes.
- Browser sign-in set only one cookie.
/auth/login,/auth/refreshand/auth/logoutsent their cookies as a header array, which keeps only the last value per name, so browsers received the stale-path clear and never the access or refresh cookie. - The share page plays on iPhone. iOS starts audio only inside the tap itself; the player created its audio context there but resumed it after fetching and decoding the first track, which iOS no longer counts as the tap, so nothing played. The context and the streaming element are now unlocked in the gesture, and the page declares itself a media player (
navigator.audioSession), so the ring/silent switch no longer mutes Web Audio. - A server with auth on starts without
koan auth setuphaving run first. It generates its signing keypair on first start, as the auth-disabled path already did; a server in a container has no terminal to run setup in before it starts, and crash-looped instead. Accounts are still created deliberately: until one exists, nothing signs in.
0.35.5
Fixed
- Clear Index no longer leaves albums showing another album's cover. Artwork is cached on disk by album, track and artist id, and a cleared library hands those ids out again from 1, so the cache served each new album the cover of whichever old one had held its number. Clearing the index now clears the artwork cache too. A library already affected needs Clear Artwork Cache once.
0.35.4
Fixed
- A full sync also clears what the server's renumbering left behind. An entry that exists only on the server, still under an id the server has dropped, cannot be streamed, and it sat beside the entry that replaced it. It is now folded into that entry, with its play history and favourite. Files without a track number are paired with their server entry in the same sync, where before they needed a second one.
0.35.3
Changed
dirs7.0.0 (#444) andlru0.18.5 (#443). Neither changes behaviour;dirs7 resolves the home and music folders exactly as 6 did.
Fixed
- A full sync relinks files after the server renumbers its tracks. When a Navidrome rescan gave every track a new id, the local file kept the old one. The sync added the recording again under the new id, and the two were never merged because both carried a server id, so the library listed each affected track twice. After a complete full sync, a file whose id the server no longer has is unlinked and merged into the entry carrying the current id, keeping its play history and favourites. (#445)
- The album grid's reshuffle button is a die. It used the shuffle symbol, the same one as playing an artist or a record shuffled, for an action that plays nothing. (#441)
0.35.2
Fixed
- The log is written on a first launch. The logger opened
koan.logbefore anything had created~/.config/koan, failed, and stayed silent for the rest of the run, so a first launch of the macOS app, or of the CLI on a fresh machine, left nothing to diagnose. It now creates the directory itself and retries the open on a later message if one fails.
0.35.1
Fixed
- Back returns to where the album grid and the artist list were scrolled. Both were rebuilt on the way back, and a macOS
Listcannot be told to scroll, so they always came back at the top. Once visited they now stay mounted behind the other pages, as the queue already did. Clicking a sidebar row for the page already showing sends it back to the top instead, the way a browser tab's own link does. (#440) - The
koan-appcask usespostflight_steps. Homebrew deprecated the block form ofpostflightand warns about it on everybrew update.
0.35.0
Added
- An artist page carries a photograph and a biography. The photograph sits beside the name; the opening of the artist's Wikipedia article sits below the albums, with a link to the rest and the photographer's credit. Both are found through the artist's MusicBrainz id and the Wikidata item it links to, never by name alone, since a name search picks the wrong one of several bands sharing a name. An artist without an id on record is identified through one of their releases first, and only then by an exact, unique name match. Answers are cached, misses included, so the page draws from the database and is refreshed after a month. No API key is needed. (#436)
Fixed
- MusicBrainz artist searches match the whole name. A name of several words was searched word by word, so "Azure Ray" found Ray Charles. This also sharpens radio's relationship lookups.
- Shuffle sits in the artist page's button row, beside Play Next and Queue, rather than on a line of its own below them. (#437)
0.34.3
Added
- Pause and resume fade. The volume ramps over 150ms instead of cutting, and the play head stops on the last sample heard.
playback.fade_on_pause, on by default; Settings → Playback. Outside the ramp samples pass through untouched, so playback stays bit-perfect.
0.34.2
Fixed
- Organize could jam on "Moving…" for good. Changing the pattern or destination while a run was going invalidated the run's result before it cleared its own running flag, so the sheet never came back until relaunch.
- A slow load no longer lands on the page you moved to. A cover still loading when the track changed, lyrics still reading when you skipped, a playlist still opening when you clicked another: each finished late and painted over what was now on screen.
- Back and Forward after deleting a playlist could crash. The history entry was pruned while the move was loading, and the arrival set the cursor past the end.
- Opening several covers of one record at once fetches and decodes it once. Concurrent tiles each started their own fetch and decode — the sharing checked and claimed in two separate steps.
- A seek the engine clamps no longer pins the seek bar. It gave up after twenty playhead updates, which were once a timer's ticks and now arrive only on a seek or pause, so it could wait until the track ended. It gives up after two seconds. A Control Center scrub past what has downloaded is clamped like one in the app.
- The wash and the seek bar hold their place across page switches. Each re-laid itself out from its last anchor on any layout pass, snapping the drift to its start and the bar backwards.
- The cache limit saves what you typed, not each keystroke. Typing "50GB" wrote "5", "50", "50G" on the way. The discovery slider saves when you let go.
- Playlist runs group by record. Two neighbouring "Greatest Hits" by different artists merged under one heading, named after the first track's artist.
- Go to Album highlights the track when the album is already open, or has as many tracks as the one before.
- Add & Play in the picker waits for the queue rather than a guessed 120ms.
- With several artists selected, the menu and double-click no longer act on one at random.
- Smaller: an error toast replaced by another keeps its own six seconds; a drop highlight on one playlist is no longer cleared by the row it left; "New Playlist…" is a button to VoiceOver; a filter field created after ⌘F was used no longer steals focus; the frame timer's settle check compared ticks the wrong way round and stopped early; the Plain graphics description had holes in it; the output device menu no longer asks for a symbol named "".
- A pause no longer re-runs the whole transport bar, and a seek no longer re-diffs every lyric line. The reads moved into the views that draw them.
- Signing out of the web client revokes the session. The refresh cookie was scoped to
/auth/refresh, so the browser never sent it to/auth/logout: the cookies were cleared and the token stayed valid for its full thirty days. It is scoped to/auth, and the old narrower one is cleared wherever the cookie is set. - Login takes as long for a username that doesn't exist as for one that does. An unknown name returned at once, while a known one paid for an Argon2 verify — enough to list who has an account.
- Long tracks proxied through the Subsonic API no longer cut off at thirty seconds. The upstream client's timeout covered the whole body, so any stream that took longer to drain than that was ended mid-track. It bounds connecting and stalls instead.
- Subsonic "now playing" is no longer recorded as a play. Clients scrobble with
submission=falsewhen a track starts andtruewhen it ends; both were recorded, so every listen was two plays and a skip was one. - Starring a remote-only track over Subsonic or GraphQL stars that track. Subsonic keyed it by an empty path, so every remote track shared one favourite; GraphQL refused them. Both use the same key the app does now, and Subsonic stars sync back to the server. An album or artist id is refused rather than read as a track id.
koan configno longer prints passwords and tokens.- Generated admin passwords come from the system RNG. They were hashed from the clock a character at a time.
- A file dropped into the TUI with an accent in its path opens. Percent-escapes were decoded as Latin-1.
- The TUI no longer rewrites the whole queue ten times a second while playing. It saves the queue when it changes and the position about once a second.
- A restored TUI session resumes the track it saved, the way it saved it. The saved position went to whichever track became ready first, and always paused.
- Deleting a playlist that was never on a server removes it from the sidebar.
- Playing a playlist over GraphQL keeps the queue following the playlist, as it does in the app, and is one queue change rather than three.
koan --headlessexits non-zero if its port is taken, and the[subsonic] portfrom config is used on every path, not only the TUI.updateConfigrefuses out-of-range numbers instead of wrapping them — a port of 70000 was saved as 4464.- A record whose files say disc 0 no longer shows every track twice. Taggers write disc 0 for a single-disc release; Navidrome leaves the field out. Dedup compares the disc, so 0 against nothing read as two different tracks — the local copy and the server's, side by side on one album page, the server's failing whenever it was unreachable. Disc 0 is stored as no disc now, whichever source sends it. Pairs already split are folded on the next launch; the local row keeps its file and history and takes the server's id.
- Skipping, seeking or stopping a track that is still downloading no longer freezes the player. The decoder waits at the download's write head for the next bytes, and stopping it only asked it to stop — it did not wake it. On a slow or stalled transfer the player thread sat in that join for as long as the network took, up to thirty seconds, answering nothing.
- A stream no longer stalls for thirty seconds when its download ends. The reader was woken before the track was marked finished or failed, looked, saw a download still running, and went back to sleep with nothing left to wake it. It is woken after, now.
- A download that retries no longer kills the stream playing from it. Each attempt deleted the
.partfile and created a new one; a stream reading it held the deleted one and waited on bytes that would never land there. A retry now rewrites the same file. A server answering 5xx with a JSON body is also retried now — it was taken for a Subsonic error document and given up on. - Previous on a track not yet downloaded goes to it. The cursor moved and the old track kept playing, so the next track boundary replayed the same song.
- A front end could miss a pause, a track change or a radio toggle. The change was announced a moment before it was written, so a client woken by it could read the old value and go back to sleep.
- An album date starting with a non-ASCII character no longer crashes koan. Years were cut out of dates by byte, which panics mid-character — full-width digits, a leading
〜. - Undoing a very large batched edit undoes all of it, not the first 500 steps.
- The download queue no longer looks at the cursor every 30ms for the life of the process. It waits for the engine to say something moved, like every other watcher.
- A refresh token in a git-tracked config refuses to start, the same as a password does.
- The CoreAudio render callback no longer logs. Two warnings on rare paths formatted and took the logger's lock on the real-time thread.
- A file on disk and the server's copy of it are one track, whatever the server calls the album. Navidrome appends a release's MusicBrainz disambiguation to its name — "(deluxe)", "(Bandcamp)", "(Unmixed)" — and dedup matched on the album name, so thousands of tracks sat twice on two album pages: one playing from disk, one streaming, and dead whenever the server was unreachable. koan now reads the recording and release ids from local tags (Picard's
MUSICBRAINZ_TRACKID/MUSICBRAINZ_ALBUMID) and matches on the pair. The recording alone would fold an album track into every compilation it is on; the release is what keeps those apart. The next scan after upgrading re-reads the files indexed without an id, once, and folds what it finds. (#422) - The test suite no longer opens the library of whoever runs it. The TUI's
AppandLibraryStatetook a database path and ignored it, reading through the shared pool, which opens the configured library. A render test that browsed the library therefore opened the developer's own — and opening it runs the checked-out branch's migrations against it. The dead parameters are gone, the test isolates its config like the others, andjust checkruns the suite against a throwaway config dir and fails if anything writes there. (#423)
0.34.1
Changed
Every change on screen now does only the work that change needs. A pass over what each view reads, following the rule the last release set for the filter field: a read is a subscription, and a read high in the tree re-runs everything below it.
The room's colour — the wash and the tint — was read by the root, so every track change re-ran the whole window and rebuilt the toolbar, which is the same thing that used to throw you out of the filter field. It is a modifier of its own now. The queue and every track list read what was playing and which rows were selected in the list's body, so a pause, a click or a queue edit re-diffed every row; the rows read those themselves, and selection comes from the List through
backgroundProminence. A playlist page found each row's position by searching the list per row per evaluation, quadratic on every click. The seek bar read the download figures, so while anything was downloading it re-anchored its animation ten times a second — the animation the anchor exists to hand over once. Every row and tile read the favourite sets, so one heart flipping re-ran every visible row; the hearts read them now. Favourites laid out every record you had ever favourited the moment the page opened and fetched all their sleeves at once; the grid is cut into list rows, which the list recycles.The playing indicator is no longer SwiftUI. The analyser published each frame through observation, which made every frame a body, a canvas raster and a commit at the display's rate for as long as music played. The bars are layers now, moved directly, at the same rate — and detach when off stage or held still, which lets the analyser park.
A click outside a text field ends the editing. Filter the albums, click a cover to play it, and every key after that went into the filter — a cover is a SwiftUI gesture and takes no focus, so the field kept it. It used to be let go by accident, when the toolbar rebuilt itself on the next track change. The hotkey monitor now ends editing on any click that is not inside the field being edited.
A queue edit is no longer a playback change. The queue version rode in the same slice as what is playing, so every edit re-ran the transport bar and every list that knew what was playing. It rides with the queue rows now.
Downloads landing one after another are one library change, not one each. A record fetched a track at a time made every page reload its rows per track. The engine says so once the batch is down, or every couple of seconds while it is still coming.
Fixed
- A file dropped from Finder no longer doubles on the next rescan if its name has an accent. Foundation hands over file paths with accents precomposed, and a Mac-written disk holds them decomposed; both open the same file, but
tracks.pathis compared bytewise, so a rescan saw a file it had no row for and added a second one. Only the accented names on an album doubled, which is what made it look like nothing in particular. Paths from outside — a drop, a configured folder, a folder being forgotten — are now resolved against the directory that holds them and stored as it spells them. Pairs already split are folded on the next launch: the older row keeps its history and sync link and takes the disk's spelling; favourites follow. (#418)
0.34.0
Security
- rustls accepted TLS 1.3 handshake messages across a key change (RUSTSEC-2026-0285) — a Subsonic/Navidrome server, or anyone between koan and one, could send handshake messages in plaintext that should have been encrypted without the connection being refused. The transcript is still authenticated, so a handshake could not be altered or completed this way. rustls is now 0.23.45.
Added
Pick several albums and play or queue them together. Select in the Albums toolbar, ⌘-click a cover, or ⌘A turns the grid into a selection: a click ticks a record, ⇧-click ticks a range, and Play or Add to Queue takes the lot and puts the grid back. A mode rather than list-style clicking, because a click on a tile already plays the record and its title already opens it.
Ticks survive the filter changing, so a pick can be gathered across several searches, and they play in the order they were made — the grid has no order for a record it is no longer showing. Dragging a ticked tile carries every tick to the queue or a playlist; an unticked one still carries only itself. Escape, Done or leaving the page ends it.
Fixed
Typing in the filter field no longer throws you out of it. The first keystroke re-ran the whole window, and the toolbar rebuilt the field with it — so the filter applied and focus went with the old field. Two reads caused it: the menus asked whether anyone was typing from the Scene body, which is the whole window, and the field read the filter back in
RootView, where SwiftUI charged it to the root.The same mistake ran through the rest of the window. Every letter typed into the search box re-ran the root and the whole sidebar, and a pause, a toast or a download ticking over re-ran one or the other. Each is now read by the view that draws it — the menu items, the filter field, the sidebar's Queue and Downloads rows, its footer, the toasts, the wash behind the window — and a keystroke reaches the field and what shows the results, nothing else.
A recording two sources credit differently is no longer two tracks. Cross-source dedup matched on the artist alongside album, disc, track number and title, so a local file tagged
Petrol Girlsand the same recording arriving from Navidrome asPetrol Girls • Ren Aldridgeresolved to two artists and therefore two tracks — drawn one after the other on the same album page, each with its own source icon. A server that merely disagrees about case did it too:PolysicsagainstPOLYSICS,War Of AgesagainstWar of Ages.Album, disc, track number and title already name one position on a release, so the artist is the thing the sources disagree about rather than the thing telling two recordings apart. A fourth matching step drops it. It requires a track number on both sides: with no slot to match on, the artist is all that separates two same-titled recordings on one release, and the step declines rather than guess. The cross-source rule is untouched — two files on disk are two tracks however identical their tags, and so are two entries on one server.
Pairs already split are folded together on the next launch. A sync could never do it: it matches a remote row by the id the server gave it, long before any content match runs, so the two would have stayed apart for good. The local row wins — it holds the path and the properties read from the file, and playback prefers it — and inherits the id the server knows it by. Only a clean pair is touched: one row with a path and no remote id, one with a remote id and no path, sharing an album, a title, a disc and a track number. Anything else is left where it is rather than guessed at.
0.33.2
Changed
The playing indicator is a spectrum analyser, three columns wide. It was a pair of sine waves the music modulated — the bands set how far the bars swung, never how high they stood — which meant a track that opens on ten seconds of silence got the full dance, because a carrier with nothing to scale it is still a carrier. The bars are the low, mid and high bands now, drawn at the height the analyser reports. Silence is flat. Pausing lets them fall away rather than freezing them mid-swing, which is what the TUI's spectrum has always done.
Bands are still measured against their own recent ceiling, so a quiet master is not a limp indicator, and the fall is the law the TUI's bars draw on: up on the frame it happens, down on a half-life so nothing snaps to zero between beats.
The analyser runs at the refresh rate of the display it is drawn on. Its rate was a config figure and the macOS indicator sampled it on a timer of its own, so a 120Hz panel got 60 analyses drawn at 30, and two clocks decided between them which frames a bar was allowed to move on. The window knows what it is drawn on: koan sets the rate from the screen the window is on and again when it is dragged to another one or a display is reconfigured under it. The indicators read on the frame they draw, so a frame is one new set of numbers and there is no timer anywhere in it — nothing on screen means nothing read, and the analyser stands itself down a second later. The TUI is unchanged: its rate is still
visualizer.fps, which is what the analyser starts at.The spectrum is published, not polled. The playing indicator asked the engine for levels on a clock — a timer at first, then the display link — because there was no event to react to. There is one now: the analyser sends a frame when it has one, the app wakes on it, and the bars are drawn from what arrived. No timer, no tick, and no frame read twice or missed.
What falls out of that is the idle cost. The analyser decays the bars to flat when the play head stops rather than holding the last chord, and once they are flat it publishes nothing at all — so a paused koan wakes nothing. The thread itself parks on a wait instead of standing down to a quarter-second look-again loop: with no reader and nothing playing it is not scheduled at all, until a reader arrives or playback starts. That last one cannot be signalled from the play head, which the audio render callback writes and which may never take a lock, so the player says so on the two edges where silence ends.
koan-coretakestokioforsynconly —watchis the analyser telling its subscribers a frame is ready. No runtime, no reactor.The playhead is an anchor, not a reading. Position was published ten times a second, which is a stream that can never go quiet while music plays and a seek bar redrawn ten times a second to move it a pixel. It is the one number in koan that changes without anything happening — and a playhead advancing at one second per second is exactly what a client can work out for itself. The engine now says where the playhead is when your own reckoning would go wrong: a seek, a pause, a track boundary, a stall. Nothing in between.
What draws it derives it. The seek bar is handed to Core Animation once per anchor with the rest of the track as its duration, so it moves without this process being woken at all; the elapsed figure is a system-drawn timer for the same reason; the lyrics panel sleeps until the next line's timestamp rather than checking where the song is. Media Remote gets told exactly when the system's own extrapolation would drift, which is what its elapsed-and-rate pair was always asking for.
The engine stops polling itself. A thread woke ten times a second for as long as koan was open, rebuilt what is playing, sampled every transfer's byte count, compared three version counters and published whatever had moved. The interface was reactive — the app has read events rather than asking since v0.32 — but the events were manufactured by a clock.
The writers say so now. Every setter on the player's shared state, the download store and the library version bump a wake; the watcher waits on it and reads the versions when it comes round, so a burst is still one pass and one message per slice. A koan with nothing happening does not schedule that thread at all.
Transfer rates go the same way: a reading is taken as the bytes land, held to one every 250ms, rather than by whoever happened to be watching. A transfer that settles zeroes its own figure rather than waiting to be sampled again — a row that finished used to keep the rate it managed on its last chunk until something looked.
The last three clocks go. The activity rows asked the engine whether a scan or a sync was running, once a second, for the whole life of the app, to notice something that happens twice a day — the engine says so now, in the same stream as everything else. The session autosave woke every second whether or not there was anything to save; it runs while the music does and writes on the edge when it stops. And a decode thread reading a track that is still downloading looked at the byte count every ten milliseconds: it waits on the count itself now, woken by the bytes as they land and by whatever ends the transfer.
The GraphQL subscriptions are pushed, not polled.
nowPlayingandqueueUpdatedlooked at the engine every 200ms and 500ms and yielded when something had moved;vizFrameresampled the analyser at whatever rate the client asked for, sending frames twice or skipping them depending on how the two clocks lined up. All three wait on a signal now.vizFrameis one message per analysed frame, and itsfpssets the rate the analyser itself runs at rather than a rate to resample it at — one analyser, so a second client asking for a different figure moves it for both.nowPlayingsends an anchor, the way the native client already receives one:positionMsis where the playhead was when the message was sent, and a client that knows it is playing can work out the rest. It arrives on a seek, a pause, a track boundary or a stall — not on a clock — so a paused koan sends nothing at all. A client drawing a moving position must derive it rather than waiting to be told. TheintervalMsarguments remain in the schema and are ignored, so existing queries still parse.The app waits to be told rather than looking. Restoring a session and jumping to the queue after an enqueue both watched a value every five milliseconds until it moved. They wait on the mirror now, with the deadline as one sleep for the whole wait rather than one per look.
Fixed
The transport sheds what will not fit rather than squashing it. The centre zone held
maxWidth: 560at the highest layout priority, so it claimed 560 points of any bar wide enough to offer them and left the two sides to share the remainder — about thirty points each at the smallest window. The format badge and the output device were drawn a few points wide, and the track's name got three letters. The centre is handed a share of the bar now and the sides split what is left equally, which is what keeps the transport centred; a side that runs short drops things in order — the radio toggle's word, then the sleeve, then the format badge — instead of compressing all of them.The window is wide enough for the columns it has.
NavigationSplitViewdoes not refuse to go below a column's declared minimum: it lays the column out at its ideal width and clips whatever does not fit. With the lyrics panel open there was nothing left to take, so the sidebar's rows and half the lyrics hung outside their own panes — and with no slack to move through, the split view stopped animating and started clamping, which is why the panel arrived whole in one frame instead of sliding. The floor is now the sum of what the columns actually draw at: the widest page's stage, the sidebar, and the panel. It is one number rather than one per column count, because a floor that moved when the panel opened resized the window under you.The lyrics panel slides open. Its state was
@AppStorage, and aUserDefaultswrite publishes on its own after the transaction that caused it has gone — so the pane had no animation to expand with while everything around it was still moving. It is observable state that writes through to defaults now, so the change happens inside the transaction and the pane and the stage move together.A clean security audit no longer reports itself as a failed build. The audit job reports through a GitHub check run, which is an API write, and this repository hands workflows a read-only token by default — so the job found nothing, tried to say so, and failed with "Resource not accessible by integration" on every push to main. It asks for the one permission it needs now.
Dependencies refreshed. Seventeen packages moved to their latest compatible release —
h2,hyper,flate2,log,uuid,randand the rest — with no version requirement changed and nothing to see from outside.chacha20moves off a yanked release. 0.10.0 and 0.10.1 called an SSE4.1 intrinsic from inside the SSE2 backend, so on an x86 processor with SSE2 and not SSE4.1 the instruction is illegal and the process dies. Upstream yanked both and shipped 0.10.2. Not a weakness in the cipher — a crash, and only on hardware old enough to matter to the Linux builds.
0.33.1
Added
- A graphics step below Plain. The setting reached koan's own chrome and nothing else: the toolbar floated over live content and the transport kept its soft scroll edge at every step, including the one whose description says it is "the only step that stands the glass down".
Barestands both down — an opaque toolbar ground and a hard scroll edge. Measured no faster on an M1 Pro, and it is here because what the setting said and what it did disagreed, not as a speed-up.
Changed
A record opens in one commit rather than three. The page was one; the wash was a second and the tint a third, both landing after it because both were held in view state written by a task, which cannot run until the body already has. The tint's was the worse of the two — it eased over two seconds, and a tint is a value every control reads rather than a property of a layer, so that is a hundred and twenty renders of the whole window for one colour. Both are read straight through the artwork cache now, the way a cover has been read since koan#284, so a colour and a sleeve the app already holds land in the same frame as the record that wanted them. Tap to first frame goes from 144–432ms to 101–208ms on a large library, and the spread goes with it — much of what looked like a slow database was the read's answer queued behind that animation.
Opening a record says how long it took. A signpost in a view says when SwiftUI worked out what to draw, which on this gesture is a few milliseconds and nowhere near when you see anything — layout, the CoreAnimation commit and the render server all come after the last line any view gets to run.
FrameTimertimes the tap against the display link instead, and reports the body, the frame that could carry it, and every stall after that. See CONTRIBUTING.Every page arrives complete. A record already loaded before it navigated; everywhere else arrived empty and filled in a query later — an artist's records, a playlist's rows, favourites, history, search results, and the queue you left behind when koan reopened.
Navigatornow loads whatever a page draws and only then moves to it, so the first frame of a page is the finished page. There is no partial render to see and no second render a frame later putting the rows under a heading that was already up.A page about one thing holds what it is about as one value, read whole and stamped with the library version it was read at — so asking again for the page on screen costs nothing, and asking after a scan is a real read. Sections hand their rows to the navigator, which adopts the page and its rows in one change rather than two. Typing in the search field no longer jumps to an empty results page on the first keystroke: it stays where you are until there is something to show.
A browse listing is only redrawn when it has actually changed. Albums, artists, favourites and history are each read whole and handed to SwiftUI whole — 5,610 records and 7,138 artists on a large library — and assigning that array again is a mutation whether or not a single row moved, so the grid was diffed end to end, laid out and committed for it. It was assigned again on every library version bump, which is every download landing and every playlist edit, and on every return to a section already visited. The rows are now compared before they are published, and the same answer as last time is dropped. The favourite id sets get the same treatment, for the sharper version of the same problem: every cell and every row reads them to draw its heart.
Nothing about how a listing is read has changed. It still arrives whole, so the scrollbar still tells the truth about how long the library is and one flick still reaches the end of it.
A track row no longer copies the whole track list to itself. Each row carries the ids of the list it belongs to, so playing it keeps the rest queued behind it — and that list was rebuilt inside the row's own body, once per row. It is built once per pass now.
Fixed
The room changes colour by fading again, not by cutting. The wash installs a two second dissolve when the record changes, and the drift installs itself by clearing every animation on the same layers first — which took the dissolve with it. The drift is reinstalled from
layout(), which a page switch triggers, so the fade was wiped a frame or two after it started and the new cover snapped in. The drift is removed by name now, and leaves alone what it did not put there.Back moves on the first press. The cursor stepped on the click and left the page to catch up, so pressing Back while a record was still being read cancelled that record — which then never applied and never recorded — and stepped off a page nobody had arrived at. The screen stayed where it was and it took a second press to go anywhere. Where you are now changes beside the page rather than ahead of it.
The transport no longer sits on the lyrics. It floats over the window rather than inside the stage, and it already stepped aside for the sidebar — but not for the lyrics panel, so the last few lines of a song were behind the glass whenever the panel was open. The panel measures itself the way the sidebar does and the bar stops at its edge, tracking it as it is dragged.
Organize no longer offers to move files into nowhere. With no library folder configured the macOS sheet took the empty string as its destination, so every path the pattern produced was relative — and a relative path resolves against whatever directory the process happens to be sitting in, which for an app bundle is
/. The preview was flawless: nothing occupied those destinations, so every file came back as a clean move. Pressing the button then failed on the firstmkdirof every single file, and because a failed move comes back as a failed row rather than a thrown error, and the sheet re-read the library afterwards instead of reading its own result, the table came back identical and the button re-armed. It could be pressed all afternoon.An empty destination is now refused where it is resolved, so the CLI and TUI get the same answer. The sheet says there is no library folder instead of drawing a plan, a move that fails is written to the log with its reason, and a run that fails keeps its own report — every row that did not make it says why, where its destination used to be.
A track no longer leaves its album when its download finishes. A track that streams starts on the partial tags symphonia can read, so when the file lands koan re-reads it properly and fills the queue item in. It filled in tracks that needed nothing — ones that came out of the library and already carried the record's own title. Where a file's tags disagree with the server's, and on a rip they often do, the item quietly changed album halfway down the queue and its record split in two: ten tracks under one heading, the one that had played under another. The file's word now only counts for a queue item with no library row behind it. Its duration still counts for everything, because that is the file's to know.
0.33.0
Changed
Opening a record takes seven milliseconds. Measured end to end in Instruments, from the click to the finished page: the two database reads are 7.4ms, switching the page is 19µs, and the first frame carries the whole record. It was about half a second.
Most of that half-second was the page loading itself twice. The navigator reads a record before it moves to it, and the page then asked again the moment it appeared — the same two queries, but landing while the artwork they had kicked off was still in flight, so the second one took twenty times what the first did and re-rendered a page that was already correct. A record now carries the library version it was read at, which makes asking for what is already on screen free and asking for it after the rows moved a real read.
Opening a record is instant, and nothing draws before it has something to draw. A page used to arrive empty, fetch, and fill in: the word "Album" over an empty list, then a header, then rows, then artwork fading in over a placeholder. Each step was a frame you could see. The record and its tracks are now read before the page is shown, in parallel and as one value, so the first frame is the finished page.
What made that possible was finding where the time actually went. The engine answers in about 300µs — but every
awaitin a view or a view's.taskinherits main-actor isolation, so the answer had to queue for a slot on the main actor before it could be delivered. Behind the state mirror's batch, which lands ten times a second, that was a hundred milliseconds and change, on every read, whatever the record. Off the main actor it comes back in one. The artwork cache was the same mistake at greater scale: it was main-actor bound with eight awaits in its fetch path, so a grid of twenty tiles queued a hundred and sixty jobs there. It is neither main-actor bound nor observable any more, which also lets a view read a cover it already holds duringbody— a record opened from the grid it was showing draws its sleeve in the same frame instead of dissolving one in from a placeholder.The wash behind the window runs on the GPU. Its drift was three
repeatForeverSwiftUI animations onoffsetandscaleEffect— and.offsetis a layout modifier, so animating it meant the attribute graph re-evaluated a window-sized layout pass every display frame, forever. It cost about a tenth of the main thread with nothing happening, and the app was unresponsive for the whole two seconds a record change took to dissolve. The drift, the blur, the saturation and the dissolve areCABasicAnimationandCALayer.filtersnow: committed once, run by the compositor, never touching the main thread again.Blocking file reads and image decoding also came off Swift's cooperative pool, which has one thread per core and was being emptied by a screenful of tiles — the same starvation, one layer down. Both now have lanes of their own, the CPU one bounded.
Artwork is one call per record rather than a listing thrown away. Asking for an album's cover fetched the album's tracks to find an id to ask with — a query built and carried across the boundary for one integer, once per tile. The engine resolves it in SQL now, in the same call that returns the bytes.
The macOS app follows one state stream instead of six events. Every model held its own copy of engine state and refreshed it by a rule someone had to remember to write, wired up by six closures deciding which model heard what. Three bugs in one afternoon were the same shape: an album page kept an empty cloud after a download landed, a playlist page heard nothing at all, and a playlist's progress rings never moved because progress was patched into one index of the queue and not the other. The engine was right every time.
The engine now publishes whole slices — what is playing, where the playhead is, the queue, what the queue still is, the transfers, their figures, and whether the library moved — and the app holds one mirror of them. Views read properties and are invalidated by SwiftUI as normal; a page showing something asked for on demand, like a record's tracks, reloads where it is drawn rather than waiting for a model to remember it exists. A snapshot cannot be applied wrongly, which is what a delta can do and did.
Slices are cut by rate of change rather than by subject, because replacing one invalidates everyone reading it. A transfer's byte count is no longer a field on a queue row and the seekable extent is no longer a field beside a track's title: both moved ten times a second while riding on something that changes when you press a button, so both dragged every reader along with them. Nothing is dropped either — each client keeps a cursor, so falling behind costs the intermediate values of a slice and never the fact that it changed, and a fresh cursor reads the whole state, which is how the app seeds itself with no separate call.
A library task now only greys out the ones it would actually collide with. Any of them running disabled all of them, on the grounds that they queue behind SQLite's single writer — so a twenty-minute sync of a large server locked out rescanning a folder, clearing downloads and the organize sheet along with it. Each task says what it holds instead: the files on disk, the rows for your local tracks, the rows mirrored from the server, the downloaded copies. A sync and a scan write different rows and now run together; a scan and a file move over the same files still do not. Clearing the index waits for everything, because it empties everything.
Every query the library answers now goes through an index.
EXPLAIN QUERY PLANwas run over every statement koan issues, against a 47,944-track library, and each full table read was either fixed or established as a query that genuinely means all of them. The costs were invisible because nothing ever failed — they only grow with the size of somebody's library:Listing an artist's tracks read the whole library. A track counts as theirs by its own credit or its album's, and SQLite cannot use an index for an
ORspanning two tables; askingalbumsin a subquery instead makes both halves indexed lookups. 10 ms → 2 ms for one artist, and the same shape in the API's batched artist load and in radio's artist picker.Listing favourites read the whole library, in the one place koan#363 did not reach — a track is favourited by any of its three paths, and joining on an
ORacross the three cannot use an index. Written as a union, as the id lookup next to it already was: 27 ms → 0.7 ms.A remote sync read every album and every artist once per record it enriched, matching on the server's id, which was not indexed. That is quadratic in the size of the library: 1.6 s of pure scanning for 5,510 albums, 44 ms once indexed. Starring albums and artists from the server was the same lookup and got the same fix.
Radio resolves the artists a recommender names back to local rows, by MusicBrainz id and then by name. Neither could use an index — nothing indexed
mbid, andUNIQUE(name)is case-sensitive while the lookup is not — so every candidate read all 7,138 artists.Forgetting a folder, and the stale-file check every scan runs, matched paths with
LIKE 'folder/%', which no index can serve. Now a range over the indexed path column. It also takes the pattern out of the path:LIKEreads_as "any character" and folds ASCII case, so a folder namedMy_MusicmatchedMy Musictoo.Deleting a track's scan-cache entry, and reading one back during organize, searched by track id where the key is the path. Undo read the whole organize log to find one batch.
The download cache's eviction pass read all 47,944 tracks to find the ten that were downloaded, despite an index on exactly that. koan never ran
ANALYZE, so the planner had no statistics and picked an index that merely supplied theORDER BY. It now runsPRAGMA optimizeon open and after a scan or a sync: 5.3 ms → 0.1 ms, with no query change at all.
One index went the other way:
refresh_tokens(expires_at)was read by nothing and cost every sign-in, so it is dropped.The TUI opens the database once rather than per query. Every read opened its own connection: a
create_dir_all, a permissions syscall, the whole schema DDL and a WAL checkpoint before a single row came back — and while downloads were writing, that checkpoint contended with them. The TUI's reads are user-triggered rather than per-frame so it never cost what it cost the macOS app, but autosave ran one on a timer. It shares the pool the app uses, which now applies the schema itself so a first run on a fresh machine works the same way.
Fixed
A large Opus file plays while it downloads again. koan#375 taught a partial file to answer "where does this end?" with what had arrived rather than with the length the server advertised, which is what FLAC needs — it bisects between its first frame and the end it is given, and an end it cannot reach sends every probe into bytes that are not on disk.
Ogg needs the opposite. It takes the end it is handed as the end of the stream, so told the file stops at the write head it reported a track that was already over: nought milliseconds, and the decode thread reached the end of it in a second and moved on to the next, over and over. A large Opus download never played at all. The answer now depends on the container — Ogg, Opus, Speex and Ogg-FLAC keep the whole file's end, everything else keeps what has arrived. Neither can seek mid-download; for Ogg this is the difference between playing and not.
Reaching for a position in a track that has not arrived says so. A track whose container cannot state a duration until the last of its bytes lands — Ogg — is reachable nowhere at all while it downloads, and every seek into one was sent unclamped and taken as a seek to zero, so the arrow keys threw playback back to the start. The TUI now says how far the transfer has got instead of moving.
Clicking the TUI's seek bar lands where it was aimed on a track still downloading. The click was mapped against the duration the container reported, which on a partial file reads short, while the bar was drawn against the one the library knows. Both use the library's now.
0.32.0
Added
A Downloads section, and a store behind it. What koan is fetching had no home: it could only be inferred from the queue, which knows about transfers for tracks that are in it and forgets each one the moment it lands — which is when you want to see that it did. There is one account of it now, kept by the downloader itself, and every surface reads it.
The page lists what is arriving with its rate, how much of how much, and where each row came from. A transfer that has stopped moving says so rather than sitting at a figure that looks like progress, which is the first thing worth knowing when something will not play.
Where a track's bytes are, wherever a track is listed. One mark, in one column, meaning the same thing in the queue as in a record: an empty cloud for something on the server, a ring filling as it arrives, a solid cloud once it is here. The queue drew a ring while a track was fetching and nothing at all afterwards — the one list where you watch a download happen was the one that could not say it had.
Fetching and removing downloads, wholesale or a track at a time. Library → Clear Downloaded Files throws away everything cached from the server. Right-clicking offers whichever of the two applies: a track already downloaded can be removed, one that is not can be fetched without queueing it — for going somewhere without a server, mostly. Either way the library rows stay and fetch again on demand.
A graphics level, in Settings -> Appearance. One slider from
PlaintoFull, so koan can be told how much of the machine it may spend on looking like itself.Fullis what it has always done and stays the default.Wash Indicators Chrome Fulldrifts dance glass Reducedheld still dance glass Plainnone held still flat materials The steps are ordered by what they were measured to cost rather than by how much they look like they cost. On an M1 Pro, playing, window frontmost:
Fullis 15-18% of a core,Reducedaround 9%,Plainaround 6%.Reducedis where it is because of what the wash's cost actually is. The blur is rasterised once at 360 points and magnified as a texture, so it is close to free -- what is expensive is the drift: three animations of incommensurate period running forever on scale, rotation and offset, which is the only thing making the wash's composited output differ frame to frame, so the copy mirrored out under the sidebar and toolbar and the glass sampling it are redone for as long as the music runs. Held still, the wash measures the same as no wash at all. The record's colour is free; only the breathing is billed.Below that,
Plainis for machines where drawing a blurred backdrop is dear at all. Most of what it saves overReducedis the playing indicators standing still, which stops a 30fps timeline and the analyser poll behind it. It also swaps the glass chrome for flat materials, which measured about a point of a core on top -- close enough to the noise floor that it is there on the reasoning rather than on the evidence, for GPUs and display sizes unlike this one.The setting lives in macOS defaults (
defaults write cc.blit.koan graphics -int 0) rather thanconfig.toml: how much this app draws is this machine's business, and the TUI has none of it to draw.
Changed
What koan is downloading is kept in one place. Whether a track was arriving was recorded twice — once against the queue entry and once by the downloader — and the two had to be told separately, so they could and did disagree: a queue entry pointed at the file a transfer had just been renamed away from, and anything the TUI fetched was invisible to everything else. A queue entry now says only whether its own file can be played, and whether bytes are arriving is asked of the downloader.
A download in progress is played from disk rather than copied into memory. The decoder used to read from a growing in-memory copy that a second thread filled from the file: a 451 MB recording cost 451 MB of RAM for as long as it played. It reads the file directly now, which costs nothing, seeks backwards for free, and carries on across the rename that ends a download.
The macOS app queries the library instead of copying it. It used to load every album and every artist at launch, narrow those copies in Swift and index them so search could resolve ids against them -- three shapes of the same five thousand rows, held to serve views that read none of them directly. Now a section asks the engine what it should be showing and shows exactly that; narrowing and sorting happen in SQL.
Nothing is paged. This is an in-process call rather than a wire, so a listing arrives whole: the scrollbar tells the truth about how long the library is, and one flick reaches the end of it.
The bugs this closes are the ones that came from the copy existing: a section showing a library the database no longer has, and a cold launch showing an empty one because the load lived somewhere the second window never reached. There is no load to have forgotten to do.
AlbumSort::Randomnow takes a seed, so narrowing a shuffled listing narrows the shuffle you are looking at instead of dealing a new one on every keystroke. A new seed is a new shuffle, which is what the reshuffle button asks for.The engine says when the library changed. A new
LibraryChangedevent rides the same channel asQueueChangedandDownloadsChanged, raised by anything that writes library rows -- scan, sync, import, organize, forget, rebuild -- including the automatic sync and the watched-folder scan that nothing was announcing at all. A background scan finishing now reaches the browser the same way one you asked for does, and the app no longer refreshes itself by guessing from whatever it happened to start.koan-corenarrows and orders albums and artists itself.list_albumsandlist_artiststake a search term, an order, a favourites-only flag and an optional limit, replacing the several near-identical queries that answered one shape of the question each. Play history and favourite tracks take a search term too, and fuzzy album and artist search hands back rows rather than ids for a caller to resolve.
Removed
WavPack and Monkey's Audio are no longer indexed. koan could not play either: symphonia has no WavPack reader at all — there is no feature to turn on — and its
apefeature is APE tags, not the codec. Both extensions were scanned all the same, so a library holding them showed rows that listed, searched, sorted, and then refused to play. A format koan cannot open is better left out than claimed.Anything already indexed disappears on the next scan.
Fixed
Long tracks streamed from a server no longer break when the download lands. Playback of a track that started mid-download held on to the name of the temporary file it started from. Finishing a download renames that file, so from then on the track named nothing: the next seek failed to open it and stopped playback outright. A nine-hour recording made it easy to hit, because there was a lot of track left to seek in.
Seeking a track that is still downloading stays in the stream. It used to reopen the partial file as an ordinary file, decoding whatever bytes happened to be on disk and ending the track early. Seeking now stays inside the download and lands anywhere already fetched, forwards or back.
The seek bar shows how far a track can actually be reached, and stops there. The limit was derived from the download's own byte count and quietly did nothing when a server sent no
Content-Length, or when under five seconds had arrived — so a scrub could land somewhere the track had not got to. koan works it out once now, from bytes where a length is known and from the measured bitrate where it is not, and the bar draws the same figure the engine enforces.A large track no longer holds the player deaf while it opens. Reading a container to find out what it is happened on the thread that answers play, pause and seek. Ogg states its duration in its last page, so opening one mid-download waited for the entire remaining transfer first — twenty-two seconds of an unresponsive player, on a fast connection. That reading now happens on its own thread and comes back as a message like anything else.
A long Opus starts playing straight away rather than waiting for the whole download. It used to wait because of that last page. koan now opens a partial file without stating a length, which is what stops a container going looking for its tail — and is how every format opens mid-download, not only Ogg, because stating a length also sends the reader looking for metadata at the end of a file that is not all there. The track starts in milliseconds and plays. What each format gives up is whatever only its tail could tell it: for Ogg that is the duration, and with it seeking, until the transfer lands. Ones that describe their frames from the front — FLAC, MP3, MP4 — stay seekable throughout, as far into the track as the bytes reach.
The transport says which of the two it is rather than leaving you to find out: the bar fills as the file arrives, the playhead moves against the duration the library knows, and reaching for a position it cannot reach yet gets an answer instead of silence.
When the transfer lands, seeking comes back on its own. Playback is not interrupted to do it — the decoder is reading a file, and a file being renamed underneath an open descriptor is not something it notices. The finished file is picked up the next time the track is seeked, which is the first moment it matters.
A track whose downloaded copy was thrown away plays again. Clearing downloads deleted the files but left the queue pointing at them and still saying they were ready, so afterwards nothing in the queue would play at all. Anything whose copy has gone is put back to waiting and fetched again.
A track still downloading can be played by asking for it. Double-clicking one opened the path the transfer will be renamed to rather than the one it is writing, and found nothing there — so it waited for the whole download rather than starting. Where a transfer is writing is now part of what says a transfer is running, so there is no longer an order for two threads to get wrong.
The seek bar's downloaded extent moves while the download does. The transport keeps its own copy of what is playing, refreshed when the playback state or the cursor moves — and neither moves during a download, so the mark sat wherever it had been when playback started. It follows the progress it is drawing now.
A finished download's bar does not read as an empty one. The downloads page lit the part that had arrived, so a transfer completing took the highlight away and the bar dropped back to looking untouched. The quiet end is the part still missing, the same way round as the seek bar.
The bar no longer darkens when a download finishes. It lit the downloaded part rather than dimming the part that had not arrived, so completing a transfer took the highlight away and the whole bar dropped a shade. The quiet end is the one that is missing, and a track already on disk looks like the ordinary bar it is.
The playhead is visible on a very long track. A third of a minute into nine hours is a tenth of a percent of the bar — narrower than the bar is thick, and so drawn as nothing at all. It has a head that does not shrink with the fraction.
A download landing shows up on the page you are looking at. A track fetched while its record was on screen kept an empty cloud until you navigated away and back — the page showing the row was not among the things a library change refreshed. A playlist had it twice over: nothing told it a library change had happened at all, and its progress rings never moved, because progress was patched into the queue index keyed by track and not the one keyed by playlist entry, which is the one a playlist row reads.
The cloud and the heart sit in the same order everywhere. The queue and a playlist had them the other way round from a record's own track list.
Playing a track twice before it arrives fetches it once. Downloads were deduplicated by queue entry rather than by track, and playing something again makes a new entry — so nothing matched and a second transfer started over the first. Both wrote the same file, and whichever finished renamed it out from under the other, which is where the failed downloads in the log came from. One transfer now, with every entry waiting on it told when it lands.
FLACs start before their whole file has arrived. A FLAC keeps a padding block after its tags — space reserved so tags can be edited without rewriting the file, and often several hundred kilobytes of it — which puts the first audio frame further in than the point streaming begins looking. koan gave up rather than reading on, so a FLAC played only once fully downloaded while an MP3 started at once.
Finding what is favourited no longer reads the whole library. Matching favourites to tracks joined on three columns at once, which no index can serve, so it read every track to find the hundred that were starred — fifty milliseconds, on every listing that shows a heart, which is all of them. One millisecond now, on a library of forty-eight thousand.
Half-finished downloads are cleaned up. koan writes a download straight through and renames it at the end, so a
.partfile still on disk is from a run that did not finish — bytes nothing knows about, since only finished downloads are tracked for eviction. An interrupted nine-hour recording was half a gigabyte that never came back. They are swept at startup, which is the run after the one that left them.A rate something else changed now reaches the macOS app. koan has watched the device's nominal sample rate since #323 and the watch fires -- the log has been saying so all along. What never moved was the app. The FFI announces a playback change only when its snapshot differs from the last one, and that comparison was a signature of named fields: playback state, cursor, and, since #359, how far the download had got. The output rate is none of them, so retuning the interface under a playing track left the badge claiming the rate the device held when the track started, until the next track happened to move the cursor.
The snapshot is compared whole now, with the position held out because it has an event of its own. A signature has to be remembered to be widened, and had already been widened twice. The same omission was swallowing a stream's duration correction, which lands after playback starts and moves nothing else.
A playlist's tile asked for its covers by track, so the placeholder never got caught. Artwork is stored and cached per record, and the mosaic named a track off each album instead of the album. Every piece was a second fetch of a sleeve the grid already had, under a key of its own, held twice in memory and twice on disk -- and it sat outside the check that recognises Navidrome's stock blue vinyl, which only ever learns from album lookups. A playlist of records with no artwork drew four vinyls where the library drew four ensōs. It asks for albums now.
The wash's drift is far enough to see. It has moved by the same amounts since it landed in #330, and those amounts were too small to register: blurred at 14 points and magnified about five times, the wash has no feature on screen narrower than eighty points, and the drift carried it about one and a half of those over twenty-three seconds. Slow movement that small does not read as movement -- it reads as a still image. The thing was running, and costing six to nine percent of a core to run, and there was nothing to see.
The excursions now reach about four of those instead: 12% of the window sideways against 4%, 10% down against 6%, and the scale swinging 1.38 to 1.58 rather than 1.19 to 1.31. The periods are untouched at 13, 19 and 23 seconds, so it is exactly as unhurried as it was -- it simply arrives somewhere.
The wider scale is not decoration. It is the floor that keeps the texture's own edge out of frame once the offset carries it 12% of the window sideways and the rotation eats another three and a half percent. The scale is also taken off the longer edge of the window now rather than its width: the texture is square, so on a window taller than it is wide the width alone never covered it.
The wash honours Reduce Motion. It never did. The playing indicators already went still when the system asked for less motion and the room behind them kept breathing.
0.31.2
Added
The app says so when it has a server configured and no password for it. Nothing did. The queue filled with tracks that never loaded, every sleeve came back empty and no download started — which reads as a broken library rather than as being signed out, and sends you looking in the wrong place for it. A toast at launch now names the server and points at Settings, which is where the one thing that fixes it lives.
A button that puts the queue back on the row that is playing. Beside the layout picker, since both are about what you are looking at rather than what is in the queue. The row is centred rather than dropped at the top edge — what is playing is read against what comes after it. It runs the same path
gandGdo, and is disabled rather than hidden when nothing is playing.
Changed
Credentials moved out of the OS keychain and into
config.local.toml. Anyone signed in to a remote server will have to sign in once more.A keychain item's ACL is keyed on the code signature of the binary reading it, and koan has no stable signing identity — ad-hoc signing derives that identity from the binary's own hash, so every release was a different application to macOS. No grant ever matched twice, "Always Allow" was a promise about a binary that was about to stop existing, and the login-password dialog came back on the first launch after every update. The apps that never ask are not doing anything clever: they are Developer ID signed, so their identity survives an update and the ACL keeps matching.
What the dialog was guarding does not justify it. Subsonic authenticates every request with the password or a salted MD5 of it, so a client has to keep something password-equivalent indefinitely — there is no token to exchange it for, and Navidrome offers no OAuth. The secret now sits in
config.local.toml, gitignored and created0600, beside the URL and username it belongs to. That is the bargain~/.netrc,~/.aws/credentialsandgh'shosts.ymlall make, and it costs a keychain that could never be made to hold.The remote password, the Subsonic API secret and the refresh token from
koan auth loginall move.koan auth loginwrites a new[auth]section naming the server it signed in to. Thekeyringdependency andKOAN_NO_KEYCHAINare gone, along with the test-suite opt-out that only existed because unsigned test binaries could never match an ACL either.
Removed
The macOS app is Apple silicon only. It shipped as a universal binary, and the Intel slice was over half the release build: two cross compilations of the engine, lipo'd together, then a universal Swift build on top. That is a long time and a lot of a runner's disk — enough that the v0.31.1 release ran out of it partway through writing the disk image — to serve machines whose newest supported macOS is the app's minimum.
koan itself is unchanged on Intel:
koanthe terminal player still builds and ships forx86_64-apple-darwin, and an Intel Mac that wants koan can run that. It is the SwiftUI app, and only the app, that now needs Apple silicon.
Fixed
- The queue comes back to where you left it. A trip to an album and back dropped you at the top of it again. The stage builds one page at a time, so leaving the queue destroyed it — and a macOS
Listcannot be put back: its scroll position belongs to AppKit's table, and every SwiftUI way of asking for one (scrollPosition,scrollTo(y:),scrollPosition(id:)) is quietly inert on it. The queue is no longer torn down. It stays where it is, behind whatever you navigated to: invisible, untouchable, and off stage, which is also what stops the bars on the playing row dancing to an analyser nobody can see. The selection you left survives the trip too.
0.31.1
Changed
Every page takes the record's colour, not just the ones about a record. The wash was drawn on the queue, on an album page and on a playlist, and nowhere else — so the albums grid, the artist list, an artist's page, favourites, history and search results were flat grey rooms you passed through on the way back to a coloured one. Each of those pages was opaque precisely to hide the wash the window was already drawing behind it.
They give that ground up. A page about one record still answers with it — an album with its own sleeve, a playlist with the first of its records — and every other page answers with what is playing. The room is coloured by the music wherever you have wandered off to, and only a page that disagrees says otherwise.
The wash and the control tint were two properties computing nearly the same answer, and now they are one: what the room is washed in and what the buttons are tinted with can no longer disagree about which record you are looking at. Nothing new is drawn — there is still exactly one
ArtworkBleed, on the window, which is whatbackgroundExtensionEffectmirrors out under the sidebar and toolbar. The pages simply stop covering it up.Artist chips are a plain fill rather than glass. Glass samples what is behind it and adapts its own luminance to stay legible against it — right for something floating over content, wrong for a chip sitting in it. On a flat page ground every pill sampled the same colour and they all matched; over the wash they each answered to a different part of it, so a row of them read as a scatter of half-transparent ones rather than a set. A fixed fill takes its share of the colour behind it without arguing with it.
0.31.0
Added
Playlists. Named, ordered lists of tracks that outlive the session — the thing the queue could never be, and the thing saved queues were standing in for. They live in the sidebar under their own heading, with a 2×2 mosaic of the first four records in them for a face.
Almost everything the queue does applies: album headings over contiguous runs, multi-select, drag to reorder, ⌫ to remove, drop to add. A playlist opens ungrouped rather than grouped, because a playlist is a sequence someone chose rather than a shelf of records — and that choice is remembered per playlist, on this machine, since no server has anywhere to put it.
Anything playable goes in one: a track, a record, an artist, a selection, the whole queue. Drag onto a playlist's row to append; drag onto the heading to be asked for a name and get a new playlist of what you dropped. Double-click one, or press Play in its header, and it replaces the queue. Playback state is mirrored back onto it the way it is on an album page. There is a Shuffle that reorders the queue and a Shuffle Playlist that reorders the playlist; they are different verbs and they are both there.
They can be exported as extended M3U8. Only tracks with a file on this machine go in — a Subsonic stream URL carries the credentials that authorise it, and a playlist file is something people mail to each other — so the export says how many it had to leave out.
Dropping into a playlist lands where you dropped it, with a line showing where that is. Adding used to mean adding to the end, wherever the pointer was.
Playlists sync with Navidrome, both ways. A playlist made here appears on the server; one made there appears here, contents and order included. Every edit pushes in the background, so nothing waits on the network; a push that never got out leaves the local copy newer, and the next sync notices and sends it. Deleting on either side deletes on the other, because a playlist that comes back after you delete it cannot be deleted at all.
Only what Subsonic itself carries is stored — name, comment, owner, public, and the ordered song list — so the two sides are the same object rather than koan's idea of one. Where a playlist sits in your sidebar, and how you like to look at it, are the exceptions: those are facts about this machine.
Subsonic playlist endpoints serve real playlists.
getPlaylists,getPlaylist,createPlaylistanddeletePlaylistused to fake playlists out of saved queues; they now read and write the real thing, andupdatePlaylist— add and remove members by index — works at last.The playing indicator moves to the music. The three bars beside the current row rode a pair of sine waves, which said "playing" truthfully but said it the same way through a drum break and a held piano chord. They now follow the analyser: low, mid and high, one band per bar.
The audio modulates the waves rather than driving them. A band never reaches a height directly — only how far its bar is already travelling — so a chorus makes the bars swell and a quiet passage settles them low and slow, and no transient can make them spike. They never come fully to rest while the transport runs, because the first thing the indicator has to say is which row is playing. Each band is judged against its own recent loudest, so a track mastered quiet gets the same indicator as a loud one. A track still buffering, or the first frames after a start, run the plain carrier.
One poller feeds every indicator on screen and stops when there are none, or when nothing is playing. Reduce Motion keeps the still bars.
qgoes to the queue.gandGalready went to its ends; there was no key for simply going there.Escape clears the selection, wherever you are. The queue also grew a Clear button beside Remove — a selection with no visible way out of it is a trap, and on a list you have scrolled away from you cannot even see what you are still holding.
The TUI organize modal honours
[organize] default. The macOS sheet already preselected the pattern it names; the TUI took whichever sorted first.Favourites shows records and artists, not only tracks. koan has always let you favourite an album or an artist — the heart is on both — and the Favourites page only ever listed tracks, so there was nowhere in the app those went. It is one page in three sections now, the way search results are: a section only appears when you have favourited something of that kind, so a tracks-only library reads exactly as it did. The filter narrows all three at once.
The seek bar shows how much of a streaming track has arrived. Playing something off a remote library while it is still downloading, the bar showed a position on a full-width track: whether the rest of it was on the machine, or the transfer was limping and playback was about to stall, was not visible anywhere near the thing that would stall. The fetched extent is now drawn behind the played one, and retires when the track lands.
It is a fraction of bytes on an axis of time — right for lossless and CBR, out by however far the bitrate wanders on VBR — so it is drawn as a distinctly weaker mark than the played extent and the tooltip says "roughly". The question it answers is whether the music is about to run out of track, not where in the track anything is; a hard-edged fill would be read as a promise it cannot keep. The TUI has drawn the same three-way bar all along.
Changed
The queue stays locked to the playlist that filled it. Play a playlist and the queue is that playlist; reorder it, remove from it or add to it and the queue follows, quietly. Rearrange the queue yourself, add to it, or let radio extend it and the two part company — from then on the playlist is a document you are editing and the queue is what you are listening to.
Locked is derived rather than tracked: queue items carry the playlist row they came from, so the queue is locked exactly when its entries are that playlist's, in that order. Nothing to keep in sync, nothing to persist, and it cannot get stuck — a queue that stops matching stops being locked, and one that matches again is locked again. Playing a playlist shuffled scrambles the order on purpose, so that queue is not locked, which is the right answer rather than a special case.
Records lock too, and need no provenance to do it: an album is an ordered set of tracks, so the queue being that album is a question about what the queue holds — which means it still answers for a queue restored from a previous session, where nothing remembers what was played. A record cannot be edited, so there is nothing to follow; it just says what you are listening to.
The queue says so: while it is locked it is headed Playing
, with the playlist's mosaic or the record's sleeve beside it, and goes back to plain Queue the moment it is not. A rule this quiet has to be visible, or the first silent update reads as koan moving things on its own. The shortcuts sheet says what the menus say. It listed the single-key shortcuts and then told you the rest were "in the menus", which is true and no help — nobody opens six menus to find out that Back is ⌘[. The ⌘ shortcuts are now a second table on the same sheet, and both halves are generated from the same declarations the menu bar is built from, so they cannot drift.
Leaving the queue and coming back keeps your place. The stage is one
switch, so every move destroys the page it left and takes its scroll position with it. The queue remembers where it was.Playing something no longer throws you at the queue. Every play button replaced the queue and then moved you to it, which is backwards: the queue runs behind whatever you are doing and is somewhere you go, not somewhere you are sent. Play a track from a record, a row in favourites, a selection in history, an album from the picker — you stay where you were and the music changes.
Two places still move you, because staying put would show you nothing. An artist page is a wall of covers with no tracks on it, so its play and shuffle buttons go to the queue. And a click on an album's cover art opens the record it just started, since that is where its tracks are.
The database schema is now version 2, and older koan builds will refuse to open it. That is the point of the version: a build that does not know about
playlistsmust not write to a library that has them. Upgrade rather than downgrading.Settings are routed to the file they belong in.
config.tomlis meant to be shareable, so three kinds of setting never land there: secrets, anything naming this machine's paths, hardware or account, and volatile UI state a keypress flips —playback.art_sizeand the four visualiser toggles that have keybinds. Everything else is taste and travels. Three call sites previously disagreed about this: the player wroteoutput_deviceto the shared file, the GraphQL settings mutation wroteart_sizeand the remote account there too, and the FFI wrote everything to the local one.config::layer_ofis now the single answer, andkoan config initbuilds its template from it, so the file it writes and the files koan writes cannot drift.A write clears the same key from the other file.
config.local.tomlwins the merge, so a shared write left shadowed by a local copy silently did nothing. In the other direction it drains machine-scoped keys out ofconfig.toml, which cleans up a file an older koan polluted as you use the app.[graphql] subsonic_portis now[subsonic] port. The port for the Subsonic API lived in the GraphQL section, so turning Subsonic on meant a key in each of two sections.[subsonic] enabledmounts/rest/*on the GraphQL port;portadds a dedicated listener.[discovery]is gone. It held one setting koan read and one it did not;analysis_on_scanmoves to[library] analyze_on_scan, where the rest of the scan options are.The menus have their icons back. Every action in the app now carries the same symbol wherever it appears: Add to Queue is the same icon on an album page, in the row's context menu and in the menu bar, and the Edit menu — replaced wholesale so ⌘Z can reach koan's own undo stack rather than a text field's — draws its own icons again instead of arriving bare. The symbols are named in one place, which is what stops the three copies of a verb drifting apart.
Removed
Snapshots. They were playlists with a resume position: a whole second feature, a second table, a second sidebar row and a second set of API calls, all to remember one number the server had no idea about. Existing snapshots become playlists on first launch, keeping their names, their track order and the date they were saved; only the position is lost. The Subsonic API already served them as playlists, so its clients see the same names either side of this.
⌘6 is gone with them, and Save as Snapshot… in the queue menu is now Save as Playlist….
The download quality setting. It offered Original, Opus 128 and MP3 320, wrote your choice to
config.toml, carried it over GraphQL and FFI, and was read by nothing — no request has ever asked a server to transcode. Re-encoding a stream is the opposite of what koan is for, so the setting goes rather than gains an implementation.remote.transcode_qualityin an existing config is ignored; the GraphQLConfig.transcodeQualityfield and its input are gone.[radio] use_subsonicand[discovery] acoustic_weightnever did anything. Both were documented as tuning knobs and neither was read: the acoustic signal's weight was a constant in the scoring function, and nothing consulteduse_subsonicbefore deciding whether to ask a server — see below for what radio actually does. Removed rather than wired up — the defaults are the behaviour everyone has been getting.[playback] ticker_fps. The transport ticker scrolls at a fixed 8 characters per second.
Unknown keys are ignored rather than rejected, so a stale config still loads. Two renames change behaviour silently and are worth grepping your config for: [graphql] subsonic_port (now [subsonic] port) and [discovery] analysis_on_scan (now [library] analyze_on_scan). The others were inert.
Fixed
The playing mark crowded the sleeve beside it. Six points pairs a status mark with a right-aligned track number, which carries slack of its own; a cover is a solid block flush to its frame and the same six points read as a squeeze. A list that draws sleeves gives the mark the same ten points the title gets on the other side.
The queue got slower the more of it you had played. A played row was the whole row at 45% alpha, and any alpha below 1 makes SwiftUI flatten that row into an offscreen layer before compositing it — its children overlap, so they cannot each be drawn at 45% and still look like one row. A long tail of played tracks behind the cursor was a long list of offscreen passes, on every frame the list drew. Played rows now step back in colour instead: a rung down the hierarchical styles, which costs a colour lookup. Only the sleeve still uses alpha, because no colour can dim an image — and one 34pt image is not a flattened row.
Most of the ways koan syncs never touched playlists, and koan's own auto-sync never touched favourites either. Four callers each knew separately what a sync consists of — the app, the CLI, the GraphQL job and the background auto-sync — so a star or a playlist made on the server arrived only if you happened to press the right button. There is one
sync_remotenow and all four go through it.The queue quietly dropped repeats. Adding a track already in the queue added nothing, and a playlist holding the same song twice played it once. The batch fetch behind every queue add took each row out of its map as it matched it, so an id asked for twice came back once.
koan wrote your whole configuration to the file you commit. Every setting koan saved itself — a visualiser toggle, the output device, dragging the album art wider — reserialised the entire
Configstruct overconfig.toml. That erased the commented-out referencekoan config initwrites, and filled the file people are told to put in a dotfiles repo with all fifty-odd keys, including[library] foldersset to koan's default music directory and a[remote]block belonging to one machine's account. Writes now go throughConfig::persist, which diffs the mutation and touches only the keys that actually changed.koan config initdeleted the patterns you wrote by hand. It is documented as safe to run on an existing setup, but it regenerated the template from koan's default serialisation — and[organize] defaultand[organize.patterns]are held back byskip_serializing_if, so they never appeared in it and were dropped. It also emitted[organize]twice when carrying values across, which is not valid TOML, and resurrected settings koan had retired. It now re-comments any value that matches the default too, so aconfig.tomlan older koan filled with its own serialisation shrinks back to a template.koan remote loginwrote your password to disk. The macOS sign-in path already stored it in the platform credential store and explicitly cleared any plaintext copy; the CLI wrote it straight intoconfig.local.toml. Both go throughhelpers::set_remote_credentialsnow. koan's own Subsonic secret also read the config field before the keychain, so a stale plaintext copy beat the real secret — the credential store wins in both, and the config field stays what it always was: the fallback for machines without one.[radio] seed_windowwas half honoured. It picked the seed artists, while the acoustic seeder asked for the last five tracks regardless. One window, one answer.The radio documentation described a feature that does not run. The README and the radio guide both led with Subsonic
getSimilarSongs2and a cache of similar-artist relationships as radio's strongest signals. Neither is reached: the auto-queue loop turns the network signals off before it picks, because ListenBrainz and MusicBrainz rate-limit to one request a second per seed artist and all three are synchronous HTTP in front of a track that is needed before the current one ends. What radio actually scores is genre and era, same-artist, acoustic similarity over bliss-audio vectors, and a low-scored random tail — all database reads.The code is unchanged; the docs now say what it does, and the guide says why the network signals are switched off and what would have to happen to switch them back on. Two things follow from the same gap and are now written down: nothing writes the
similar_artistscache, sosimilarArtistsover GraphQL and FFI andgetSimilarSongs2on koan's own Subsonic API return empty; and radio behaving identically offline is not graceful degradation, because there is no online path to degrade from.koan scan --analyzeis the one thing that meaningfully improves radio, so the docs now say that instead of burying it fifth in a list.remote.transcode_qualitywas still documented after being removed. It survived in the remote-servers guide — with a table of quality tiers and a note that "Navidrome and most Subsonic servers handle this natively" — and in the configuration reference. The setting was never wired to anything and is gone; so is the section describing it.Documented settings that were not true.
bass_shakedefaults totrue, notfalse.[organize] defaultpreselects a pattern in the organize UI, not "the TUI modal" it had no effect on. The format-string reference showed akoan organize --patterncommand that has never existed — organize runs from the TUI and the macOS sheet.koan grew to a gigabyte of artwork and never gave any of it back. Every cover you scrolled past was decoded and held for the life of the process — nothing evicted, so an hour of browsing a remote library reached 978 MB of decoded bitmaps, most of it swapped out rather than released. Covers are now held in a bounded cache that hands memory back under pressure.
Bitmaps are also kept at the size they are drawn rather than the size they arrived. A queue row shows a sleeve at 28 points; it was holding the full 600-pixel image to do it, one per row. Rows and the transport keep a thumbnail, the grid and a record's own page keep a tile, and full size is decoded on demand for the artwork viewer and released with it — which is the only place the detail was ever visible.
The queue raced to fetch the same sleeve once per track. Queue rows asked for artwork by track, so a twelve-track album was twelve HTTP round trips, twelve files on disk and twelve identical bitmaps in memory for one image.
QueueItemnow carries the album it came off — resolved for the whole queue in one query — and every row on a record shares a single fetch.This also closes a hole in the placeholder detection. Navidrome answers with a stock blue vinyl for anything with no artwork, and koan spots it by noticing the same image on three unrelated albums; lookups by track never took part in that vote, so the queue and the transport would draw the placeholder the grid had already learned to hide.
The window wash cost a quarter of a core to sit still. It was drawn twice — once on the window, once on the page on top of it — and the page's copy sat on an opaque ground hiding the window's, which kept animating behind it for no one. There is one now, on the window, which is the one that mirrors out under the sidebar and toolbar.
The one that remains no longer redraws on a timer. It moved its blur through scale, rotation and offset twenty times a second, and each tick invalidated layout: a full window Auto Layout pass, 20 Hz, whether or not anything had changed. The drift is handed to CoreAnimation instead, which runs it off the main thread and smoother for it. Stopping playback now settles the wash back to rest over a couple of seconds rather than freezing it mid-breath.
The same timer cost a third of a core everywhere else it was used. The three bars marking the playing row drove their height from a
TimelineView, and the seek bar sized its played portion and its fetched extent withframe(width:). Height and width are layout, so each of those forty-odd ticks a second marked the window dirty and AppKit answered with a full Auto Layout pass over the whole view tree — a third of a core to move nine points of bar and one line, and it went on doing it while the window was minimised, because aTimelineViewdoes not care whether anyone is looking. Both are drawn in aCanvasnow: same bars, same marks, same motion, on a box whose geometry never changes. Playing with the window minimised went from 28% of a core to 15%.The wash re-blurred the cover on every frame it drifted.
.blurand.saturationsat above the drift in the modifier chain, so SwiftUI recomputed a blurred, saturated copy of the sleeve sixty-odd times a second for as long as anything was playing. The transforms were never the expensive part — re-deriving what they moved was. The blurred wash is rasterised once now and the drift magnifies that; switching the motion off entirely reached 17% of a core, keeping it and rasterising once reaches 13%, from 21–25% before. Nothing about how the wash looks or moves changes.The playing bars ran at twice the rate of the numbers behind them. The indicator's timeline was pinned to 1/60 while the analyser it reads only produces new levels at 1/30, so every other frame redrew data that had not moved. In this window a frame is not free — each one is a SwiftUI graph update, and each of those costs a whole-window Auto Layout pass. Both now read the same constant.
The spectrum analyser ran with nothing reading it.
Player::spawnstarts it unconditionally, so a client with no visualiser on screen still paid for a 2048-point FFT and a fresh waveform allocation sixty times a second and dropped every frame on the floor. It now stands down a second after the last reader of its snapshot goes away, and picks back up within 250 ms of one returning — which is what the playing indicators already ask for and release as they come and go.The filter on the Favourites page did nothing.
LibraryModelnarrowed the list intovisibleFavouritesand the page rendered the unfilteredfavouritesbeside it. Every other filtered section read the right one.Ungrouped queue rows had no room for their covers. Every row carries its own sleeve when the queue is not grouped by album, and the fixed row height around it left the art all but touching the separators above and below. It gets the same six points the album heading already gives its own cover — they are rows in the same list and should breathe alike.
The favourite key flipped the database and nothing else.
fand ⌘D went straight to the engine, but every heart in the app readsLibraryModel.favouriteTrackIds— so the row changed underneath a UI that kept showing the old answer, and pressing the heart afterwards looked like it was undoing a favourite you had just added. Both routes go through the library now, which is what the hearts read.Undoing a queue replace left the player on a track the queue no longer had. The queue came back, which is the part you could see working, but the engine kept decoding whatever the replace had started — an item the restored queue does not contain. The transport then described a row nothing could select, and the decode lookahead finds the next track by locating the current one, so with the current one gone the queue ended at the end of that track rather than carrying on.
Playback is reconciled with the playlist after every undo and redo, not just this one: any undo that takes items away can strand the engine the same way — undoing an add while the added track is playing did it too. If something was playing, the restored cursor picks up where the queue says it was; if it was paused or stopped, the undo stays quiet, because an undo is not a reason to start the music. The position is not part of what a replace snapshots, so the track starts again rather than resuming mid-way.
The format badge latched a rate the device was on its way off. A 48 kHz track followed by a 44.1 kHz one publishes the new track's info before the device has finished reclocking, and a switch is not instant — the better part of a second on USB. A front end polling in that window paired 44.1 with the outgoing 48, and then never let go: the macOS app only republished the format when the codec, source rate or bit depth changed, and none of those move once the rate lands. "FLAC 16/44.1 → 48" could sit there, wrong, for half an hour. The output rate now reads as unknown while the device is between rates, rather than as the last track's.
The format badge could claim bit-perfect while the HAL was resampling. The output rate behind "FLAC 16/44.1 → 48" was read once, when the engine was built, and never again. But the device rate belongs to no one app: Audio MIDI Setup, Focusrite Control, anything else holding the device can move it a second later, and koan then resamples to reach it without noticing — or, the other way round, goes on asserting a match that no longer holds. Since koan does not take hog mode, losing the rate is expected; reporting it wrongly is not. The rate is now watched for as long as the engine lives, and both front ends follow it. The macOS app also had to be told that the output rate is a reason to redraw the badge — it only republished the format when the codec, source rate or bit depth changed, none of which move when another app steals the clock.
Every Opus track started 40 ms late. The bridge between symphonia's demuxer and
opus-decoderdropped its first two packets, on the reasoning that an Ogg stream opens withOpusHeadandOpusTags. Symphonia consumes both intoextra_databefore we ever see a packet — it is where the bridge reads the channel count and pre-skip from — so the two it threw away were music, and Matroska and WebM never carry those headers as packets at all. Header packets are recognised by their magic now, which costs nothing to a reader that strips them and is correct for one that doesn't.A bad Opus packet could take the decode thread down with it.
opus-decoder0.1.1 overflows a shift building CELT's collapse mask on the first packet of some stereo streams: a panic in a debug build, a wrong mask in a release one. It is the only Opus decoder on crates.io that isn't libopus over FFI, and it is unmaintained, so the decode call is contained — that packet is skipped and logged, and playback carries on, which is already how a malformed packet is handled.The README said Opus wasn't supported. It was removed from the format list on the grounds that symphonia ships no Opus decoder. That much is true and always has been, which is why koan has bridged
opus-decodersince v0.20.3.
0.30.2
Added
- A heart on the transport. ⌘D has always favourited what is playing from anywhere, but a heart you can see also tells you whether this one is already in. It sits next to the title, because that is what it acts on.
Changed
The format badge says when the output is being resampled. koan switches the device to the source rate, and when a device refuses — MPEG-2 and MPEG-2.5 MP3 rates routinely are — the system resamples to reach it. The player has always known which of those happened, because
set_device_sample_ratereturns the rate the device settled at, and it compared the two and wrote a line to the log. Nothing else ever saw it. Meanwhile the badge showed the source format either way, captioned "koan matches the device rate rather than resampling" — an unconditional claim that is false in exactly the case worth knowing about.The settled rate now reaches the front ends: the macOS badge appends it —
FLAC 24/96 → 48— the TUI's format line does the same, andnowPlaying.track.outputSampleRatecarries it over GraphQL. What it does not do is claim bit-perfection. koan never takes the device exclusively, so another application's audio can be mixed in and the volume stage may scale in software, and none of that is visible from inside the process. What koan can say for certain is whether it handed the device the samples as they are, or something had to resample to reach it — so that is all it says.
Fixed
Favourites rows lost their covers again. They were given their own sleeve and album name in v0.30.0, on the grounds that a list gathered from the whole library has nothing above it saying what each row is. Rebuilding the detail column in v0.30.1 reproduced the call that draws it without the flag that turns the mode on.
A flash of bare colour on the first keystroke of a search. The page's ground was put behind it before it was told to fill the column, and a background sizes itself to what it backs — so the ground was only ever as big as the page's content. The results page measures nothing while the query is still running, which left the window's wash showing everywhere around it. The page is filled first now, and every page carries an opaque ground of its own with the wash drawn over it rather than through it.
The Now Playing widget had no cover on it. Control Center, the lock screen and the media-key HUD showed the title and the artist against a blank square. Now Playing was only ever handed the artwork if the cover happened to already be in the cache at the instant the track started — and it never is: fetching it is an HTTP round trip on a remote library, and it lands a moment later. By then the guard that stops a 10 Hz poll republishing unchanged metadata saw the same track, the same state and no seek, and returned. The art arriving is now a reason to republish, and Now Playing asks for the cover itself rather than hoping the transport bar's request has landed, so it works with the window closed.
The cached count sat still while an album downloaded. "N of M remote cached" in the sidebar was read once at launch and again after a scan or a sync, and a download is neither — the count moved in the database and nothing told the library to look again. A finished transfer refreshes it now.
Download progress juddered, and everything else slowed down while it ran. Progress was announced by rewriting the queue item's load state after every 64KB — which took the playlist write lock and bumped the queue version, a thousand times a transfer, five transfers at once. Every front end reads that version as "the queue changed", so the macOS app was refetching the whole queue across the FFI ten to twenty times a second for what is a byte counter.
The load state says that a download is running and hands out the counter; the counter is where progress lives, and the download thread writes it without taking a lock at all. It is announced once per attempt. Progress reaches the macOS app as its own event instead of as a queue change, so it moves at 10 Hz without anything being rebuilt — and the last few tracks of an album no longer freeze at whatever fraction they had reached, which is what happened when nothing was left waiting to download and the old nudge stopped firing.
0.30.1
Changed
- ⌘K is the search. It is the search everywhere it exists, and koan's knows albums, artists and tracks. It opened the sheet that builds a queue instead, which is a different job — that keeps its place in the menu and moves to ⇧⌘K.
Fixed
Picking something from the search dropdown landed you on the list instead. Choosing an album sent you to the album grid, an artist to the artist list. The detail column was a
NavigationStackwhose root switched per section, and a stack throws its path away when its root changes under it, then writes the empty path back — so a move that set a section and a destination at once was undone in the update that made it. Search was the only thing that did both, which is why nothing else broke.The stack is gone. koan navigates like a browser and always did: any page reachable from any page, with a linear history and a cursor, which
Navigatoralready owned — Back and Forward moved that cursor, and the stack's own back button was hidden so they could. It was navigating nothing and charging a hierarchy for it. An album is reachable from the queue, from the grid, from an artist and from search, and none of those is its parent. Now there is one page, one list of pages visited, and one cursor into it; the sidebar lights a row when the page is that row, and nothing when you are on a record.Navigating anywhere could take two seconds. Opening an album from the queue and then clicking through to its artist slid the page in as though it were being dragged.
.animation(_:value:)animates every animatable change in the subtree it is attached to, not only the value it names, and it was attached to the whole split view to cross-fade the tint between records — so any navigation that happened to coincide with a new colour was stretched to the length of that cross-fade. The tint is animated where it is set instead, which is the only thing that was ever meant to move.
0.30.0
Added
- The artist and album in the transport bar are links. The bar named what was playing and gave you no way to get to it — its second line was the artist as plain text, and the record it came from was not shown at all. It reads
artist — albumnow, each name going where its own name says, through the sameLinkTextthe rows, grid cells and queue headers use. That was the last place in the app an artist name was not a link.
Changed
The window takes its colour from the record. koan's chrome used to be pink whatever was playing. Now the cover of the record on — or of the album page you opened — is blurred out into a wash across the whole window, under the toolbar, the sidebar and the transport, so every piece of glass in the app sits in that colour. It drifts while something is playing, on three periods that never line up so it never reads as a loop, and settles where it is when you stop. One record dissolves into the next over two seconds; the old cover stays up until the new one is in hand rather than wiping through a placeholder, and a record with no art is no wash rather than a grey one.
The controls follow it. The declared accent becomes a near-black neutral — all it drives is what AppKit draws, list selection and focus rings, and at that weight it stops competing — while the SwiftUI tint is the dominant colour of the sleeve: a saturation-weighted circular mean of hue, clamped to stay legible on dark chrome. An average would not do, because averaging every pixel of a busy cover gives the same brown-grey every time as opposite hues cancel.
It follows the record, not the track: artwork is fetched per track, so re-deriving it would ask the server for another copy of the same sleeve every few minutes. And it is not tied to scroll position — the wash says what is playing, and following the scroll would have it announce whichever record you happened to be looking at.
The macOS app is built out of Liquid Glass. Not a coat of blur over the old chrome — the real macOS 26 material, and the layout changes it asks for. The transport is a slab of glass floating over the stage rather than a bar welded to the window's bottom edge behind a divider: the queue scrolls under it, fading out at the soft scroll edge as it goes, because glass with nothing moving behind it is just a grey rectangle.
It hangs off the window rather than the detail column. A
NavigationStackdrops decoration applied around it the moment it pushes, which took the transport off every album and artist page; each screen now makes its own room for it instead. It stops short of the sidebar, and takes the full width when the sidebar is closed. Play/pause is bigger than the two beside it and no longer goes dead when nothing is queued — it is the control you reach for without looking.The toolbar says what belongs together.
ToolbarSpacerreplaces aSpacersmuggled inside aToolbarItem, so filtering and sorting sit on separate panes of glass instead of sharing one joined capsule with the lyrics toggle. Its background is hidden, so the wash runs behind it rather than stopping in a grey line.Everything laid over artwork is glass now. The codec badge on a sleeve is clear glass rather than a black scrim hiding the corner it sits on; the favourite heart gets a ground of its own instead of a drop shadow fighting whatever is behind it, and grows in on hover. Artist chips, the shortcut sheet's key caps, the picker's commit bar and the error toast follow — the toast tinted rather than bordered, since glass already has an edge.
The transport and the queue show what changed. The playing indicator's rule — motion tells you a state is live, where a glyph only names it — applied to the four places that most needed it. Play/pause morphs between its symbols rather than swapping them. A skip bounces the arrow that was pressed: on a remote library the next track takes a moment to load, and until it does nothing else on the bar has moved, so the press reads as dropped and gets repeated. The transport's title and artist cross-fade on a track change, which gapless playback otherwise leaves unmarked. Cover art fades in rather than cutting, because in the album grid covers land tens of milliseconds apart and the hard cut reads as a stutter of pops.
A downloading queue row said the same thing twice — a static arrow in the status column and a progress bar further along it — so the bar is gone and the arrow is the ring that fills, in the column the eye already reads for state. Reduce Motion drops the bounce; the cross-fades stay, being fades rather than movement.
Favourites rows carry their own cover. A record's tracklist has one sleeve above it and numbers down the side; favourites is a list gathered from the whole library, where the cover and the album name are what tell one row from the next. The shared track list learned the mode history rows already used, so both now look the same and there is one row to change.
Fixed
Favourites and history can be filtered, which they were already built for. Both narrow on title, artist and album, history has an empty state for when a filter matches nothing, and neither could be typed into: the toolbar offered its field to albums and artists by name, and ⌘F named the same two. Which sections have a filter is now one answer on
Navigator.Sectionthat the field and ⌘F both read, so a section cannot be filterable in the model and not on screen. Favourites also draws the narrowed list rather than the whole one, and counts what it is showing.The sidebar said no remote tracks were cached, however many were. The count asked for tracks whose
sourceis'cached'— a value the schema allows and nothing writes, because downloading a track does not change where it came from. What a download writes iscached_path, which is whatset_cached_pathsets and clearing the cache nulls. Counted from there it agrees with the files on disk.
0.29.1
Changed
- The playing row is marked by bars rather than a speaker. A speaker glyph says "sound comes out of here", which is true of the whole application; what a row needs to say is this one, and it is still moving. Three bars ride a pair of sine waves whose frequencies sit at an irrational ratio, so the pattern never settles into a loop the eye can catch, and they freeze where they stand when the transport pauses — paused is the absence of motion, so it costs no second glyph. Reduce Motion gets the bars at rest.
0.29.0
Added
The queue groups by album or gives every track its own row, and remembers which you chose. Grouped is what it was: a heading per contiguous run of a record, tracks underneath carrying a number. Ungrouped drops the headings and gives each row its own sleeve and its full attribution, because there is no heading above it to say what record it is. Each suits a different queue — an album listen wants the headings, a long shuffled queue wants every row to identify itself — so it is a toggle in the queue bar rather than a decision made for you, and it persists.
Both modes are shown with the active one lit, the way Finder switches view. One icon would have had to choose between naming the mode you are in and the mode you would get, and whichever it named, the other reading is available and wrong.
Changed
Scanning stops reading the cover art it throws away.
ParseOptions::read_cover_art(false)tells lofty not to decode a picture frame, not to skip it: holding nothing but aRead, it streams the frame intoio::sink(). Embedded art is around 95% of the average ID3v2 tag, so a 48,000-file library spent 4.1 GiB of every scan pulling JPEGs off the disk to drop them on the floor. koan now walks the frame headers itself and hands lofty a reader that answers with zeros over the picture frames and the trailing padding — both of which lofty is contractually discarding — so those bytes never leave the disk. Over 4,000 real MP3s that is 865 MB unread, 216 KiB a file, with every tag and audio property parsing byte-for-byte as before. There is a per-file floor that bytes don't touch, so expect a scan to shorten by something nearer a fifth than a third. A tag the walk cannot mirror lofty over — unsynchronised v2.2/v2.3, an extended header, a frame ID that isn't one — is read the old way.The macOS app drops the AppKit workarounds its old deployment target needed. The floor is macOS 26, so: the hand cursor over a link is
.pointerStyle(.link)rather than pushing and poppingNSCursor— which leaked a cursor off the stack whenever a hovered row scrolled away; the artwork sheet sizes itself from a windowRootViewmeasures with.onGeometryChangerather than anNSViewRepresentablereaching forsheetParentand setting state from inside layout; Add Folder is.fileImporterrather thanNSOpenPanel.runModal()spinning a nested run loop under the main actor; and the organize window no longer stamps its ownNSWindow.identifier, because SwiftUI now puts the scene id there itself.The single-key shortcuts ask for the main window by that scene id instead of naming the windows they must ignore, so a new window scene is no longer a bug waiting for someone to add it to the list. Six files stop importing AppKit; the seven that still do — the key monitor, the responder-chain edit commands, the pasteboard,
NSSearchField, and Now Playing artwork — have no SwiftUI equivalent.The queue's album headings carry the record, not a label. The cover was 22pt — too small to recognise a sleeve by — and the heading read as one run-on line of artist, album and year. Art is 52pt, and the text is the album, its artist, then year · track count · running time · codec, so a run in the queue says what it is without counting rows. The codec only shows when the whole run shares one.
Fixed
Everything but the TUI downloaded one track at a time.
remote.download_workersdefaults to 5 and the macOS settings pane offers it, but the code path behind it ignored the value: the download queue — a worker pool, a permit-limited priority lane, and a watcher that reorders around the playback cursor — lived in the TUI crate, andkoan-fficannot importkoan-tui. What everything else got instead was a stand-in that spawned one thread per batch and walked it with aforloop. Queue an album from the macOS app and it fetched track after track, in submission order, ignoring where you actually were in the queue.The queue moves to
koan-core, where it should have been — it imported nothing butkoan-corealready. The macOS app, the GraphQL server and radio's auto-extend all reach it through the same helper they already called, so all three now download in parallel and promote what you jump to, and several tracks report progress at once instead of one.A track that can never load no longer parks the queue on itself forever.
play()leaves the cursor on an item that is not yet Ready and waits forTrackReady— and a download that fails never sends one. With the library folder offline and the remote unreadable, every item failed and the player sat stopped on the first one, which is the same picture as a queue still fetching. Failures raiseTrackFailednow, and the cursor walks on to the next item that can still load, or stops cleanly when there is none.The reason a track cannot play reaches the front ends. It was a string inside
LoadState::Failedthat nothing read: the TUI drew!, the macOS app drew a triangle captioned "Couldn't be fetched", and the actual sentence — a locked keychain, a server that would not answer — lived in the log file.QueueEntrycarries it, so the TUI raises it once per distinct reason rather than once per track, the triangle's tooltip says it, and GraphQL clients can readQueueEntry.failureReason.Sharing a track asked the config file whether there was a password. The same mistake
koan remote statushad in v0.27:remote.passwordis empty for every keychain-backed sign-in, so "Remote not configured" was the answer on a perfectly good setup. It goes throughsubsonic_clientand reportsremote_unavailable()like everything else.Clicks that registered and did nothing. Four separate things cleared or replaced the detail column's navigation path — a section switch, the sidebar's selection setter, a history move, and the push itself — and none knew about the others, so a push could be undone by an unrelated update landing in the same pass.
Navigatorowns it now: oneLocationvalue holding the section and the stack pushed on top of it, one history of locations behind it, and a single move that writes both. The sidebar's highlight is stored rather than derived from the stack, so aListwriting its selection back can no longer pop what was just pushed, and the stack's root is a view of its own, so changing section cannot make SwiftUI discard the path against it.Two consequences worth knowing. Back and Forward now restore the whole location, so returning to a section you had pushed into puts you back where you were rather than at its top. And clicking the sidebar row you are already on does nothing — that write is indistinguishable from one SwiftUI makes itself, and honouring it was half the bug. Back, from the toolbar or ⌘[, is the way out of a detail view.
Picking a search suggestion lands in the section the thing lives in. It used to push onto the results page and then empty the field, which left you standing on a root that no longer had anything in it. An album opens under Albums, an artist under Artists, and Back returns to whatever you were doing before you searched.
Correcting a file's tags re-merges it with its remote copy.
upsert_trackmatched by path first, so once a row existed for a file every later scan updated it in place and never reconsidered the cross-source merge. That is wrong exactly when the original tags were bad: a track indexed asGolden Skans (David E Sugar Rwith no track number could not content-match the copy synced from the server, and fixing the tags gave it the right title and a second identical row rather than one. A row matched by path or remote id is now asked the content-match question again against the corrected metadata, and folds its counterpart in if it is there — play history concatenates, lyrics and the embedding fill a gap, favourites follow the path. The album the bad tags invented is dropped with it.A library already holding duplicates from this is repaired by
koan scan --force; a plain scan skips files whose mtime and size have not changed, and it is the re-read that spots the merge.A macOS build made without Xcode had invisible controls. The accent is read from the asset catalog, compiling it needs
actool, and that ships with Xcode proper rather than the command line tools. Without it the colour resolved to nothing and the whole app was tinted with nothing — which does not merely lose the colour: every borderless button and the playing row's title and speaker are drawn in.tint, so they were invisible rather than uncoloured. It falls back to the system accent, which is visible and still visibly not koan's.
0.28.0
Added
- Track results drag and right-click like every other row. The album tiles and artist pills beside them already did both; the track row was a
Button, which claims the press, so it was the one result you could only click. It takes the row behaviour the library lists use — full-width hit area, drag to enqueue — and the context menu the tiles and pills already had. Clicking still goes to the album.
Changed
Filtering the album and artist lists is a query, not a pass over everything the client is holding. The macOS app narrowed its own copy of the library with
localizedCaseInsensitiveContains: on a 5,500-album, 7,000-artist library that is 26ms of main thread per keystroke — and it ran for every section, not the one on screen.find_albumsjoinsfind_artistsin koan-core so every front end narrows the same way, the FFI'salbums()takes asearch, and the GraphQL resolver stops filtering a fully-loaded list in Rust. The app debounces and cancels, so holding a key down is one round trip.Matching is ASCII case-insensitive now, as
find_artistsalready was — SQLite'sNOCASEdoes not fold accented letters, soMÖTLEYno longer findsMötley. A folded search column is the fix and is not here yet.The
LIBRARYcollation folds each name once per thread rather than once per comparison. Building a sort key means an NFD pass and aVecof freshStrings, and a collation is asked about the same name once per level of the sort — around two dozen times in a five-thousand-row list. Sorting an album list built roughly 140,000 keys where 5,500 would do. Every client's lists load faster for it.koan-ffisorts albums withsort_by_cached_key.sort_by_keyrecomputes its key on every comparison, so sorting by title lowercased each one a couple of dozen times over.Album artwork is decoded and downsampled off the main actor.
NSImage(data:)defers the decode until the image is drawn, which put it on the main thread mid-scroll — and embedded artwork is routinely 1500px square for a tile shown at under 200pt. Grid tiles are downsampled to 512px; a cover opened on its own is left alone.The artist list's hover state lives on the row. It was on the browser, so every pointer move across the list invalidated all of it. The album and artist detail views also scanned the whole catalogue to find the record they were already showing; there is an index for that.
Engine events are an async sequence rather than a callback interface.
PlayerEventswas a trait the client implemented and registered; it is nownext_event(), awaited in a loop, andPlayerEventcarries what changed. The loop is the subscription, so its lifetime is the client's task and there is nothing to register or unregister.The macOS app loses the object that existed only to bridge the two worlds — a callback has to be
Sendablewhile the model is main-actor isolated, so every one of its three methods did nothing but hop back withTask { @MainActor }. It also loses an FFI round trip per event: the change already carries the new state, and the app was re-fetching it.A client that falls behind now drops the events it missed instead of delaying the engine. Every variant carries an absolute value — a snapshot, a version, a position — so the one that does arrive is complete on its own.
Drag sources outside list rows went through
.onDrag. It claims the press outright, which costs the tap underneath it —RowBehaviourhad already found this and moved list rows to.draggable, whose recogniser has a movement threshold and leaves a press that never moves as a click. Album tiles, artist pills and artist names were still on the old path.PlayableTransferisTransferablewith the two representations the item provider was registering by hand, so drops inside koan and the plain-text fallback out of it are unchanged.
Fixed
justran everything with the credential store switched off.export KOAN_NO_KEYCHAIN := "1"sat directly abovecheck:, reading as though it belonged to it — but a top-levelexportin a justfile reaches every recipe, sojust macos-runlaunched the app with no keychain. With no password there is no server, and koan degraded three ways at once: nothing played, no downloads started, and every record came back with no artwork, which reads as an empty library rather than as being signed out. It is set per-recipe now, on the two that run unsigned test binaries.A client that cannot reach its server says so.
remote_unavailable()has produced the right sentence since v0.27 and was called in exactly one place — awarn:in the download queue that only a log reader would ever see.KoanEngine::remote_problem()asks the question directly, the macOS app asks at startup and reports through the error toast it already had, andcover_artreturns an error when the server is configured but unusable instead of answering "no art" for every record in the library.A failed artwork fetch is no longer remembered as "this record has no art". The cache could not tell a server that said no from one that could not be reached, so a blip during a scroll left permanent holes until relaunch. Only a definite answer is recorded now.
Dragging an artist's name in the artists list dragged nothing. The name was a
Button, and a button consumes the press a drag starts from — so the row queued when dragged and the link on it, standing for the same artist, did not. The app now has one kind of link text rather than two, and every name that navigates to something playable is also a drag source for it.The Homebrew cask warned on every
brewcommand.depends_on macos: ">= :tahoe"is a deprecated string comparison; the bare symbol has always meant "that version or newer", so the requirement is unchanged. The workflow that regenerates the cask on release is fixed too, not just the published tap.The foot of the macOS sidebar was cut off by the transport bar. The bar is a
safeAreaInseton the split view, which reserves space in the window but not inside a column's own scroll view. The detail column already compensated; the sidebar never did, so its footer was laid out against a frame whose bottom sits behind the bar — the divider and the first activity row showed, and the progress bar, the cancel button and the library counts underneath them did not. During a sync you got a label with nothing to say how far along it was.The sidebar takes the same measured inset the detail column takes, so the footer grows upward from the top of the bar.
Clicking a search result did nothing. Albums, artists and tracks on the results page all registered the click and stayed put; the same tiles and pills worked in the album and artist browsers, which is what made it look like a hit-testing problem rather than a navigation one.
The sidebar's lit row was derived from the detail stack, so that an album opened from anywhere lit Albums. Opening one therefore moved the sidebar selection — and a
Listwrites a moved selection back through its binding. That setter pops to the section root, which is right when you click a sidebar row and wrong when the List is echoing a move the app just made: it threw away the destination that had only just been pushed. The browsers were unaffected because the lit row was already the right one, so nothing moved and nothing echoed.The lit row is now the section being browsed and nothing else. Opening an album from search results keeps Results lit, and Back returns you to them.
Picking from the search dropdown landed on an empty results page instead of what you picked. Choosing a suggestion pushes its album or artist and then empties the field, and both happened in one update: the results page is the stack's root at that moment, so clearing the query changed what that root drew while the destination was still landing, and it was discarded against the root it had been pushed onto. Emptying the field is its own update now, so the push settles first.
0.27.0
Added
KOAN_CONFIG_DIRpoints koan at a different configuration directory, so one machine can run more than one library.config_dir()honours it, andset_config_dir()does the same in-process.The macOS app takes the TUI's single-key shortcuts.
space,</>,,/.,f,R,p,/,l/a,r,g/G,L,zand?do there what they do in the TUI, and Help ▸ Keyboard Shortcuts (?) lists them — generated from the table that implements them, so the two cannot drift.They are handled by a local event monitor rather than declared as menu shortcuts. A modifier-less key equivalent is claimed by the menu bar before the responder chain sees it, which would mean
ffavouriting a track instead of typing an f into the search field. The monitor asks what has focus first: the keys are live in the app and dead in any text field, sheet or the settings window. The cost is type-select in lists, which koan's browsers have a filter field for.Escnow leaves a search or filter field rather than only clearing it, and⌘Ffocuses the filter on the albums and artists pages, the library search everywhere else.File organization in the macOS app. Dropping a folder of files on the queue indexes them into the library where they lie and queues them; Organize Files… in the queue or library context menu then opens a sheet that previews where a pattern puts each one, and moves them when you say so.
The preview is the feature. Every selected file gets a row showing its destination relative to the library folder, including the ones that can't move — a destination already occupied, or two files resolving to the same path, is an orange row next to the path it collided with rather than a number in an error count underneath. Nothing is ever overwritten, so the only way that matters is if you can see it before pressing the button.
Patterns come from
[organize.patterns], shared with the CLI and TUI, and can be edited in place: the preview follows what you type, and saving writes it back toconfig.tomlunder its name. An edited pattern previews and runs without being saved, so trying one out costs nothing. With more than one library folder configured you pick which one to organize into; the CLI's behaviour (the first) is the default.Dropped files get library rows where they are, not in the music tree — importing and organizing are separate on purpose, so files land in the library only after you have seen where they are going.
It opens in a window rather than a sheet. A sheet cannot be resized — AppKit leaves the style mask off and SwiftUI pins its content size — and a table of file paths is exactly the thing you want to make wider. A window also leaves the library visible behind it, which suits a preview you are checking against rather than a prompt you are answering.
Whether cover art and cue sheets travel with the music is a checkbox in the sheet and a
[organize] move_ancillarysetting behind it, so the CLI and TUI organize the way the app just did.Generating destinations is separated from asking the disk about them, because only one of those is fast.
organize::generateformats a pattern against an already-resolved selection and touches no files at all, so it reruns on every keystroke;organize::check_against_diskis thestat-per-file pass that finds occupied destinations and the artwork travelling alongside, and it lands a moment later. Ancillary files were previously discovered with a directory read per file, so an album of a dozen tracks did the samereaddira dozen times.
Changed
The macOS app requires macOS 26. It was built against 14. Nothing in the app is holding the old floor up and the newer SwiftUI is worth having —
searchFocused, which is what lets/put the caret in the search field, is 15-and-later on its own. The Homebrew cask requires Tahoe to match.organizePreviewandorganizeExecuteboth returnOrganizePlan(wasOrganizePreview/OrganizeResult), an ordered list of per-file entries carryingoutcome(MOVE/UNCHANGED/CONFLICT/ERROR), the destination, and the reason where there is one. Breaking for GraphQL clients:moves,errorsandskippedare gone. A conflict previously arrived as a string inerrorswith the destination buried in the message, which is unusable for the thing a client most needs to render — a file about to be blocked, next to what is blocking it. The TUI's preview gains the same rows.The FFI never blocks its caller. Every one of the 80 exported calls that can block is
asyncnow and runs on a worker thread; the six that stay synchronous read a single atomic or an O(1) length and cannot block by construction. Previously all of them were synchronous FFI functions and the hazard lived in doc comments, which had already failed —lyrics()was documented as safe to call from a view body and opened a database connection, and six paths in the macOS app reached the engine directly on the main actor, one of them from inside a SwiftUIForEach.Blocking moved into Rust rather than being wrapped at each call site. The app used to hop with
Task.detached, which runs on Swift's cooperative pool — sized to the core count — so a cover-art storm or a scan starved every other task in the process. The engine's pool grows on demand and is deliberately not core-sized: a thread waiting on a socket costs a kernel stack, not CPU, and capping blocking work at the core count queues it behind nothing. koan-core stays synchronous, which is what its three synchronous consumers and its dedicated audio threads want; only the boundary changed.Queue mutations and transport commands share one lane, in submission order. They previously each got their own
Task.detached, so two in quick succession could reach the player in either order — dropping in an album and pressing undo could undo it before it landed.Every
Task.detachedaround an engine call is gone from the app, along with the helper that wrapped them.Nothing played when the library drive was offline, and nothing said why. The log read
remote not configuredwhile the remote was configured perfectly well — what koan could not do was read the password, because macOS grants keychain access per binary and the app had never been granted it.subsonic_clientreturns nothing for four different reasons and every caller reported the same one, so "koan has no password" and "koan cannot read the password it has" printed identically, despite sending you to completely different places.Tracks that cannot be fetched are marked failed with the reason now, instead of sitting as pending forever. The player waits for a track to become ready, so a download that was skipped left the queue silent until it ran off the end.
koan remote statusasks the way koan asks. It read the config field directly and never consulted the credential store, so it reportedpassword: not setfor every keychain-backed sign-in — the arrangementkoan remote logincreates — and then skipped its own connectivity check because of that same flag. The one tool that should have diagnosed this was reporting the opposite of the truth.
Fixed
The test suite read the developer's own configuration, and asked for their keychain password.
Config::load()resolves its directory from$HOME, so tests inherited whatever library folders and remote server belonged to whoever ran them. A koan-tui rendering test spawned the download queue, which resolved the configured server and reached for the credentials to reach it with — and macOS put up a dialog asking for the login keychain password. The suite then blocked on it: koan-server's tests took 25.52s waiting, and 0.10s when the keychain was disabled.Nothing was hardcoded; that is what made it easy to miss. The tests were simply configured as the person running them, and CI never noticed because a runner has no
~/.config/koan/to inherit. On a developer's machine the same code path would have gone on to fetch tracks from their server.Tests point the configuration at a disposable directory now, so they read a config nobody has edited. The ones that need a remote build their own rather than borrowing one.
Menu shortcuts no longer reach past a field you are typing in. ⌘← and ⌥← skipped tracks instead of moving the caret or the word, and ⌘Z undid a queue edit instead of the typing — in the search field, a filter, Settings, anywhere. Every shortcut whose key also means something while typing is now disabled while a field has focus, which releases its key equivalent to the responder chain; declining the action instead would leave the menu swallowing the key, so the shortcut would stop working without the field ever hearing it. The bare-key shortcuts already asked what had focus; the modified ones never did.
The sync fetched 1,725 artists and threw the list away.
get_artistswas called, counted, logged as "syncing 1725 artists" and then dropped — artists only ever came into being as a side effect of a track upsert, which saw nothing but a name and an id. That is why not one artist in a synced library had a MusicBrainz id or a sort name, and why the reported artist count was theatre. The list is applied now, and the count is what was actually written.Album and track metadata the server had already sent was discarded. An album row is reached through a track, so it only ever saw what a file's tags said; track totals, the record label and the MusicBrainz id are properties of the release and came back in the same
getAlbumList2response the sync already pages through.songCountwas even parsed intoSubsonicAlbum, covered by a test, and stored nowhere. Albums and tracks gainmbid, albums gainsort_name, andtotal_tracksandlabelare filled — all from responses koan was already making, at no extra request. Enrichment fills blanks rather than overwriting, so a locally-scanned album keeps what its tags said.Remote tracks carried no quality figures at all. Navidrome and any other OpenSubsonic server report
samplingRate,bitDepthandchannelCounton every song; koan's client did not parse them and the sync hardcoded all three to null. Every remote-only track in a synced library therefore had no sample rate and no bit depth — 5,058 of 5,058 in the library this was found on — so the format badge had nothing to show for them. For a player whose point is bit-perfect output, that is the wrong field to be missing. A full sync fills them in; a plain Subsonic server that does not report them still leaves them absent, because a missing sample rate is not 0 Hz.A fresh HTTP client, and a fresh TLS handshake, for every remote request.
subsonic_client()built a newSubsonicClienton each call, and each of those builds two blockingreqwestclients — two runtimes on two threads with two cold connection pools. Browsing a synced library paid that per album cover. The download queue had already worked this out and kept a client of its own for the app's lifetime; the client is now shared process-wide and keyed on the credentials, so every caller gets connection reuse and logging in as someone else still replaces it.Reading the config forked a
gitprocess.Config::load()re-read both TOML files, re-ran the figment merge, and re-scanned for credentials in version control — and that last check shells out togit ls-fileswhenever a password is present in the file, then panics if it is tracked. koan reaches config from paths that run per frame: the macOS settings pane readslibrary_folders()from a SwiftUI list body, so it did all of that per rendered frame. The check is what its own message says it is, a gate on starting, and runs once per process now. The merged config is cached and re-read when either file's mtime moves, so a config edited by hand is still picked up.
0.26.0
Added
Play history. koan never recorded its own plays:
play_historyexisted for the radio feature, and its only production writer was the inbound Subsonic scrobble route — i.e. plays arrived when other clients scrobbled to koan, and playing a track in koan itself wrote nothing.A track is now written to history the moment it starts, not once it has been listened to for long enough. History answers "what did I put on, and in what order"; putting something on and skipping two seconds in is still a thing you did, and a log with a threshold on it is a log with holes in it. How long it was actually heard for is filled in afterwards, from position deltas — so a pause adds nothing and a seek does not credit the stretch it skipped.
The macOS app gains a History section (⌘5) grouped by day. Read-only: rows link through to the album and the artist and carry the usual play/queue menu, but the only thing you can change is the log itself — select and ⌫ to forget entries, the same as queue items.
Plays of tracks that came from a remote server are scrobbled to it.
SubsonicClient::scrobblehad been written and never called.Albums and artists can be favourited, not only tracks. Subsonic stars all three and koan only ever read songs back, so an album starred in Navidrome was invisible here and there was no way to star one from koan at all. There is a heart on an album tile, on an artist row, and in the header of both detail pages, and the context menu favourites the thing you opened it on rather than looping over its tracks — which would have turned off every track that was already a favourite. Favourites are keyed by name rather than row id, so like track favourites they survive a rebuilt index.
A heart on every queue row, on hover, filled when the track is a favourite.
koan can be set up from the app. Settings is four panes — Library, Server, Playback, Radio — covering everything needed to go from a fresh install to playing music without opening a terminal: library folders through a folder picker, signing in to a Subsonic or Navidrome server, transcode quality, cache limit and location, download workers, ReplayGain mode and pre-amp, radio lookahead and discovery. The configuration is still
config.toml, shared with the CLI and the TUI, so this is a view onto that file rather than a second source of truth: fields commit when you finish editing, not on every keystroke, and the window re-reads on focus so a change made elsewhere is not silently overwritten.Remote credentials go to the platform credential store.
set_remote_credentialschecks them against the server before writing anything, stores the password in the keychain, and empties the config copy — so signing in once migrates a setup that had it in plaintext. Shared by the CLI and the app, which cannot now disagree about where credentials live.The library keeps itself current. An incremental scan a few seconds after startup, a rescan when the library folders change, and an incremental sync with the server on a timer. All three are cheap: 48,000 files walk in under a second and everything unchanged is skipped on its mtime and size, so the cost tracks what actually changed. Automatic sync is configurable, and a full sync stays a deliberate choice.
One place that says what koan is busy with. Scans, syncs, library rebuilds and large queue edits each get a row at the foot of the sidebar with a label, how far through as counts rather than only a percentage, a bar, and what it is working on that second. Scans report a real fraction: the file count gives a denominator and a new progress callback carries the numerator across the FFI, throttled so a fifty-thousand-file scan does not cross it fifty thousand times. Only one library task runs at a time — they all queue behind SQLite's single writer — and the ones that cannot start are disabled rather than silently ignored. Each can be cancelled, which stops between transactions and keeps what it had already committed. (#219)
Removing a folder or signing out can forget what it brought. Both ask. A track held both locally and on the server keeps its row and loses only the half you removed, so "remove every folder and sign out" ends at an empty library, which is what it looks like it should do.
just macos-signing-certcreates the self-signed certificate development builds sign with. Ad-hoc signing derives the app's identity from the binary's own hash, so every rebuild is a different application to macOS and keychain grants and TCC permissions are both forgotten. It does nothing for Gatekeeper — that needs Developer ID and notarisation.
Changed
The app is
kōan.appand calls itself kōan in the menu bar and Finder. The executable inside stays ASCII, which is whatpsand crash reports show.Playback position is saved every second, so a crash costs a second rather than the session. The queue is only rewritten when the queue changes: it is stored as a JSON blob, and re-serialising a library-sized one every second to remember a number is not a trade.
Fixed
play_history.track_idwas missing itsON DELETE CASCADE. Underforeign_keys = ONa bareREFERENCESmakes a track with history undeletable unless the caller clears the history first. One caller did; the constraint should not depend on the next one remembering. The table is rebuilt on first open, dropping entries whose track had already gone.A sync never recorded the album's or the artist's id on the server. The track's was kept and theirs was dropped, so all 5,800 albums in a synced library had a null
remote_id. The server keys stars, shares and cover art off those ids, which left koan able to name an album but not refer to it. A full sync backfills them.Favouriting a track from anywhere but the Favourites list appeared to do nothing. The favourite was written and pushed to the server, but every view held its own copy of the track with the state baked in from when it was fetched, and only the Favourites list was reloaded — so the heart on the album page stayed empty on a track that was now a favourite. Removing one appeared to work because that is the one list that was refreshed. Favourite state now lives in one place and the row reflects it on the click rather than a round trip later.
The app never reconciled favourites with the server. That only happened in
koan remote syncon the command line, so a star made on another machine never arrived and one made in the app only left if you happened to run the CLI. It is part of a sync now, both directions, for all three kinds — union rather than mirror, since neither side records an unstar and treating one as authoritative would quietly delete favourites made on the other.Nothing the engine logged was written down when it was hosted by the app. koan-ffi never installed a logger, so every warning in koan-core — a favourite that could not reach the server, a file that would not decode — was discarded. It writes to
~/.config/koan/koan.log, the same file the CLI uses.The sidebar went on pointing at where you started. Reaching an album from Favourites, from search, or from "Go to Album" in the queue left the selection on the section you came from. It follows the detail stack now: an album highlights Albums, an artist highlights Artists, whichever door you came through.
Artwork opens at the size of the window. It was capped at 760pt, which made a 4000px scan no bigger than a thumbnail on a large display; lifting the cap then left it tall and narrow, square cover in the middle of a column of dead space. The sheet is sized from the window it hangs off rather than from its own proposal, which AppKit answers with a tall box.
"Show in Library" in the queue is "Go to Album", which is what it does and what the same action is called everywhere else.
cargo testasked for the login keychain password on every run. A keychain item's ACL is keyed on the reading binary's code signature, and a cargo test binary is unsigned and rebuilt under a fresh hash each compile — so no ACL can match it, and "Always Allow" grants access to a binary that is about to stop existing.KOAN_NO_KEYCHAIN=1opts out andjust checkexports it.The credential store is asked once per process rather than once per client.
subsonic_clientbuilds credentials from scratch and the download queue, radio, sync and sharing each build one, so a single session asked several times over — and being asked five times for one password is indistinguishable from the app being broken.One implementation of pushing a favourite to the server. The TUI, the app and the server each had a byte-identical copy.
0.25.2
Changed
- Direct downloads say how to get past Gatekeeper. The app is signed but not notarised, so macOS refuses the first open of a downloaded copy and offers only "Move to Trash". The
xattr -dr com.apple.quarantineline now leads the release notes and the README's install section; the Homebrew cask already did this in a postflight.
Fixed
- The macOS app is universal again.
swift build --arch arm64 --arch x86_64puts its lipo'd product under.build/apple/Productsand leaves.build/releasepointing at one slice, so the bundle shipped the arm64 slice out of a build that had just compiled x86_64 as well — v0.25.1 does not run on Intel. - A broken bundle can no longer ship.
just macos-verify <arches>asserts the binary contains every architecture asked for and does not linkkoan_ffidynamically, and CI runs it between the build and the DMG. Both bundles that went out broken today built, signed and packaged without complaint. - The Homebrew cask is no longer published with an empty checksum. The shas came from bare
sha256sum <path>calls whose failure went nowhere, so a missing artifact producedsha256 ""— which Homebrew refuses to install — and nothing in the run said so.
0.25.1
Fixed
- The v0.25.0 macOS app could not launch.
-lkoan_ffiover cargo's output directory finds the.dylibnext to the archive and prefers it, so the shipped app referenced/Users/runner/work/koan/koan/target/release/deps/libkoan_ffi.dylib— a path that exists only on the CI runner — and was arm64-only, the host dylib having won over the universal archive.just macos-ffinow stages the right archive in a directory holding nothing else, which cannot produce either outcome. The bundled binary goes from 3.4 MB to 20 MB, which is the engine actually being in it.
0.25.0
Added
A native macOS app (
apps/macos) — SwiftUI on top of koan-core through new uniffi bindings (koan-ffi), not a client of the GraphQL server. The app links the engine in-process, so there is no daemon, no port and no auth surface between the UI and the audio it is driving. GraphQL remains the surface for clients that genuinely cannot link the core.Queue, albums, artists, favourites and snapshots, with album-grouped queue editing, drag and drop, a ⌘K picker, synced lyrics, global search, media keys and Now Playing, output device switching, cover art with a disk cache, and session restore that picks up mid-track — resuming only if playback was running when you quit.
ReplacePlaylist { items, start }— replace the queue and choose where it starts, as one command. Clear-then-add-then-play is three commands down a bounded channel, each acted on as it arrives, so playing track nine of an album audibly started track one first.replaceQueueand the FFI both take the index.Radio survives a restart, and playback state records whether it was running, so reopening resumes rather than always landing paused.
Album and artist counts on artist rows, and
added_aton albums for a recently-added ordering.
Changed
Sorting reads like a person would. SQLite's default collation is a byte comparison, so the artist list ran
Zebrabeforeaphex twinand putÂmeafter the entire alphabet. ALIBRARYcollation folds case and accents onto the base letter and compares digit runs as numbers, soTrack 2precedesTrack 10.Radio no longer touches the network on the path that has to produce a track.
pick_trackscalled ListenBrainz and MusicBrainz in line, and both rate-limit to one request a second per seed artist, so a queue with nothing left to play got its next track long after the music had stopped. It now uses local signals only — genre and era, same-artist, acoustic similarity and random — all database reads. The network signals remain for a background pass that fills the similar-artists cache.Queue mutations are batched everywhere. Removing a selection took the playlist lock and bumped the version per track, and building queue items re-read
config.tomlfor every one. Sharing resolved remote ids one query per track.
Fixed
Subsonic error bodies were cached as audio — Subsonic reports failure with HTTP 200 and a JSON body, so a success status proves nothing on a binary endpoint. Navidrome's
data not foundfor a stale id wrote a few hundred bytes of JSON into the cache, marked the track Ready, and then failed to decode forever — silently, and without ever retrying. Downloads now reject error documents before writing anything, and cache entries too small or too document-shaped to be audio are discarded and re-fetched. Distinct from the truncated-download fix below, which only catches transfers that end early.Favourites were invisible on remote-only libraries —
track_id_by_pathmatchespath,cached_pathorremote_url, but the favourite check compared only the two local paths. A never-cached remote track could therefore be favourited and never show as one, and toggling one failed outright for want of a local path to key on.Reaching the end of a queue crashed the player — the render callback zeroes the tail of the output buffer when the ring runs dry, and passed a byte count to
ptr::write_bytes, which counts in elements of the pointee. It wrote four times the intended range, off the end of the buffer CoreAudio had handed it. Nothing faulted: it corrupted the neighbouring block, and the damage only surfaced when CoreAudio freed it — a trap inside caulk's allocator duringAudioUnitUninitialize, which read as a double free in the teardown rather than an overrun a track earlier. Underrun happens at the end of every track, so the end of a queue is where it landed.ID3v1 tags won over ID3v2, truncating titles to 30 bytes — a regression from the Symphonia 0.6 migration. 0.5 exposed probe-level and container-level metadata separately; 0.6 replaced both with one revision log, and the port walked it taking the first value it found for each field. For an MP3 carrying both tags the first revision is ID3v1, whose fields are a fixed 30 bytes, so
Golden Skans (David E Sugar Remix)was indexed asGolden Skans (David E Sugar R. Only reachable for files lofty cannot parse — but those are exactly the files with damaged tags, and a truncated title matches nothing on a remote server, so the local copy of a record could no longer merge with the server's and appeared twice. Later revisions now win.Scanning decoded every embedded cover image and threw it away —
lofty::read_from_pathparses pictures by default, so a scan pulled a few hundred KB of JPEG out of every ID3v2 tag and FLAC block purely to drop it; a sampled--forcerun spent most of its time inattached_picture_frame::parse. The scan now reads tags and audio properties only. Artwork is unaffected:extract_cover_arthas always done its own read, for the one track that needs it.The Symphonia fallback read only three tags — when lofty cannot parse a file at all, the fallback took title, artist and album and dropped the track number, disc, date and genre Symphonia hands over in the same pass. A row with no track number cannot content-match the same track synced from a remote server, so a file landing on this path stayed a duplicate even once its tags read correctly. It now takes everything offered.
"Recently added" was topped by whenever the last scan ran — locally-scanned albums had no date of their own, so they were stamped with
datetime('now')at insert. Every local album therefore sat permanently above everything the server considered new, in a different date format that wouldn't sort against it either. A local album now dates from the earliest mtime among its files, written as the same ISO 8601 UTC string a Subsonic server uses forcreated, and rescanning keeps the earliest rather than freezing whichever file the first scan reached. Existing scan-time stamps are cleared on upgrade so the next scan refills them; server-supplied dates are untouched.The scan overlaps tag reads with database writes. Chunking reads and writes with a barrier between them left the disk idle for every write and the CPU idle for every read; reads now stream down a bounded channel while the main thread commits.
lofty's 16 MB allocation cap made whole formats unreadable — one record with 4000x4000 cover art in its Vorbis comments exceeded it, so lofty refused every file on it and they fell to the Symphonia fallback: worse metadata, three parses instead of one. Raised to 256 MB.
Share links report why they failed. Every surface collapsed all failures into "local-only tracks can't be shared", including a server that returned no URL for a share it had created. Resolution now lives in koan-core, with distinct errors, one query for the remote ids, and a partial share that says how much it left out.
0.24.0
Breaking
The Subsonic REST API now has its own credentials and is off by default. It previously authenticated with
remote.usernameplus the[remote]password — the user's actual Navidrome account password — and/rest/*was mounted outside the JWT middleware, soauth_enabled = truedid nothing for the surface that streams every file in the library. The protocol sendsmd5(password + salt)with a client-chosen salt over whatever transport the client picked, so one captured/rest/pingon the LAN yielded a digest to crack offline — and cracking it owned the remote music account too.Migration:
koan subsonic setup # generates a 256-bit secret, stores it in the keychain, prints it onceThen re-point your Subsonic clients at the new username (
koanby default) and secret.koan subsonic statusshows the current state,koan subsonic disableturns it back off. Nothing is served at/rest/*until you run setup.Plaintext Subsonic auth (
p=, includingp=enc:...) is refused. Token auth (u+t+s) only. Every current client uses it.updateConfigno longer acceptslibraryFoldersorremoteUrl. Chained withtriggerScanandorganizeExecute,libraryFolderswas a remote move of arbitrary files into the music tree;remoteUrlrepointed sync at an attacker's server. Both stay CLI-only.The
organize*mutations are gated behind[graphql] allow_organize = true(defaultfalse). They physically rename and move files.Existing refresh tokens are invalidated. They are now stored as
sha256(token); rows written under the old scheme no longer match. Clients re-login once.Default CORS no longer allows any origin. With
cors_originsempty the server emits noAccess-Control-Allow-Originat all. List the origins your web client is served from.The MCP
graphqltool executes atuserrole, not admin. It could previously invokeorganizeExecute,organizeUndo,updateConfig,triggerScanandcreateShare— none of which its tool description advertised.KOAN_MCP_ADMIN=1restores admin;setDevice/clearDevice/triggerScanneed it.
Security
h2 unbounded empty DATA frames (RUSTSEC-2026-0258) —
axum::serveruns hyper-util's auto builder, which speaks h2c on a plaintext listener, so anyone able to reach the API port could grow server memory without limit. h2 is now 0.4.18 (patched in 0.4.16).rustls-webpki CRL panic and name-constraint bypasses (RUSTSEC-2026-0104, -0098, -0099, -0049) — a hostile certificate chain from a Subsonic/Navidrome server could panic the sync client, and URI/wildcard name constraints were mis-evaluated. rustls-webpki is now 0.103.15.
Cross-site WebSocket hijacking —
/graphql/wsupgraded with noOrigincheck. WebSocket handshakes are exempt from CORS, so any page the owner visited could open a socket, have the browser attach the session cookie, and run queries and mutations while reading every response. Requests carrying a foreignOriginare now refused before the upgrade; an absentOrigin(non-browser client) still passes.CSRF via a CORS-safelisted content type —
POST /graphqlwithContent-Type: text/plainneeds no preflight, so the browser sent it with cookies attached, and async-graphql parsed the body as JSON regardless. The response was unreadable but the mutation landed.POST /graphqlnow requiresapplication/jsonorapplication/graphql.DNS rebinding — no
Hostwas ever checked, so a page whose DNS flipped to127.0.0.1after loading reached the API as same-origin, at which point CORS, Private Network Access andSameSiteare all irrelevant. Requests are now refused unless theHostislocalhost, a bare IP literal, or listed in[graphql] allowed_hosts.Session cookies were
SameSite=None; Secure—Noneis what made the two attacks above reachable, andSecuremeans browsers refuse to store the cookie over plainhttp://on a LAN address, so cookie auth was silently dead in the deployment the docs recommend. NowSameSite=Lax, withSecureonly when[graphql] cookie_secure = true. The refresh token gets its ownHttpOnlycookie scoped toPath=/auth/refresh./auth/loginwas unauthenticated, unthrottled and outside the concurrency limit — Argon2 at 19MiB per verification meant a few hundred concurrent logins exhausted memory and pegged the CPU, and the handler ran the hash on the async workers, stalling every other request. Now: a concurrency limit of 2 on the auth router, a per-IP rate limit (10/minute), andspawn_blockingaround verification.An empty or truncated keypair silently downgraded to no-auth —
auth_enabled && !private_pem.is_empty()meant a damaged key file made every request an anonymous admin. It is now a startup failure. In TUI mode that failure is logged rather than panicking a background thread, where it left the API silently absent.getCoverArt?size=was unbounded and upscaled —?size=65535on a 1000×1000 cover asked for ~17GB, andVec's allocation failure aborts the process, which no panic handler can intercept. Clamped to 16–2048 and never larger than the source.?token=applied to every route — a valid JWT could sit in any URL, and from there in shell history, proxy logs andReferer. It exists for WebSocket URLs, which cannot carry a header, and is now confined to/graphql/ws.The playground introspection key was a UUIDv7 — 48 of its bits were the server start time in milliseconds. It is now 256 bits from the system CSPRNG, and compared in constant time.
Refresh tokens were stored as plaintext UUIDs. Now
sha256(token), and the tokens themselves are CSPRNG values rather than UUIDs.GraphQL errors returned raw SQLite messages and absolute filesystem paths. The detail is logged; clients get "internal error".
No query depth or complexity limit — a single nested query could fan out across the whole library. Now
limit_depth(12),limit_complexity(2000).Subsonic username was compared with
!=while both password paths correctly usedsubtle. Now constant-time.parse_rangeunderflowed on a 0-byte track file — panic in debug,u64::MAXin release. Guarded.Dependency refresh across the workspace. Notable majors: rusqlite 0.40, keyring 4, jsonwebtoken 11, rtrb 0.4, cpal 0.18, rmcp 3.1, bliss-audio 0.13, lofty 0.25, base64 0.23, tower-http 0.7, pem 4, getrandom 0.4, toml 1.1, jwalk 0.9, core-foundation 0.10, clap 4.6.
jsonwebtoken now uses the aws-lc-rs backend, shared with rustls rather than pulling a second crypto stack. Token verification is stricter than under 9.x: the signature check can no longer be disabled, and the
algheader is matched against the pinnedEdDSAunconditionally.keyring on Linux talks to secret-service over zbus instead of dbus-secret-service. macOS Keychain access is unchanged — same generic-password service/account attributes and the same user keychain — so existing credentials still resolve.
bliss-audio no longer needs the aubio C library; upstream replaced it with a Rust implementation, so
bliss-audio-aubio-rsand its bindgen build are gone. The feature vector is unchanged (FeaturesVersion::Version2), so stored embeddings stay valid, though decoded values may shift marginally after bliss's Symphonia/Rubato update.
Added
Native macOS app — a SwiftUI front-end in
apps/macos, built on a newkoan-fficrate that exposeskoan-coreto Swift via uniffi. In-process: no daemon, no port, no auth surface, and CoreAudio output stays in Rust so playback is bit-perfect. Queue-centric like the TUI, with album-grouped queue, a multi-select picker (add / add-and-play / replace queue), library and artist browsing, favourites, snapshots and synced lyrics. Visualizers are out of scope. Ships asbrew install --cask radiosilence/koan/koan-app.SubsonicClient::get_cover_art— fetches artwork from the remote server. Libraries synced from Navidrome have no local files to read embedded tags out of, so every album was previously blank in any client relying on tag extraction.queries::favourite_track_ids_batch— favourited track IDs in one query.koan scan --force-remove— deletes stale tracks even when the proportion missing trips the mount-failure brake, for the case where the files really were deleted. It lifts that one check and nothing else: a folder yielding no audio files is still left alone, and a path that cannot be stat'd is still not "gone". The run announces itself up front and lists what it removed.Render tests for the TUI (
crates/koan-tui/tests/render.rs) — the widget layer had no test coverage, and layout and unicode regressions compile cleanly while rendering wrong. Pins the main layout split at every terminal height, asserts the seek bar's click hit-test agrees with the columns actually painted, and sweeps every widget across terminal sizes from 1×1 upward with titles containing CJK, emoji, ZWJ sequences, combining marks and RTL text.
Seven ways koan organize could destroy music files, every one of which was reported as a successful move.
- Destinations are never overwritten.
move_filewas a barefs::rename, which silently replaces whatever is at the destination. Two rips of the same track, a case-only difference on macOS (RainvsRAIN), or a download landing in the library mid-run all destroyed a file and reported success. Planning now refuses a destination claimed twice in one run or already occupied on disk, andmove_filereserves the name atomically withcreate_newso nothing can slip into the gap. A case-only rename goes via a temporary name, since reserving the destination would otherwise open the source itself. - An empty path component no longer collapses an album onto one filename. An unresolvable function was dropped from the output without marking the expression unresolved, and the path sanitiser skipped empty components — so
%artist%/%album%/$nun(%tracknumber%,2). %title%, one typo, renamed every track on the album toArtist/Album.flac, each overwriting the last. Unknown function names are now a parse error, an unresolvable function marks its expression unresolved, and an empty,.or..component is refused instead of skipped. - Preview and execute read the same metadata. Preview resolved fields from the database and execute from file tags, and the two didn't populate the same fields:
%label%existed only in the tag path, so the shipped$if2(%label%,%album artist%)pattern previewed one tree and wrote another. Both now go through one resolver, withlabelanddatecoming off the album row. - The TUI's organize updates the database and can be undone. It used a path-only code path that wrote no
organize_logrows and lefttracks.pathpointing at the old locations — the queue looked right until the next launch, and a 5,000-file organize could not be undone. It now runs the same database-backed path as the GraphQL API; files the library has no row for are logged with a nulltrack_idso undo still covers them. - Empty-directory cleanup can't delete a library root. It walked up from the source directory with no floor, so organizing out of a configured library folder removed the folder itself. It now stops at the directories it was given.
- Undo refuses rather than clobbers. It never checked whether the original path had been re-occupied, picked its batch by a one-second timestamp that two batches could share, and aborted the whole run on the first failure while deleting the rows it had already processed. Batches are now chosen by primary key, each entry is restored only when its original path is free and the moved file still matches the size and modification time recorded for it, and per-entry failures are reported with their log rows left in place.
- Path-keyed state follows the file. Only
tracks.pathandscan_cache.pathwere rewritten, orphaning favourites (keyed by path), queue snapshots, saved playback state and cached paths. All of them are now rewritten in the same transaction as the move — and the database work happens first, so aUNIQUE(path)violation aborts before the file is touched instead of after.
Also hardened, same blast radius:
Cross-filesystem moves are durable.
fs::copyfollowed byremove_filemeant power loss between the two left a zero-length destination and no source. The copy now goes to a temporary file, is flushed withsync_all, has its length verified and its modification time restored, and only then replaces the destination and unlinks the original. A run that won't fit on the target filesystem is refused before it starts.The format parser can't be made to abort the process. Nesting is capped at 64 levels (a few thousand nested
[was a stack overflow, uncatchable, terminal left in raw mode), length-driven functions ($repeat,$pad,$num,$tab) cap their allocations, and$add/$sub/$muluse checked arithmetic.A
)inside a quoted argument no longer truncates a call. The end of a function call is now found by the argument parser, which understands quoting, instead of a naive paren count that ended mid-expression and re-parsed the tail as a literal — silently appending garbage to the path.Path components are length-capped at the same 240 bytes as the rest of the codebase, so a long title is shortened rather than previewing cleanly and failing with
ENAMETOOLONG.Release pipeline could not recover from a partial crates.io publish. The idempotency guard used
curl -sfagainst the crates.io API, which returns 403 to curl's default User-Agent under its data-access policy — so the guard never fired and a retry after a partial publish always failed on "crate version already uploaded". The only escape was another version bump, which is what v0.23.2 and v0.23.3 were. Replaced the hand-rolled loop withcargo publish --workspace, which orders by dependency and waits for the index itself, and dropped--no-verifyso the packaged crate is actually built.The git tag was cut before crates.io. Once tagged,
check-versionsaw the release as done and setshould_release=falseforever, so crates.io could never be retried. crates.io now publishes first and the tag marks a release that actually shipped.Documented
auth_enableddefault was wrong in four places (it defaults to true), and the v0.22.0 changelog entry contradicted itself. The guides that show how to disable auth now warn that doing so leaves the API open to anything that can reach the port.ARCHITECTURE.mdandCLAUDE.mdclaimed the koan-tui/koan-server boundary was compiler-enforced. It is not — koan-tui declares an (unused) dependency on koan-server.MSRV declared (
rust-version = "1.89", set by async-graphql) and enforced by a CI job.cargo auditjob and Dependabot for both cargo and GitHub Actions.Release gate that fails if the internal path-dep versions drift from the workspace version — the drift that
--no-verifywas hiding.Job timeouts, and
.gitignoreentries for local secrets and state.koan subsonic setup|status|disable.[graphql] allowed_hosts,cookie_secure,allow_organize.[subsonic] enabled,username,password.Tests for
auth/middleware.rs, which previously had none: the cookie/Bearer/query-param precedence chain, theauth_enabled = falseadmin bypass, the introspection-key bypass and its constant-time mismatch, theunwrap_or(Role::Readonly)fallback on an unparseable role claim, tokens signed by another key. Plus the WebSocketOrigincheck (foreign rejected, absent allowed, same-origin and configured allowed), thetext/plainPOST rejection, theHostallowlist, cover-art size clamping, the empty-file range guard, cookie flags, and the login rate limiter.
Changed
koan-core:SubsonicAuthsplits the credentials and URL signing out ofSubsonicClient, which constructs blockingreqwestclients and so cannot be built inside a tokio runtime.SubsonicClient::stream_to_filefetches through/rest/streamfor servers that implement only that.GraphQLClient::stream_urlis gone — it was unused and omitted the auth parameters/rest/*requires.Symphonia 0.5 → 0.6.1 — 0.6 rebuilt the format/codec registry, audio primitives, and metadata types around multi-track (audio/video/subtitle) media. Track timing moved off
CodecParametersontoTrack, which is where the audible wins come from: 24-bit/96 kHz ALAC now reports 96 kHz instead of 48 kHz (it previously played at half speed, and switched the output device to the wrong rate — fatal for a bit-perfect player), and ALAC-in-CAF decodes at all instead of erroring out. Playback frame counts are byte-identical across every other format.GraphQL collections default to 50 rows and cap at 500. A query with no
firstused to return the entire collection, so{ tracks { edges { node { title } } } }materialised a whole library as rows, as GraphQL values and as serialised JSON at once. Clients that relied on the unbounded form must paginate withfirst/after.triggerScanandtriggerRemoteSyncreturn aJob, not a result. Both run for minutes; they now start a detached worker and hand back{ id, kind, state, message }, polled with the newjob(id:)andjobsqueries. One job of each kind runs at a time — a second call returns the running one. The oldScanResulttype is gone; added/updated/unchanged counts arrive in the finished job'smessage.sortByandsortDirnow do something. They were declared, published in the SDL and to MCP, and silently dropped: a client asking forsortBy: DATEgot DB order and no error.GraphQL queries time out at 30s, shed load past 64 in flight (503) and survive a panicking resolver. The concurrency limit alone queued the surplus, so an overloaded server answered everyone slowly instead of telling the excess to come back. Subscriptions are exempt from the timeout.
Dependency refresh across the workspace. Notable majors: rusqlite 0.40, keyring 4, jsonwebtoken 11, rtrb 0.4, cpal 0.18, rmcp 3.1, bliss-audio 0.13, lofty 0.25, base64 0.23, tower-http 0.7, pem 4, getrandom 0.4, toml 1.1, jwalk 0.9, core-foundation 0.10, clap 4.6.
jsonwebtoken now uses the aws-lc-rs backend, shared with rustls rather than pulling a second crypto stack. Token verification is stricter than under 9.x: the signature check can no longer be disabled, and the
algheader is matched against the pinnedEdDSAunconditionally.keyring on Linux talks to secret-service over zbus instead of dbus-secret-service. macOS Keychain access is unchanged — same generic-password service/account attributes and the same user keychain — so existing credentials still resolve.
bliss-audio no longer needs the aubio C library; upstream replaced it with a Rust implementation, so
bliss-audio-aubio-rsand its bindgen build are gone. The feature vector is unchanged (FeaturesVersion::Version2), so stored embeddings stay valid, though decoded values may shift marginally after bliss's Symphonia/Rubato update.The library scan commits in 1000-file chunks instead of one transaction spanning the whole run. Ctrl-C at 90% used to discard everything and restart from zero; committed chunks now land in
scan_cacheso the next run resumes. Peak memory drops to one chunk rather than the whole library's metadata, and other writers — favourites, queue save on quit, play counts, GraphQL mutations — no longer sit behind a minutes-long write lock.busy_timeoutraised from 5s to 30s to match.Stale removal runs in its own transaction and propagates failures instead of logging them and committing anyway. Its refusal message names the folder, how many tracks are missing, out of how many, and the percentage, so an ambiguous case is diagnosable from the error alone.
scan_folderandfull_scantake aScanOptionsinstead of a bareforceflag, andremove_stale_tracksreturns the paths it removed rather than a count.Download timeouts are per-stall, not per-transfer — the download client bounds connect (10s) and time between bytes (30s) with no total deadline, and retries transient failures three times with backoff. JSON API calls keep a separate client with a 30s total deadline, which is correct for a small body read in one go.
One
SubsonicClientper app, not per download — the client was rebuilt insidedownload_track, re-reading config and redoing the TLS handshake for every track.SubsonicClient::stream_urland the auth path are fallible — the salt is generated from OS entropy and a request without it now fails instead of falling back to anything predictable. The salt is sent alongsidemd5(password + salt), so a guessable one would make the token precomputable from a captured exchange.All remote downloads share one implementation (
koan-core/src/remote/download.rs) — there were three copies of "stream bytes to disk with progress" and only one wrote to a temp file and verified the result.ratatui 0.29 → 0.30, crossterm 0.28 → 0.29 — the two move together because
ratatui-crosstermdefaults to crossterm 0.29; bumping ratatui alone resolves two crossterm versions and breaks at the backend boundary. No source changes: koan's ratatui surface isBuffer,Rect,Style,Line/Span,WidgetandLength/Min/Percentageconstraints, and every 0.30 breaking change lands elsewhere.0.30 splits into
ratatui-core/ratatui-widgets/ratatui-crosstermand replaces the cassowary layout solver with kasuari. Solver output is unchanged for koan's constraint sets, andBuffer's out-of-bounds policy still panics rather than clamping, so nothing that used to render now renders differently or silently truncates. The one behavioural change is that halfwidth katakana dakuten/handakuten (U+FF9E/U+FF9F) now measure one cell instead of zero, matching how terminals actually draw them.The optional
termwiz/terminabackends appear inCargo.lockbut stay out of the build graph.The pre-push hook no longer runs
git add -A && git commit --amendwhencargo fmtchanges files — it swept unrelated working-tree changes into the user's commit. It now fails and asks. It also runs--all-targets, matching CI, so warnings in test code stop passing the hook and failing CI.
Removed
The ReplayGain scanner.
scan_track,scan_album,write_tagsand their helpers had no caller anywhere and no CLI or GraphQL surface — andscan_albumwas wrong regardless: it built one R128 analyser from the first track's spec and fed every subsequent track through it, so a mono interlude or a 48 kHz bonus track silently corrupted the album gain for every track. Reading and applying ReplayGain tags during playback is untouched. Drops theebur128dependency.playback.software_volume. Declared, defaulted, documented and tested, but read by nothing since it was added — setting it did nothing at all.cargo testoverwrote the user's real JWT signing key.auth's keypair tests calledgenerate_keypair(), which writes to~/.config/koan/auth/, so running the test suite rotated the live Ed25519 key and invalidated every issued token. Keypair derivation is now split from the filesystem write and the tests use the pure form.MP3s at unusual sample rates played at the wrong speed — the audio engine was configured with the rate the device settled on, not the rate the PCM actually is. Output devices reject the MPEG-2/2.5 rates that only MP3 uses (8/11.025/12/16/22.05/24 kHz, and 32 kHz on many DACs), so a 22.05 kHz MP3 on a 44.1 kHz device played at exactly double speed. The engine is now always configured from the source format and the device switch is a best-effort bit-perfect optimisation; when it fails the platform resamples instead. FLAC never hit this because it is only ever ripped at rates every device supports. (#181)
Mixed-format queues played the second track at the wrong speed — every track in a gapless session shares one ring buffer and therefore one engine, but the decode thread would happily push a 48 kHz track in behind a 44.1 kHz one. A track whose rate or channel count differs now ends the decode session so the player can restart it on a correctly configured engine.
Tail of the last decoded track was cut off — the decode thread signalled completion as soon as it had written the last sample, up to 4 seconds before the audio engine had played it. It now waits for the ring buffer to drain first.
An empty or unmounted library folder deleted the entire library —
full_scanonly checked that the folder existed, so a NAS mount that failed, an unattached Docker volume, or a directory whose permissions changed left an empty-but-present path. Stale removal then found every indexed path missing and deleted the rows along with their play history, lyrics and embeddings. Three brakes now: a folder yielding zero audio files skips stale removal entirely,try_existsmeans an IO error is never read as "deleted", and a run that would clear more than 20% of a folder holding at least 100 tracks is refused outright.Scanning one folder swept its siblings — the stale-removal prefix had no trailing separator, so scanning
/Volumes/Musicalso matched/Volumes/Music Backup. Unplugging the backup drive and rescanning the main one deleted the backup's rows.Content dedup merged distinct tracks and lost a file — the match ignored
disc, so a 2-CD box set whose discs share a track title and number collapsed into one row pointing at whichever disc was scanned last; the other file became unreachable in library, search and queue, and stale removal never noticed because the file was still on disk.discis now part of the predicate, and the match only fires across sources: two rows that both carry a local path, or that both carry a remote id, are two tracks. That keeps the local↔︎remote dedup the design wants. The cost is that a server which rotates its ids yields visible duplicates instead of re-attaching silently — duplicates you can see and fix, where a swallowed track you can do neither with.Remote sync erased locally-scanned audio properties — merging wrote every column straight from the incoming metadata, so syncing against a Navidrome serving the same files nulled
sample_rate,bit_depth,channels,size_bytesandmtimeacross the library and rewrote the codec. A merge now fills gaps only and never overwrites a populated column with NULL.Orphaned
scan_cacherows aborted stale cleanup half-done — cleanup deleted the cache row by the track's current path, leaving any row under a former path behind. The foreign key then failed theDELETE FROM tracks— after the FTS, lyrics, play-history and embedding rows had already gone — and every remaining stale track in that run was skipped. Cache rows are now cleared bytrack_idas well as path.A single panicking file aborted the whole scan — lofty and symphonia can panic on hostile tags; rayon re-raised it at
collect(), so one bad file out of 500k produced zero indexed tracks and a backtrace that didn't name it. Tag reads are contained; the file is reported as an error and the scan continues. Same for acoustic analysis.Files skipped by walkdir vanished silently — permission-denied subtrees and symlink loops were discarded without a word. They are logged, counted in
ScanResult::unreadable, and reported bykoan scan.ScanResult::updatedwas always zero — every upsert counted asadded, sokoan scanprinted "0 updated" every run and GraphQL returned the same throughtracksUpdated.upsert_track_statusreports whether a row was inserted, which also makesScanEvent::is_newtruthful.A failed
scan_cachewrite was swallowed — the track was indexed but uncached, so every future scan re-read its tags with no diagnostic.Failed album fetches no longer become permanent library holes — a sync that lost albums to network errors still reported success and advanced
last_sync, so the next incremental sync skipped straight past them.last_syncnow only advances when every album fetch succeeded, andSyncResultcarries the failure count sokoan remote syncandtriggerRemoteSyncreport an incomplete run.Sync pagination can no longer skip albums — the offset walk used
type=newest, whose ordering shifts whenever the server reorders or adds an album mid-sync. It now walksalphabeticalByName, de-duplicates album ids for the run, and usescreatedonly to decide which albums need a detail fetch.Truncated downloads can no longer masquerade as cached tracks — the TUI remote bridge wrote straight to its destination and only checked completeness when the server sent a Content-Length, so a dropped connection on a chunked stream (Navidrome's transcoded output) left a truncated file that played as a stub for the rest of the session. Every remote download now goes through one implementation that writes a
.partfile and renames only on a verified-complete transfer.The remote-stream cache is bounded — bridge downloads were keyed on a per-session queue id, so nothing was ever reused and every play left a full-size file behind forever. They are now keyed on track identity and the directory is pruned to a 2GB budget.
Priority downloads respect
download_workers— cursor movement spawned an unbounded thread per landing, so scrolling a large remote queue fired hundreds of concurrent requests at the server. Priority downloads now run on a two-permit lane, tracks already downloading are never started twice, and anything over the limit goes to the head of the worker queue.Favouriting a track mid-download sticks — the star was keyed on the in-progress
.partpath, which stops existing when the download completes, so it silently disappeared and was never pushed to the server.Download workers survive panics — a panicking download permanently shrank the worker pool for the process lifetime.
Lost server connections are visible — the remote bridge swallowed poll errors and froze on the last known state while retrying at 10Hz. Connection loss and recovery are now logged.
remove_track_by_pathandremove_tracks_by_source— unused outside their own tests, and both left orphaned foreign-key rows behind that would fail a later delete.
Fixed
No modern Subsonic client could finish a library sync. The JSON serialiser emitted every attribute as a string, so
getSong?f=jsonreturned"duration": "240"where the OpenSubsonicChildschema says int. Symfonium, Substreamer and Feishin all default tof=jsonwith generated deserialisers and aborted on the first song;isDirwas never emitted at all. Attribute values now carry their wire type —duration/track/bitRate/year/songCount/albumCountare ints,isDir/public/thegetUserroles are booleans — and only JSON changes. The XML wire format is byte-for-byte what it was, plus the newly added attributes.No client showed cover art anywhere. Neither songs nor albums carried a
coverArtid. They now do (mf-<id>andal-<id>), andgetCoverArtresolves the prefix: it previously read every id as a track id, sogetCoverArt?id=5meaning "album 5" silently served track 5's art. A bare numeric id still means a track. Rendered covers are cached (256 entries, keyed on id and size) — painting a 200-album grid used to decode 200 media files.createPlaylistwith any song returned a bare HTTP 400.serde_urlencoded, which axum'sQueryextractor uses, cannot deserialise the repeatedsongIdparameter into aVec, so the request was rejected with a plain-text body before the handler ran and only empty playlists could be created. The query is now parsed directly. The response also carries the created playlist, as it has since Subsonic 1.14.0.Playlist contents were invisible to XML clients.
getPlaylistemitted members as<song>where the schema says<entry>.Unimplemented endpoints returned an empty HTTP 404 instead of a Subsonic error, which several clients read as a broken server and fail their connection test on. Anything unhandled under
/rest/now answers with error code 70.getIndexes,getMusicDirectory,getAlbumList,getUserandgetScanStatusare implemented rather than refused — the first two are how DSub and every file-browse client enumerate a library.koan play --servernever played audio. The bridge built/rest/stream?id=<queue-item UUID>with no auth parameters, against a handler expecting a library row id, so every request was rejected before it ran.NowPlayingTrackandQueueEntrynow exposetrackId, and the bridge signs its requests with the[subsonic]credentials from the machine it runs on — set those to match the server's, or client mode has nothing to stream with.getGenresreturned blank genre names to XML clients — the name was written as avalueattribute, which is the JSON spelling; the XSD carries it as element text. It also loaded the entire tracks table to count genres, now oneGROUP BY.An unsatisfiable
Rangeserved the whole file with a 200 instead of a 416 withContent-Range: bytes */<total>. ARangeheader that does not parse is still ignored, per RFC 9110.A malformed
idcame back as a bare HTTP 400 from axum's extractor rather than a Subsonic error 10.Database errors read as an empty library.
getAlbum,getGenres,getPlaylistsand the artist album counts swallowed failures and answeredstatus="ok"with zero rows, which tells a client to drop its cached library.The Subsonic router was built twice at startup, each build re-reading two config files and, on macOS, prompting the keychain. Proxied upstream streams also built a fresh HTTP client and re-read the config on every request; both are now resolved once.
The Linux audio callback took a mutex on every buffer. The rtrb consumer was wrapped in a
std::sync::Mutexso it could move into cpal'sFnMutcallback — butrtrb::Consumeris alreadySendand the callback bound isFnMut + Send, so a by-value capture was always enough. The lock cost an atomic read-modify-write per callback on the real-time thread, and itstry_lockfailure path filled the buffer with silence: an audible dropout reachable only through a contention that could not occur.A panicking background job poisoned the job registry for every later lookup, and a poisoned decode cursor silently stopped the gapless lookahead — stalling the queue with no error rather than failing loudly. Both now use
parking_lot, which the project's own primitive table specifies.A GraphQL query could stall audio in every connected Subsonic client. rusqlite is blocking and nothing in the server ran it off the async runtime, so resolvers occupied tokio workers directly. Four concurrent
fuzzySearchcalls on a 4-core box took every worker, theReaderStreamfeeding each in-flight/rest/streamresponse stopped producing bytes, and clients dropped the connection mid-track. OnetriggerScandid it single-handedly for the length of the scan. Every SQLite call, HTTP fetch, tag read and file decode now runs on the blocking pool.A fresh SQLite connection was opened per resolver field.
Database::opencreates the parent directory, chmods the file, sets four pragmas, attempts a WAL checkpoint and runs a ~30-statement DDL batch plus three migrations — all of it, every field. On a 500-artist library the nested artists → albums → tracks query cost roughly 3,500 open cycles, about 120,000 statements. The schema now holds a small connection pool sized to the core count,Database::open_existingskips the setup for pooled connections, and the DDL runs once.N+1 queries across the type graph.
Track.isFavouriteopened a connection and scanned the wholefavouritestable per track;Album.trackCountandtotalDurationMseach materialised every row of the album to count or sum them;Artist.albumCount/trackCountre-ran the query their sibling field had just run. Counts and sums are nowCOUNT(*)/SUM(...)in SQLite, and parent → child edges go through dataloaders, so{ tracks(first: 500) { isFavourite } }is one query rather than 500 connections and 500 table scans.tracks(...)loaded the whole library and filtered it in Rust. Every predicate ran as aretain()over every row before pagination,search:silently truncated at 10,000 rows, andyearStart/yearEndranSELECT date FROM albums WHERE id = ?once per track in the library. Filters, ordering and the page window are now SQL with bound parameters.first: -1overflowed the page arithmetic — a panic in debug, a request for the entire library in release.A full player command channel parked a tokio worker.
send_cmdused crossbeam's blockingsendon a bounded(16) channel while the player can sit instart_playbackfor about a second during a device rate change. It now waits 250ms and reports "player busy".cargo testoverwrote the user's real JWT signing key.auth's keypair tests calledgenerate_keypair(), which writes to~/.config/koan/auth/, so running the test suite rotated the live Ed25519 key and invalidated every issued token. Keypair derivation is now split from the filesystem write and the tests use the pure form.MP3s at unusual sample rates played at the wrong speed — the audio engine was configured with the rate the device settled on, not the rate the PCM actually is. Output devices reject the MPEG-2/2.5 rates that only MP3 uses (8/11.025/12/16/22.05/24 kHz, and 32 kHz on many DACs), so a 22.05 kHz MP3 on a 44.1 kHz device played at exactly double speed. The engine is now always configured from the source format and the device switch is a best-effort bit-perfect optimisation; when it fails the platform resamples instead. FLAC never hit this because it is only ever ripped at rates every device supports. (#181)
Mixed-format queues played the second track at the wrong speed — every track in a gapless session shares one ring buffer and therefore one engine, but the decode thread would happily push a 48 kHz track in behind a 44.1 kHz one. A track whose rate or channel count differs now ends the decode session so the player can restart it on a correctly configured engine.
Tail of the last decoded track was cut off — the decode thread signalled completion as soon as it had written the last sample, up to 4 seconds before the audio engine had played it. It now waits for the ring buffer to drain first.
An empty or unmounted library folder deleted the entire library —
full_scanonly checked that the folder existed, so a NAS mount that failed, an unattached Docker volume, or a directory whose permissions changed left an empty-but-present path. Stale removal then found every indexed path missing and deleted the rows along with their play history, lyrics and embeddings. Three brakes now: a folder yielding zero audio files skips stale removal entirely,try_existsmeans an IO error is never read as "deleted", and a run that would clear more than 20% of a folder holding at least 100 tracks is refused outright.Scanning one folder swept its siblings — the stale-removal prefix had no trailing separator, so scanning
/Volumes/Musicalso matched/Volumes/Music Backup. Unplugging the backup drive and rescanning the main one deleted the backup's rows.Content dedup merged distinct tracks and lost a file — the match ignored
disc, so a 2-CD box set whose discs share a track title and number collapsed into one row pointing at whichever disc was scanned last; the other file became unreachable in library, search and queue, and stale removal never noticed because the file was still on disk.discis now part of the predicate, and the match only fires across sources: two rows that both carry a local path, or that both carry a remote id, are two tracks. That keeps the local↔︎remote dedup the design wants. The cost is that a server which rotates its ids yields visible duplicates instead of re-attaching silently — duplicates you can see and fix, where a swallowed track you can do neither with.Remote sync erased locally-scanned audio properties — merging wrote every column straight from the incoming metadata, so syncing against a Navidrome serving the same files nulled
sample_rate,bit_depth,channels,size_bytesandmtimeacross the library and rewrote the codec. A merge now fills gaps only and never overwrites a populated column with NULL.Orphaned
scan_cacherows aborted stale cleanup half-done — cleanup deleted the cache row by the track's current path, leaving any row under a former path behind. The foreign key then failed theDELETE FROM tracks— after the FTS, lyrics, play-history and embedding rows had already gone — and every remaining stale track in that run was skipped. Cache rows are now cleared bytrack_idas well as path.A single panicking file aborted the whole scan — lofty and symphonia can panic on hostile tags; rayon re-raised it at
collect(), so one bad file out of 500k produced zero indexed tracks and a backtrace that didn't name it. Tag reads are contained; the file is reported as an error and the scan continues. Same for acoustic analysis.Files skipped by walkdir vanished silently — permission-denied subtrees and symlink loops were discarded without a word. They are logged, counted in
ScanResult::unreadable, and reported bykoan scan.ScanResult::updatedwas always zero — every upsert counted asadded, sokoan scanprinted "0 updated" every run and GraphQL returned the same throughtracksUpdated.upsert_track_statusreports whether a row was inserted, which also makesScanEvent::is_newtruthful.A failed
scan_cachewrite was swallowed — the track was indexed but uncached, so every future scan re-read its tags with no diagnostic.Failed album fetches no longer become permanent library holes — a sync that lost albums to network errors still reported success and advanced
last_sync, so the next incremental sync skipped straight past them.last_syncnow only advances when every album fetch succeeded, andSyncResultcarries the failure count sokoan remote syncandtriggerRemoteSyncreport an incomplete run.Sync pagination can no longer skip albums — the offset walk used
type=newest, whose ordering shifts whenever the server reorders or adds an album mid-sync. It now walksalphabeticalByName, de-duplicates album ids for the run, and usescreatedonly to decide which albums need a detail fetch.Truncated downloads can no longer masquerade as cached tracks — the TUI remote bridge wrote straight to its destination and only checked completeness when the server sent a Content-Length, so a dropped connection on a chunked stream (Navidrome's transcoded output) left a truncated file that played as a stub for the rest of the session. Every remote download now goes through one implementation that writes a
.partfile and renames only on a verified-complete transfer.The remote-stream cache is bounded — bridge downloads were keyed on a per-session queue id, so nothing was ever reused and every play left a full-size file behind forever. They are now keyed on track identity and the directory is pruned to a 2GB budget.
Priority downloads respect
download_workers— cursor movement spawned an unbounded thread per landing, so scrolling a large remote queue fired hundreds of concurrent requests at the server. Priority downloads now run on a two-permit lane, tracks already downloading are never started twice, and anything over the limit goes to the head of the worker queue.Favouriting a track mid-download sticks — the star was keyed on the in-progress
.partpath, which stops existing when the download completes, so it silently disappeared and was never pushed to the server.Download workers survive panics — a panicking download permanently shrank the worker pool for the process lifetime.
Lost server connections are visible — the remote bridge swallowed poll errors and froze on the last known state while retrying at 10Hz. Connection loss and recovery are now logged.
Deleting the playing track jumped back to the top of the queue — removing an item clears the cursor, and an unset cursor means "start from the beginning", so deleting track 25 of 40 resumed at track 1. The removed track's predecessor is now pinned before advancing, so playback continues at its successor. Reachable from the TUI, GraphQL and MCP.
Deleting an upcoming track replayed the whole queue — the decode thread's gapless lookahead runs up to ~4 seconds ahead of what is audible, and its reference item vanishing was read as "start of queue". Track 6 would run gaplessly into track 1. A missing reference now ends the lookahead so the audible track's own successor is used.
Playback died for good when the next track had not finished downloading. Advancing only accepted fully-downloaded tracks and left the cursor where it was, and the download completion signal is discarded unless the cursor is on that track — so on a slow link the queue stopped with every track showing Ready and nothing resumed it. The cursor now parks on the track being fetched and playback resumes when its bytes land.
A failed stream download hung playback and leaked three threads. The decode thread waited on a condvar with no timeout and no way to learn the download had died; the pump feeding it spun at 100 wakeups/sec forever, holding the whole buffered track (100+ MB for hi-res FLAC), and the engine teardown then blocked on joining it. Reads now fail with a broken-pipe or timeout error rather than a silent EOF that would truncate the track, and the pump exits when the download fails, stalls for 30s, or nothing is left to read it. A chunked transfer with no Content-Length no longer hangs at end of track.
Batch-deleting a selection containing the playing track restarted the audio engine once per deleted track — each restart re-probes the file, re-enumerates devices and can change the DAC's sample rate, so Ctrl+A Delete on a long queue froze the player and clicked the output. The resume point is now resolved once for the whole selection.
Undo of a multi-track delete restored tracks in the wrong order. The selection arrives from a
HashSetin arbitrary order, and re-inserting a track whose recorded predecessor had not been restored yet appended it to the end. Positions are now snapshotted in playlist order.A four-way lock cycle could hang the app in remote-bridge mode —
current_download_fractiontook the track-info lock before the playlist lock whilederive_visible_queuetook them the other way round. Neither holds both any more.A failed playback start left a zombie "Playing" transport with a frozen position, since the engine had already been torn down by the time the failure surfaced. A failure now leaves the player cleanly stopped, and pause/resume report what the engine actually did instead of assuming success.
The visualizer ran up to 4.35 seconds ahead of the audio. Every mode — spectrum, VU, oscilloscope, lissajous, beat-reactive colour — was drawing samples the DAC had not reached yet. The decode thread pushed into the viz buffer at the moment it wrote into the ring buffer, and a local FLAC decodes 50-100x realtime, so the ring stays saturated and a sample written at T is heard at T + ring_depth/rate: 4.35s at 44.1kHz, 4.00s at 48kHz, 2.00s at 96kHz, 1.00s at 192kHz. Nothing looked broken because the bars still moved in time. The viz buffer is now a delay line the length of the ring buffer, read at the position the audio engine's played counter reports rather than at the write head. Feeding it from the render callback was not an option — that thread may never allocate or lock.
The transport went blank for ~50-100ms on every skip and every seek.
stop_enginesignals the decode thread and hands the join to a cleanup thread, so the outgoing thread was still mid-packet when the new session'stimeline.reset()ran. Its finaladd_writtenthen landed on the fresh timeline — one packet, 4608 interleaved samples for stereo MP3 and up to 8192 for FLAC — so the new track's first boundary was stamped at that offset instead of 0, and with the fresh engine'ssamples_playedstarting at 0 the binary search found nothing andcurrent_playback()returnedNone. The same window admitted a phantompush_boundaryfrom the dying thread, which would have shown the wrong track's metadata for the rest of the session. Timeline writes now go through a handle carrying the generation its session started in, checked under the same lockreset()takes; a retired handle's writes are dropped. The decode thread also polls it as a second abort signal, which stops a dying thread pushing into the visualizer delay line the next session has just reset.Seeking reported the requested position, not where playback resumed. The timeline recorded the seek target before the seek ran, and symphonia's returned landing point was discarded. Coarse seeking made this worse rather than exposing it: it picks a byte offset by interpolating linearly over the whole file and then derives its reported timestamp from that same guess, so a 5-minute VBR MP3 seeked to 2:30 resumed at 2:33.7 while reporting 2:29.9 — a 3.8-second lie for the rest of the track, and near the end the bar pinned at 100% while audio still played. Seeks are now accurate rather than coarse (1.5-3ms on files up to 79MB) and the boundary is pushed after the seek, from the real landing point.
One unreadable file killed the rest of the queue and truncated the track still playing. A failure to open or decode any track ended the decode thread, which the player read as end-of-queue. Because the decode head runs up to a full ring buffer ahead of the DAC, track 5 of an album failing cut track 4 off ~4 seconds early and tracks 6-20 never played at all; a bad first track ended the session without trying anything else. Bad sources are now skipped with the path logged, with a 32-consecutive-failure cap so a wholly unreadable queue still terminates.
ReplayGain clipped hard whenever the peak tag was absent. Gain was only limited when a peak tag existed, and nothing downstream clamps — engine.rs, cpal_backend.rs and opus.rs go straight to the DAC. A quiet classical recording tagged
REPLAYGAIN_TRACK_GAIN=+9.5 dBwith no peak gave ~2.99x, so everything above 0.33 FS clipped: gross continuous distortion on exactly the material ReplayGain exists to rescue. A negative peak from a malformed tag inverted phase. Only a finite, positive peak is now trusted to bound the gain, and the output is clamped to ±1.0 unconditionally."+3.21 db"silently disabled ReplayGain — only a literal"dB"suffix was stripped, so a lower-case tag failed to parse and the file played unadjusted. The suffix match is now case-insensitive.Spectrum read 6 dB low. The FFT magnitude scale was
2/N, correct for a rectangular window, but the analyzer applies a Hann window with a coherent gain of 0.5. Everything read 6.02 dB down, so against the -80 dB floor a full-scale sine topped out at 0.925 and the bars never reached the top of the widget. The scale is now derived from the window's own sum.Spectrum bass bars combed and collapsed at high sample rates. A fixed 2048-point FFT spaces bins 93.75 Hz apart at 192 kHz, leaving whole runs of the bottom Bark bars with no bin at all. The gap filler ran left-to-right in place, so it fed synthesised values into the next bar's average while the bar to the right was still zero: a sawtooth ripple biased low, with bar 0 sitting permanently at half height. Runs of empty bars are now interpolated in one pass between their measured neighbours.
Known issues
- WAV
LIST INFOtags are not read — Symphonia 0.6.1's WAV reader parses the chunk into a metadata log and then builds the reader fromexternal_datainstead, discarding it. Only reachable for WAVs lofty cannot parse, since lofty reads these tags on the happy path; such files fall back to a filename-derived title.
Closes the browser-facing attack surface on koan serve. The threat model that drove this: koan on a LAN, reachable from other machines on the network and from any web page the owner's browser happens to load.
Internal
- Internal crate versions are declared once, in
[workspace.dependencies], instead of being pinned per member — the per-member pins had drifted a patch behind and would have published a brokenkoan-cliat the next minor bump. koan-tuino longer depends onkoan-server. It never imported it; the dependency pulled axum, async-graphql, rmcp, tokio and tower into every TUI build and contradicted the documented crate boundary, which is now compiler-enforced again.reqwestis declared once in[workspace.dependencies]with the feature union the workspace already resolved to, replacing four declarations with four different feature sets.- Dropped confirmed-unused deps:
toml,chrono,rayon,owo-colorsfrom koan-tui;walkdirfrom koan-server;core-foundation,crossbeam-channelfrom koan-cli. - Tests covering the
ALTER TABLEschema migrations: SQLite's "duplicate column" wording is the only thing stoppingDatabase::openfrom failing on an already-migrated database, so it is now asserted rather than assumed. - Transport geometry ignored the layout solver, writing outside the frame buffer —
render()derived the album-art rect, the transport text rect and the spectrum rect from the height it asked for, not the height the solver granted. On a short terminal the solver shrinks the transport, the text rect lands below the buffer, andBuffer::set_stringn(which clamps x but never y) indexes straight off the end. Trigger iswidth >= art_size + 2 && height <= art_size / 2 - 3— at the defaultart_size = 24that is width >= 26 and height <= 9, so 80x24 was safe. Dragging the transport divider persistsart_sizeup to 80 intoconfig.toml, and at 80 the trigger covers ordinary terminals: koan then panicked on the first frame of every launch, with no way to fix it from inside the app. All three rects now come from the solver, andrender()bails out with a message below 20x5. - FPS overlay underflowed on narrow terminals — the counter is 14 cells wide (19 with the beat tag) but only checked for 8, so
area.x + area.width - wwrapped. - Empty queue panicked in a one-row pane —
QueueViewwrote its "empty" line atblock.inner(area).ywithout checking the top border had left a row. - Album dates with multibyte characters panicked — the library browser and album picker took
&date[..4]to get the year.len()is bytes, and date tags are free-form text, so a Japanese or Chinese pressing (or fullwidth digits) split a character mid-sequence. Now counts characters. - Queue clicks resolved to the wrong row after an edit-mode scroll —
QueueViewcomputed its own scroll offset in edit mode and never wrote it back, whileAppscrolled against a different height and every hit-test read the stale offset. Once they diverged, clicking a track selected the one above it for the rest of the session. There is now one definition of the queue's visible height, and the widget renders exactly the offset it is given. - All but the last mouse event in a frame were dropped — coalescing every event meant a trackpad flick scrolled one line, and a click whose press and release landed in the same frame did nothing. Only motion coalesces now.
- Terminal left in raw mode on I/O errors — every
?out of the event loop skipped the restore block. ADropguard handles it. - Track info modal keyed off a queue index — removing a track shifted it onto a different track, or past the end, where the modal rendered nothing while still swallowing every keystroke. It now holds a
QueueItemIdand closes when that track leaves the queue. - Library filter bar overlapped its own click region — the view reserves the bottom row for the filter input while focused, but hit-testing and scrolling used the full height, so clicking the input selected a node.
- Transport resize handle stole the queue's top border row.
- Queue scrollbar's last drawn row was not clickable — clicking it fell through and selected a track.
- Matroska duration — MKV states its duration at media level in millisecond ticks, which was being read as a frame count and rendered a 10-second file as 226 ms. Durations now come from the container's stated duration via its own timebase, falling back to the playable frame count.
- MP3 duration overstated by ~30 ms — the probe reported the untrimmed frame count while the decoder dropped encoder delay and padding, so the seek bar ran past the end of the audio. Both sides now report the trimmed length.
- Gapless trimming in ReplayGain scans — encoder delay and padding are now dropped before loudness analysis, so MP3/Vorbis scans no longer measure the silence the decoder discards. Scanned gain values shift very slightly; re-scan to refresh them.
0.23.3
Fixed
similarArtistscrashed on pre-existing DBs — schema added arelationshipcolumn tosimilar_artistsbut shipped noALTER TABLEmigration, so databases created before the column existed blew up withno such column: sa.relationshipthe moment the query ran. Added the migration alongside the existing cache-column migrations and a regression test that boots a pre-migration schema and verifiescreate_tablespatches it. (#180)
0.23.2
Second attempt at getting the split crates on crates.io. v0.23.1 published koan-core but then failed because the publish order had koan-tui before koan-server — and koan-tui depends on koan-server. Flipped the order; no code delta.
Fixed
- Publish order —
koan-servernow publishes beforekoan-tuiso the crates.io index sees the dependency before downstream crates try to resolve it.
0.23.1
Re-release of v0.23.0 to publish the split crates to crates.io. No code changes from v0.23.0.
Fixed
- Missing crates on crates.io — the publish-crate CI job referenced the pre-split binary name (
koan-music) and silently failed for every release since v0.21.0.koan-tui,koan-server, andkoan-clihad never been published. The job now publishes all four crates in dependency order and is idempotent across partial retries. (#177)
0.23.0
Groundwork for the upcoming browser SPA: full GraphQL schema for web clients, real-time subscriptions, cookie auth, and configurable CORS. Subsonic streaming now rides the GraphQL port by default, so the remote TUI (koan play --server) finally works end-to-end.
Added
- GraphQL subscriptions — real-time data over WebSocket at
/graphql/ws. Three subscriptions:nowPlaying(playback state at configurable interval),queueUpdated(full queue snapshot on change),vizFrame(spectrum/VU/waveform at configurable FPS). (#162, #171) - Queue snapshot with status —
queuequery returnsQueueSnapshotwith versioned entries, each with derivedstatus(Queued/Playing/Played/Downloading/PriorityPending/Failed) and optionaldownloadProgress. Replaces flatVec<QueueEntry>. - Visualizer query —
vizFramequery returns current spectrum, peaks, VU levels, beat energy, and optional waveform. Returns null when no analyzer is running. - Config query + mutation —
configquery exposes current settings,updateConfigmutation writes individual fields toconfig.toml(admin-only). - Playlist version query —
playlistVersionreturns monotonic counter for change detection. - Playback state persistence —
savePlaybackStateandclearPlaybackStatemutations for web clients. - Cookie auth for web clients — auth routes set
HttpOnly; Secure; SameSite=Nonecookies alongside JSON responses. Middleware checks cookie before Bearer header (priority: cookie > Bearer > query param). Logout clears the cookie. No breaking changes for CLI/mobile clients. (#172) - Configurable CORS origins —
[graphql] cors_origins = [...]restricts allowed origins withcredentials: truefor cookie auth. Empty (default) keepsAllow-Origin: *for dev/backward compat.
Fixed
- Subsonic streaming works on the GraphQL port — Subsonic REST is now merged onto the GraphQL router whenever remote credentials are configured, so
koan play --server <url>can pull streams without a second listener.--subsonic <port>continues to expose an additional dedicated listener for clients that expect a separate port. (#174) - Rust 1.95 clippy lints — resolved
collapsible_match,manual_checked_ops, andabsurd_extreme_comparisonsacrosskoan-coreandkoan-tui. Pure refactor; no behaviour change. (#175)
Known issues
- Remote TUI client doesn't send a JWT yet —
koan play --server <url>still fails againstauth_enabled = trueservers because the client has no login/token flow. Tracked in #173.
Internal
ApiServerOptsstruct — replaces positional args on internalrun_api_blocking, carries optionalVizSnapshotfor subscription support.
0.22.0
Security
- Constant-time password comparison in Subsonic API (fixes timing attack).
- Atomic refresh token rotation (single SQL statement, no TOCTOU race).
- Key file permissions set before write (no world-readable window).
- Server panics if auth enabled but keypair missing (fail-closed).
- GraphQL handler requires AuthUser injection (no silent admin fallback).
- Hardcoded admin/admin Subsonic fallback removed.
- Auth keypair directory gets automatic
.gitignore.
Added
- API authentication — JWT-based auth with Ed25519 signing for the GraphQL and Subsonic APIs. (#161)
- Three roles:
admin(full control),user(playback, queue, favourites),readonly(browse-only). - Argon2id password hashing, short-lived access tokens (15min default), single-use rotating refresh tokens (30d default).
- Auth routes:
POST /auth/login,POST /auth/refresh,POST /auth/logout. - Axum middleware validates JWT on protected routes. When
auth_enabled = false, all requests pass through as admin — zero breaking change for existing installs. - CLI commands:
koan auth setup(keypair + first admin),koan auth create-user,koan auth delete-user,koan auth list-users,koan auth login,koan auth logout. - Refresh tokens stored in platform keychain via
keyring. In-process execution (MCP) bypasses auth. - Config:
[graphql]section gainsauth_enabled,access_token_ttl,refresh_token_ttl. - DB tables:
users,refresh_tokens(auto-created on startup). - Role-based guards on all GraphQL mutations (admin: scan/organize/device, user: playback/queue/favourites, readonly: queries only).
koan auth reset-password <user>— reset password, revoke all tokens.koan auth set-role <user> <role>— change a user's role.koan auth regenerate-keys— regenerate Ed25519 keypair, invalidate all tokens.koan auth reset— nuclear option, wipe all auth state.- Non-interactive setup via
KOAN_USERNAME+KOAN_PASSWORDenv vars. - Auth enabled by default.
- Three roles:
- 1Password CLI integration — on user creation, offers to generate a secure 32-char password and save to 1Password as
koan@<hostname>. Updates existing items if found. - GraphQL playground with introspection key —
koan --headless --playgroundgenerates a process-scoped key, injects it into GraphiQL as a default header, auto-opens the browser. Normal JWT auth unaffected. - CORS support — API endpoints accept cross-origin requests for browser clients.
0.21.0
Added
- Integration test coverage — 12 new behavioral tests covering the scanner, decode pipeline, session persistence, remote sync, GraphQL mutations, and config loading. Shared WAV file generators in
test_utils.rs. Safety net for the crate restructure. - Bitrate display for lossy codecs — transport bar shows bitrate (e.g.
Opus 48kHz/128kbps stereo) instead of a fake bit depth. Estimated from file size / duration for Opus. (#155) - Human-readable quality labels —
FLAC · CD qualityfor 44.1kHz/16bit/stereo,stereo/monoinstead of2ch/1ch, sample rates as44.1kHznot44100Hz. (#155)
Changed
- Crate restructure — split monolithic
koan-musicinto four crates with compiler-enforced dependency boundaries. (#157)- koan-core — audio engine, player, DB, Subsonic client, format strings, config. Platform-agnostic library. Now includes shared helpers (subsonic client builder, cache paths, track resolution, download).
- koan-tui — Ratatui TUI, visualizers, media keys, transport, download queue. Library crate exporting
run_tui(). - koan-server — GraphQL (async-graphql + axum), Subsonic REST API, MCP server. Library crate.
- koan-cli — thin entry point with clap CLI, logger, signal handling. Produces the
koanbinary. - Dependency rules enforced by Cargo: koan-tui and koan-server cannot import each other. Future iOS app imports only koan-core.
Fixed
- GraphQL connections — disabled
nodesshortcut field on Relay connections, edges-only for consistency. (#166)
0.20.4
Fixed
- Bit depth hidden for lossy codecs — Opus, Vorbis, AAC, and MP3 no longer show a fake "32bit" in the transport bar.
bit_depthis nowOption<u16>—Nonefor lossy codecs, displayed only for lossless (FLAC, ALAC, WAV, AIFF). Transport shows"Opus 48000Hz/2ch"instead of"Opus 48000Hz/32bit/2ch".
0.20.3
Added
- Opus codec support —
.opusfiles now play correctly. Usesopus-decoder(pure Rust, RFC 8251) to bridge Symphonia's Ogg demuxer with a real Opus decoder. Pre-skip trimming, 48 kHz output, ReplayGain scanning all handled. Closes #149. - Secrets-in-git startup check — on launch, koan checks if config files containing passwords are tracked by git. If so, the app refuses to start and prints remediation steps (remove from git, add to .gitignore, rotate credentials). Hard panic, no bypass.
Changed
- Symphonia format support — added ADPCM codec, MKV/WebM and CAF container support.
Fixed
- Scan FK constraint error —
koan scanfailed withFOREIGN KEY constraint failedwhen removing stale tracks that had rows inlyrics_cache,play_history, ortrack_vectors. Now cleans all FK references before deleting. (#152) - Multi-instance state clobber — autosave is now event-driven (dirty flag) and throttled to 100ms. An idle koan window no longer overwrites the saved state of an active instance.
0.20.2
Changed
- Reactive background — beat-pulsing background color on braille modes (starfield, wormhole, kaleidoscope, lissajous, wireframe, spiral) moved behind
[visualizer] reactive_bg = falseconfig flag instead of being removed. Off by default.
0.20.1
Added
- Symphonia format support — added ADPCM codec, MKV/WebM and CAF container support. Opus decoding is not yet supported (see #149).
- BPM detection — beat onset interval tracking with median estimation. Stored on VisualizerState for future use. Resets on track changes.
Fixed
- Matrix rain character flicker — characters no longer flash/disappear globally. Each position flickers independently at ~2hz with staggered phase offsets.
- Matrix rain speed — reverted post-release speed experiments. Back to the v0.20.0 formula (band energy + beat + bass) with time-based frame_dt scaling so speed is consistent across different FPS targets.
- Reactive background removed — the beat-pulsing background color on braille modes (starfield, wormhole, kaleidoscope, etc.) looked flickery. Transparent background integrates better with the TUI.
- Pleasures layout — artist/album text properly spaced with blank lines above and below. Waveform box no longer clips peaks at the top (height scale capped per ridgeline). Raised cosine window tapers ridgelines to flat baselines at the edges.
- Animation timing — all visualizer animations now use actual frame delta time instead of hardcoded 1/60. Consistent speed at 30fps, 60fps, or 120fps.
0.20.0
Added
22 visualizer modes, up from 5 — cycle with
Mor use the new picker (v). PressFfor fullscreen. All modes use the palette system, beat-reactive color/hue shifts, and drift.Analytical:
spectrogram(time×frequency heatmap with blue→yellow→red→white heat map, sqrt amplitude scaling),stereo(L/R waveforms stacked top/bottom),vu(dual analog needle meters with ballistic physics),flame(filled spectrum curve with 8 stacked decay trails).Winamp-inspired:
plasma(overlapping sine waves, audio-reactive parameters),tunnel(polar fly-through with ring/stripe texturing),wireframe(3D torus mesh with spectrum-modulated vertices, perspective projection),metaballs(6 implicit surface blobs driven by spectrum bands),starfield(1500 3D stars with perspective projection, bass-driven speed, motion trails),pleasures(pure white ridgelines from spectrum history with raised cosine window, artist/album labels).Psychedelic:
moire(three rotating line grids, interference patterns),kaleidoscope(8-fold symmetry mirror of spectrum-driven radial patterns),julia(Julia fractal with audio-driven complex constant, smooth escape coloring),spiral(Archimedean spiral arms modulated by spectrum),interference(concentric wave sources, ripple moiré),wormhole(3D wireframe tunnel fly-through with procedural geometry, background stars).Special:
matrix(authentic cmatrix-style digital rain with katakana characters, per-column spectrum-mapped fall speed, beat-spawned clusters).Visualizer picker modal — press
vto open a fullscreen picker. Arrow keys scroll with live preview in the background. Enter confirms, Esc reverts.Mstill cycles directly. (#147)Matrix overlay — press
Xto toggle. Post-processing pass that replaces all rendered characters with random matrix glyphs in green, preserving the spatial structure. Works on any visualizer mode. Config:[visualizer] matrix_overlay. (#147)Bass shake — camera jitter + scale pulse on bass hits. Applied to braille-rendered modes (oscilloscope, radial, wireframe, starfield, lissajous, wormhole, kaleidoscope, spiral). Press
Sto toggle. Config:[visualizer] bass_shake = true. (#147)Reactivity config —
[visualizer] reactivity(0.0–2.0, default 1.0). Scales all beat/spectrum-driven animation coefficients. Crank to 2.0 for DnB, dial to 0.3 for ambient. (#147)Beat-reactive backgrounds — starfield, wormhole, kaleidoscope, lissajous, wireframe, spiral get a subtle pulsing background color that shifts with beat hue offset. (#147)
Drag-to-resize transport bar — click and drag the bottom edge of the transport/album art area to resize it. Makes more room for the visualizer or enlarges album art. Persisted to config. (#147)
Changed
- Braille rendering — all braille cells now rendered bold with +25% brightness boost to compensate for dot sparsity. (#147)
- Spectrogram — dedicated heat map colorscale (blue→yellow→red→white) with sqrt amplitude scaling for full dynamic range. No longer uses the palette system. (#147)
0.19.5
Added
- Four new visualizer modes — cycle with
Mkey through nine total modes. New additions:spectrogram(time×frequency heatmap scrolling vertically, block characters for density),stereo(L and R waveforms stacked top/bottom with warm/cool palette split),vu(dual analog needle meters with arc scale, tick marks, and ballistic needle physics — fast attack, slow decay),flame(filled area under the spectrum curve with 8 stacked decay trails creating a layered mountain/fire effect). All modes use the existing palette system, beat-reactive color shifts, and dreamy drift. Config:[visualizer] mode = "spectrogram"(orwaterfall,stereo,vu,meter,flame,mountain). (#146)
0.19.4
Fixed
- Braille visualizer modes running at ~11fps instead of 60fps — the decode thread pushed entire packets to the visualization buffer in one shot, then blocked waiting for the audio ring buffer to drain. For FLAC (4096 frames/packet at 44.1kHz), VizBuffer only got fresh data every ~93ms (~11fps). Spectrum bars hid this with decay smoothing, but waveform-based modes (oscilloscope, lissajous, radial, particles) rendered the same frozen samples 5-6 frames in a row before jumping. VizBuffer writes now happen incrementally inside the ring buffer push loop, paced by the audio callback's real-time consumption rate. All visualizer modes now update at true 60fps.
- Double-smoothed spectrum bars — the TUI applied its own decay smoothing on top of the analyzer's, making transients mushier than intended. Spectrum, peaks, and VU levels now pass through directly from the analyzer thread (single layer of smoothing). Beat energy retains local decay for the hue-shift effect.
0.19.3
Fixed
- Incomplete downloads can't corrupt the cache — downloads now write to a
.partfile and atomically rename on completion. Interrupted downloads are cleaned up, never mistaken for complete files. Size verification against Content-Length catches server-side truncation. Streaming playback reads from RAM (StreamBuffer) so the rename is invisible to the decoder. (#143)
0.19.2
Fixed
- Streaming playback fails on restored sessions with unmounted volumes — when a track's original local path no longer exists (e.g. volume unmounted), the streaming system tried to open the stale path instead of the cache download destination. Now updates the item path to the cache dest before downloading starts. Also checks if the local file came back (volume remounted) before re-downloading. (#140)
0.19.1
Added
- Braille visualizer modes — five rendering modes for the visualizer, switchable with
Mkey:bars(existing LED spectrum),oscilloscope(raw PCM waveform as braille line),radial(polar-coordinate spectrum starburst),particles(frequency-driven particle system with physics),lissajous(stereo phase scope with afterglow trail). All modes use a braille character grid (U+2800..U+28FF) for 2x4 subpixel resolution per terminal cell. Beat-reactive, palette-colored, existing color palettes and drift effects apply to all modes. Config:[visualizer] mode = "bars"(default). (#137)
0.19.0
Added
- Colorful spectrum analyzer — frequency-mapped rainbow replaces monochrome green. Four palettes via
[visualizer] palette:spectrum(default),fire,neon,mono. Dreamy 8-second color drift breathes the rainbow back and forth across the bars. Beat-reactive hue shifts snap the palette forward on kicks/transients. Brightness pulses on top. Peak markers glow in brightened palette colors. All color math in the render path — zero impact on audio threads. (#134, #135)
0.18.7
Changed
- Sample rate switching uses CoreAudio property listener instead of polling —
set_device_sample_ratenow registers anAudioObjectAddPropertyListeneronkAudioDevicePropertyNominalSampleRateand blocks on a oneshot channel instead of spinning every 10ms. Eliminates up to 10ms unnecessary latency per rate switch. Timeout bumped from 2s to 5s to cover USB Class 1 DACs doing PLL relock. Early-out when rate already matches, spurious callback verification, RAII listener cleanup. (#130)
0.18.6
Fixed
koan play /dirwith large libraries — for >1000 files, uses a singleall_tracks_by_pathDB query instead of hundreds of batchedWHERE INqueries. Directory walk + metadata resolution now runs on a background thread so the TUI starts immediately (#128)- Organize preview takes minutes on large libraries —
preview_for_pathsnow loads metadata from the DB (single query) instead of re-reading every file's tags from disk. Falls back to parallel disk reads (rayon) for files not in the DB. 48k-track library: ~5 minutes → ~3 seconds (#128)
0.18.5
Fixed
- Hi-res audio playing at wrong speed — CoreAudio sample rate switches are asynchronous, but the player read back the device rate immediately after requesting the change and got the old rate. A fallback (
unwrap_or(source_rate)) then masked the mismatch by lying to the ASBD. Result: 96kHz files played at quarter speed (device still clocked at the old rate, draining the ring buffer too slowly).set_device_sample_ratenow polls until CoreAudio confirms the switch (10ms intervals, 2s timeout) and returns the verified rate. Both file and streaming playback paths fixed. (#124)
0.18.4
Changed
- Now-playing queue indicator — playing track now shows ▶ instead of
>, with bold title text for visibility (#122)
Fixed
- Audio seize-up at album transitions — when the gapless decode loop exhausted the playlist, the Player had no way to know playback finished. Audio engine kept running, outputting silence. Now the decode thread signals
DecodeFinishedand the Player auto-advances or stops cleanly (#122) - Double engine restart at session restore — startup sent Play+Pause+Seek, causing three engine teardown/rebuild cycles. Now sets cursor without playback; the deferred seek is the single start point (#122)
- Key repeat rapid-skipping — terminal key repeat on
>/<could fire dozens of NextTrack/PrevTrack commands. Added 150ms debounce in the Player command loop (#122)
0.18.3
Changed
- CLI:
koan init→koan config init— config initialization is now a subcommand ofkoan config.koan configwith no subcommand still shows resolved config (#120) - Config init generates commented template —
config.tomlnow contains all defaults as commented lines for reference. Uncomment what you want to customize. No more silent duplication of values across config files (#120) [library]and[remote]excluded fromconfig.toml— machine-specific paths and credentials belong inconfig.local.tomlonly. Prevents accidental credential leaks into dotfile repos (#120)- ReplayGain default changed to
off— wasalbum. Users who want loudness normalization can opt in viareplaygain = "album"or"track"(#120)
Fixed
koan remote loginno longer bloatsconfig.local.toml— previously wrote all default config sections; now patches only the[remote]section, preserving the rest of the file as-is (#120)- Removed
Config::save()footgun — method could leak secrets from merged config intoconfig.toml. Replaced withConfig::patch_local(section, values)for targeted local config updates (#120) .gitignorenow covers*.db-waland*.db-shm— SQLite WAL files were previously not gitignored (#120)
0.18.2
Changed
- CLI:
koan playsubcommand — play-related args (paths,--album,--artist,--id,--library,--clear,--server,--jukebox) moved from the root command tokoan play. Running barekoanstill launches the TUI. This fixes zsh tab completions which broke when positional paths were on the root struct alongside subcommands (#116)
Fixed
Tab completions — zsh/bash/fish completions now correctly suggest subcommands instead of filesystem paths (#116)
Docs:
koan mcp— corrected all references from--mcpflag tomcpsubcommandDocs: removed fabricated Docker content — no Docker image exists
Docs: GraphQL operations table — fixed naming convention, added missing operations
Docs: radio mode scoring — corrected signal descriptions to match actual implementation
Docs: added missing CLI commands —
koan analyze,koan completions,scan --forceDocs: added missing
Vkeybinding for visualizer toggleDocumentation rewrite — slimmed README from 740 lines to a focused hook + install + quickstart + feature list + doc links. All detailed content moved to dedicated guides and references under
docs/:docs/getting-started.md— progressive first-time setup tutorialdocs/guide/— radio mode, remote servers, file organization, GraphQL API, MCP integration, headless serverdocs/reference/— configuration (all fields including previously undocumentedticker_fps,target_fps,show_fps,art_size,output_device), keybindings (every key in every mode), CLI referencedocs/recipes/— troubleshooting, cache management
0.18.1
Added
- API concurrency limit — GraphQL server now applies a tower
ConcurrencyLimitLayer(max 10 concurrent requests) to prevent mutation spam / DoS (#99) - Composite index on
tracks(album_id, disc, track_number)for faster album-ordered queries (#99) - Render callback drain on AudioEngine drop —
AudioOutputUnitStopcan return before the render callback finishes during sample rate switches. Addedin_callbackatomic flag and spin-wait inDropto ensure the callback has fully exited before tearing down buffers (#89) - Pending items never downloaded on session restore — the cache verify fix correctly marked missing files as
Pending, but never actually triggered downloads. Introduced a persistentDownloadQueuethat lives for the app's lifetime: session restore feeds pending items into it, and double-clicking a pending track triggers a priority download with stream-when-ready playback. The same queue replaces the one-shot scoped thread pool previously used byenqueue_playlist(#94) - GraphQL/Subsonic port bind panic —
run_api_blockingcalled.expect()on port bind, crashing the entire app onAddrInUse. Now logs a warning and gracefully disables the API server (#95) - TUI layout jump when album art loads — the transport bar now always reserves a 24×12 cell placeholder for album art, preventing layout reflow when art loads or when switching between tracks with/without embedded art (#96)
- Track
db_idin playlist items —PlaylistItemandPersistedQueueItemnow carrydb_id: Option<i64>, enabling re-download of remote tracks after session restore. Backwards-compatible: old persisted state withoutdb_iddeserializes cleanly via#[serde(default)](#94)
Changed
- Config loading uses figment — replaced hand-rolled TOML deep-merge with figment for layered config: defaults →
config.toml→config.local.toml→KOAN_*env vars. Any config field is now overridable via environment variables usingKOAN_SECTION__FIELDnaming (e.g.KOAN_REMOTE__PASSWORD,KOAN_GRAPHQL__PORT,KOAN_PLAYBACK__TARGET_FPS)
Fixed
Secret round-trip leak in config save —
save()on a merged Config would serialize secrets fromconfig.local.tomland env vars back intoconfig.toml. Callers now useConfig::update_base()which reads onlyconfig.toml, applies the mutation, and writes back without leaking sensitive fieldsPath traversal in organize —
sanitize_relative_pathnow strips..and.components, andplan_single_movevalidates the destination stays under the base directory. Prevents malicious metadata from writing files outside the library (#99)RT safety in CPAL audio callback — changed
Mutex::lock()totry_lock()in the audio render callback so the real-time thread never blocks; outputs silence on contention instead (#99)O(N) LRU cache query — replaced correlated
SELECT MAX(played_at)subquery per track with a singleLEFT JOINon pre-aggregated play_history (#99)Sequential scan_cache lookups — scanner now batch-loads the entire scan cache into a HashMap instead of issuing one DB query per file, dramatically faster for large libraries (#99)
Memory usage on playlist build —
playlist_items_from_pathsnow usestracks_by_paths()(batched IN-query) instead of loading every track in the library into a HashMap (#99)
0.18.0
Added
- CoreAudio crash during sample rate switch —
stop_engine()was dropping theAudioEngineon a background cleanup thread while the player thread immediately changed the device sample rate. The engine is now dropped synchronously before any sample rate changes; only the decode handle cleanup runs in the background (#89) - Cache management with LRU eviction — cached remote downloads are now tracked in the DB (path, size, download date). Set
cache_limitin[remote]config (e.g."50GB") to enable automatic LRU eviction on startup. Evicts whole albums, oldest last-played first. Favourited tracks are never evicted. Newkoan cache evictsubcommand for manual eviction (#88)
0.17.1
Added
- Album-aware download priority — when a track starts playing, remaining tracks from the same album are bumped to the front of the download queue, ensuring gapless album playback (#87)
- CONTRIBUTING.md — contribution guidelines (#82)
Fixed
- GraphQL/Subsonic servers now bind to 127.0.0.1 by default — previously bound to
0.0.0.0with no authentication, exposing library enumeration, file moves, and queue clearing to anyone on the network. Addedbindfield to[graphql]config and--bindCLI flag (#85)
0.17.0
Changed
- Unified daemon mode —
koannow runs TUI + GraphQL API in one process by default. No more separatekoan serve. All interfaces share one player, one state (#70)koan --headlessreplaceskoan serve(GraphQL API only, no TUI)koan -d/koan --daemonizeforks a headless background daemonkoan --mcpreplaceskoan mcp(MCP server on stdio)koan --no-apiopts out of the API server (TUI-only, old behaviour)koan --port,--subsonic,--playgroundconfigure the API from top-level- Play args (
--album,--artist,--id,--library,--clear,--server,--jukebox) moved to top-level —koan playremoved koan scan --analyzecombines scan + acoustic analysis in one pass
Removed
koan play—koanIS play. All args moved to top-levelkoan serve— replaced bykoan --headlesskoan graphql— dead alias, removedkoan mcp— replaced bykoan --mcpflagkoan pick— standalone picker removed, TUI has built-in pickers (p/a/r)koan artists,koan albums— usekoan searchor GraphQL queries
Fixed
Remote
- Replace hand-rolled ISO 8601 parser with chrono — the manual RFC 3339 parser in
remote/sync.rs(~70 lines) could panic on malformed input from Subsonic servers. Replaced withchrono::DateTime::parse_from_rfc3339()+ fallback patterns for common server quirks (missing timezone, fractional seconds, space separators). Added 11 unit tests (#74)
Audio
- Atomic ordering hardened —
samples_playedusesAcqRelon fetch_add,Acquireon loads.runningflag usesAcquire/Release. No moreRelaxedfor cross-thread state (#76) - Timeline lock ordering —
PlaybackTimeline::current_playback()now acquires the boundaries read lock first, then readssamples_playedinside that scope. Dead standalonechannels/sample_rateatomics removed (#76) - Alignment check in CoreAudio callback — replaced
debug_assert!with a runtime check that fills silence on misalignment instead of UB (#76) - Buffer bounds validation —
ptr::copy_nonoverlappinginengine.rsandcpal_backend.rsnow clamps to available space and fills remainder with silence (#76) - VizBuffer allocation reuse — added
VizBuffer::snapshot_into(&self, out: &mut Vec<f32>)to reuse caller's buffer instead of allocating per frame (#76)
Player
- Atomic ordering across player state — all cross-thread atomics (
playback_state,position_ms,playback_generation,playlist_version,bytes_written,quit_requested,metadata_refresh_pending,radio_mode,pump_written) upgraded fromRelaxedtoAcquire/Release/AcqRel(#78) - Undo stack O(1) eviction —
Vecreplaced withVecDequefor O(1)pop_front()instead of O(n)remove(0). Batch depth capped at 500 to prevent unbounded nesting (#78) - Seek underflow on short tracks — guard
max_ms > 5_000before subtracting safety margin, preventing short/partially-downloaded tracks from clamping seek to 0 (#78) - ClearPlaylist snapshot race —
stop_playback_and_clear_state()(engine teardown only) now runs before snapshotting the playlist for undo, then clears. Previouslystop()cleared the playlist before the undo snapshot was captured (#78)
TUI
- Terminal restoration on any thread panic — removed main-thread-only guard from panic hook. Terminal is restored (raw mode, alternate screen, mouse capture, bracketed paste, cursor) regardless of which thread panics (#77)
- Cursor clamping on queue mutation —
clamp_queue_cursor()called afterdelete_selected()and on every playlist version change. Render-time clamp kept as safety net (#77) - Cover art cache bounded —
CoverArt::clear()frees theDynamicImagewhen nothing is playing (#77) - Double-click timeout clearing — stale
last_click_time/last_click_idxcleared after 1 second, preventing misinterpreted double-clicks (#77) - Picker cursor safety — render loop clamps cursor to
matched_countrange before computing scroll offset, preventing out-of-bounds when results shrink between ticks (#77)
Database
- Transaction boundaries —
upsert_track()wraps the entire artist/album/track/FTS5 operation in a savepoint. Scanner and analyzer use properunchecked_transaction()with error propagation instead of silentlet _ =drops (#79) - Source column validation —
CHECK (source IN ('local', 'remote', 'cached'))constraint on tracks table (#79) - WAL checkpoint on connect —
PRAGMA wal_checkpoint(PASSIVE)at connection open prevents unbounded WAL growth across sessions (#79) - LIKE wildcard escaping —
remove_stale_tracksnow escapes%,_, `` in path prefixes viaescape_like()(#79) - Missing index — added
idx_library_folders_pathonlibrary_folders(path)(#79)
Misc
- Batch ID collision —
chrono_batch_id()usesas_nanos()instead ofas_millis()to prevent millisecond-resolution collisions (#75) - Unicode-aware string comparison —
stricmpformat function uses.to_lowercase()instead of ASCII-onlyeq_ignore_ascii_case()(#75) - Ancillary file move errors logged —
execute_single_move_no_dbnow logs warnings vialog::warn!instead of silently swallowing with.ok()(#75) - Tokio features scoped —
"full"replaced with["rt-multi-thread", "net", "macros", "signal"]in koan-music (#75)
0.16.0
Changed
- GraphiQL v2 — replaced deprecated GraphQL Playground with the official GraphQL Foundation IDE. Actively maintained, subscription-ready, better UX.
koan serve --playgroundnow serves GraphiQL (#71) - Clean schema type names — stripped
Gqlprefix from all GraphQL types.GqlArtist→Artist,GqlTrack→Track,GqlNowPlaying→NowPlaying, etc. The public schema now has clean, idiomatic names
0.15.0
Added
- Linux audio support —
AudioBackendtrait abstraction withCpalBackend(ALSA/PipeWire/PulseAudio via cpal) for Linux andCoreAudioBackendfor macOS. Bit-perfect gapless on both platforms. Decode pipeline untouched — backends are dumb ring buffer consumers (#58) koan serve— unified server command. GraphQL API (always on) + optional Subsonic REST (--subsonic <port>). Replaceskoan graphql. One process, one player, two interfaces (#55)- Subsonic REST API — 22 endpoints for third-party clients (play:Sub, Amperfy). Browsing, search, streaming with Range + proxy, cover art, star/unstar, scrobble, playlists (mapped to snapshots), genres. XML + JSON, MD5+salt auth (#55)
koan play --server— TUI client mode via GQL. Streams audio locally from a remotekoan serveinstance (#55)--jukeboxmode — server plays audio, client is remote control only (#55)- Acoustic similarity —
koan analyzegenerates 23-dim bliss-audio fingerprints. Radio mode gainsSimilarityAxis::Acoustic.similarTracks(trackId, limit)GQL query (#68) - GraphQL API — full Relay-style cursor pagination, rich metadata filters (year, codec, genre, sample rate, bit depth, duration), fuzzy search, lyrics, cover art, organize, scan, sync, share mutations (#36)
- MCP server: GraphQL-first — 2 tools:
schema_sdl+graphql. Claude reads the schema, drives everything through one tool - Named queue snapshots — save/restore/list/delete via GQL + MCP. Bank curated mixes and switch between them
- Radio mode via API —
enableRadio/disableRadiomutations. SharedPlayerState atomic keeps TUI and API in sync - Favourites filter + remote sync —
favouritesOnlyon all queries,isFavouriteon tracks. Star/unstar auto-syncs to Subsonic/Navidrome [discovery]config —analysis_on_scan,acoustic_weightfor acoustic similarity tuning- Neural discovery (feature-gated) — DCLAP ONNX embeddings behind
neural-discoverycargo feature.textSearchGQL query,koan analyze --neural. Opt-in, graceful degradation (#69) - Cross-platform credentials —
keyringcrate replacessecurity-framework(macOS Keychain + Linux secret-service) - CI for Linux — clippy, test, build on macOS + Ubuntu. Release binaries: macOS arm64/x86_64 + Linux x86_64/arm64 (native runners)
Changed
- graphql.rs split — 2400-line file decomposed into
graphql/{mod,types,queries,mutations,helpers,server}.rs(#67) PlayerholdsBox<dyn AudioBackend>— all device/engine calls go through trait- SubsonicClient factory —
subsonic_client()helper replaces 9 manual creation sites (#65) - Player device restart dedup —
restart_on_current_track()+Config::load_or_default()(#62) - serve.rs route dedup —
register_subsonic_routes()shared between prod and test (#61) - Platform-gated deps —
coreaudio-sys/core-foundationmacOS-only,cpalLinux-only
Fixed
- Remote tracks silently skipped — GQL mutations now trigger background downloads. Correct cache paths via
resolve_item_path()(single code path with TUI) restoreSnapshotdownloads — snapshot restore now runs the download pipeline likeaddToQueue- N+1 query elimination — genre/favourite filtering uses batch SQL instead of per-item calls (#64)
- GraphQL injection — query building converted from
format!()to proper variables (#63) - Remote bridge hardening — exhaustive
PlayerCommandmatch, incomplete downloads marked Failed, 30s HTTP timeouts (#60) - Linux: ALSA/JACK stderr spam — cpal backend probe output suppressed via fd redirect during all operations
- Linux: Ctrl+C terminal restore — second Ctrl+C force-restores raw mode and exits immediately
- Scanner: empty files — 0-byte files get clear error instead of confusing Symphonia probe messages
--playgroundflag — changed fromOption<bool>to proper flaginsert_in_queue— was silently appending, now usesInsertInPlaylist- Ctrl+C on GQL server — graceful shutdown via
tokio::signal::ctrl_c
0.14.0
Added
- Acoustic similarity —
koan analyzegenerates 23-dim acoustic fingerprints (tempo, timbre, chroma, spectral features) via bliss-audio. Stored in SQLite, brute-force KNN is sub-millisecond. Radio mode gainsSimilarityAxis::Acoustic— finds tracks that sound similar regardless of metadata.similarTracks(trackId, limit)GraphQL query for "more like this" [discovery]config section —analysis_on_scan(run analysis during library scan, default false) andacoustic_weight(scoring weight for acoustic signal)- Empty file handling — scanner skips 0-byte files with a clear error instead of confusing "probe reach EOF" messages
0.13.1
Changed
- graphql.rs split — 2400-line god file decomposed into
graphql/{mod,types,queries,mutations,helpers,server}.rs
Fixed
- N+1 query elimination — genre and favourite filtering now use batch SQL queries instead of per-item DB calls. O(1) instead of O(n*m) on large libraries
- Remote bridge hardening — exhaustive PlayerCommand match (compiler catches new variants), incomplete downloads marked as Failed instead of Ready, 30s HTTP timeouts
- GraphQL client injection fix — all query building converted from format!() string interpolation to proper GraphQL variables
- Player device restart dedup — extracted shared restart logic, config load errors now logged instead of silently swallowed (
Config::load_or_default()) - SubsonicClient factory — single
subsonic_client()helper replaces 9 manual construction sites, 30s timeout on all HTTP clients - serve.rs route dedup — extracted
register_subsonic_routes(), test router no longer duplicates prod routes - CI reliability — arm64 cross-compile no longer silently fails, tags not force-pushed, doc tests added
0.13.0
Added
- Linux audio support —
AudioBackendtrait abstraction withCpalBackend(ALSA/PipeWire/PulseAudio via cpal) for Linux andCoreAudioBackendwrapper for macOS. Bit-perfect gapless playback on both platforms. The decode pipeline and ring buffer are untouched — backends are dumb consumers koan serve— unified server command. GraphQL API (always on) + optional Subsonic REST (--subsonic <port>). Replaceskoan graphql(kept as hidden alias). One process, one player, two interfaces- Subsonic REST API — 22 endpoints for third-party client compatibility (play:Sub, Amperfy). Browsing, search, streaming with Range support, cover art, star/unstar, scrobble, playlists (mapped to snapshots), genres. XML + JSON, MD5+salt auth. Proxy streaming for remote tracks
koan play --server— TUI client mode. Connects to a remotekoan servevia GQL. Client streams audio locally from the server--jukeboxmode — server plays audio, client is remote control only- GQL client library in koan-core — typed helpers for all queries and mutations
- Cross-platform credentials —
keyringcrate replacessecurity-framework. macOS Keychain + Linux secret-service - CI builds for Linux — clippy, test, build on both macOS and Ubuntu. Release binaries for macOS arm64/x86_64 + Linux x86_64/arm64
Changed
PlayerholdsBox<dyn AudioBackend>instead of direct CoreAudio FFI- Platform-gated deps:
coreaudio-sys/core-foundationmacOS-only,cpalLinux-only
0.12.5
Fixed
- Remote tracks now play when queued via GQL/MCP — two-part fix:
- GQL mutations now trigger background downloads for remote tracks (0.12.4)
- Remote tracks now get the correct cache path via
resolve_item_path()— same code path as the TUI
0.12.4
Fixed
- Remote track download pipeline wired to GQL mutations —
addToQueueandreplaceQueuenow spawn background downloads for remote tracks using the same pipeline as the TUI
0.12.3
Added
lyrics(trackId)query — fetch synced LRC or plain text lyrics for any track. Checks embedded tags, sidecar.lrcfiles, and LRCLIB. Cached in DBcoverArt(trackId)query — extract embedded cover art as base64 with MIME type. Supports JPEG and PNGorganizePreview/organizeExecutemutations — preview and execute file renames using fb2k-compatible format strings. Supports per-track or whole-library operationsorganizeUndomutation — undo the last organize batchtriggerScanmutation — trigger a library rescan from the API. Returns added/updated/unchanged countstriggerRemoteSyncmutation — trigger Subsonic/Navidrome library sync from the APIcreateShare(trackIds, description)mutation — create Subsonic sharing links for tracks. Returns the public URL. Claude can now share what it's playing
0.12.2
Added
fuzzySearchGraphQL query — nucleo-powered typo-tolerant fuzzy matching for tracks, albums, and artists. Same engine as the TUI picker (and Helix editor). Returns ranked results.{ fuzzySearch(query: "aphx twn", kind: TRACK, limit: 10) { id name rank kind } }
0.12.1
Changed
- MCP server: GraphQL-first interface — stripped 40+ individual tools down to just 2:
schema_sdl(introspect the full schema) andgraphql(execute any query or mutation). All operations go through GraphQL now. Claude callsschema_sdlfirst to learn the API, then usesgraphqlfor everything. Cleaner, less context overhead, same capabilities
0.12.0
Added
- GraphQL API —
koan graphqlstarts a headless player with an HTTP GraphQL server (default port 4000). Full Relay-style cursor pagination on artists, albums, and tracks. One nested query replaces multiple MCP tool calls:{ artists(first: 100) { edges { node { id, name } } } }. Mutations for all playback control, queue management, favourites, and device switching. Optional GraphQL Playground UI atGET /graphqlwith--playgroundflag orplayground = truein[graphql]config - MCP
graphqltool — single tool on the MCP server that executes GraphQL queries in-process (no HTTP). Claude Desktop can now fetch artists, albums, and tracks with nested queries in one round-trip instead of fanning out across individual tools [graphql]config section —port(default 4000) andplayground(default false) in config.toml- Named queue snapshots — save/restore/list/delete named queue states via GQL mutations (
saveSnapshot,restoreSnapshot,deleteSnapshot) and MCP tools (save_snapshot,restore_snapshot,list_snapshots,delete_snapshot). Bank the techno, switch to hardcore, jump back. Stored in the DB (queue_snapshotstable) with queue JSON, cursor path, and playback position - Radio mode via API —
enableRadio/disableRadioGQL mutations andenable_radio/disable_radio/radio_statusMCP tools. Radio mode was previously TUI-only (Shift+R). Uses SharedPlayerState atomic so TUI and API stay in sync - Favourites filter —
favouritesOnly: trueparameter onartists,albums, andtracksqueries. Dedicatedfavouritesquery with cursor pagination.isFavouritefield on track type - Favourite → remote sync — favouriting/unfavouriting via GQL or MCP automatically syncs to Subsonic/Navidrome (
star/unstarAPI) on a background thread. Fire-and-forget, best-effort clear_deviceMCP tool — reset audio output to system default (was GQL-only)- Daemon mode —
koan graphql -dforks the server into background, writes PID to~/.config/koan/graphql.pid. Claude Code can start it and query via HTTP schema_sdlMCP tool — dumps the full GraphQL schema in SDL format so Claude can introspect all available queries, mutations, types, and filter params on first connectsimilarArtistsquery — returns scored similar artists (from ListenBrainz, MusicBrainz, Subsonic) with source and relationship typeplayHistoryquery — recent play history with track info, paginated- Comprehensive MCP instructions — rewritten server instructions guide Claude through discovery, the graphql power tool, all filter params, snapshots, radio, favourites, and device control
- Rich metadata filters on all queries — albums:
title,yearStart/yearEnd,codec,label,genre. Tracks:title,artistName,albumTitle,genre,codec,yearStart/yearEnd,minSampleRate,minBitDepth,channels,minDurationMs/maxDurationMs. Artists:genre. All string filters case-insensitive substring
Fixed
insert_in_queueMCP tool — was silently appending instead of inserting after the specifiedafter_queue_item_id. Now usesInsertInPlaylistcommand directly--playgroundCLI flag — wasOption<bool>requiring--playground true. Now a proper flag- Ctrl+C on GraphQL server —
axum::servewas blocking forever. Addedwith_graceful_shutdownusingtokio::signal::ctrl_c
0.11.1
Fixed
- MCP server crash on startup — all tool return types now use object schemas (MCP 2025-11-25 spec requires
outputSchemaroot type to beobject). Bare string and array returns replaced withStatusResponse,QueueResponse,TrackListResponse,ArtistListResponse,AlbumListResponse,DeviceListResponsewrapper types
Tests
- 32 MCP server tests — coverage for all playback commands, queue management (add/remove/clear/replace/reorder), library discovery (search, list_artists, list_albums, list_tracks, get_track, library_stats), state queries (now_playing, list_devices, set_device), UUID parsing, track resolution, and error paths
0.11.0
Added
- MCP server —
koan mcpruns koan as a headless MCP (Model Context Protocol) server on stdio, controllable by Claude Desktop or any MCP client. Exposes 21 tools: playback control (play/pause/resume/stop/next/previous/seek), queue management (add/insert/remove/clear/replace/reorder/get), library discovery (search/list_artists/list_albums/list_tracks/get_track/library_stats), state queries (now_playing/list_devices/set_device), and favourites (favourite/unfavourite/list_favourites). The LLM provides the taste and reasoning — koan just exposes the controls. Configure in Claude Desktop with{"command": "koan", "args": ["mcp"]} - Visualiser toggle — press
V(Shift-V) to enable/disable the spectrum visualiser at runtime. Persists to config.toml. Visible in?help menu under Toggles - Multi-signal radio mode — radio now uses ListenBrainz ML similarity, MusicBrainz relationship graph (collaborators, band members, associated acts), Subsonic, genre/era matching, and play history to pick tracks across multiple axes instead of just one source. Drifting seed window follows your recent plays instead of anchoring to a single track. Recency scoring surfaces buried gems (never-played and long-forgotten tracks get a discovery bonus). New config options:
history_window(don't repeat last N, default 200),seed_window(last N plays as seed, default 5),discovery_weight(0.0-1.0, default 0.3) - Play history tracking — koan now records track completions in a
play_historytable, used for recency scoring in radio mode and future scrobbling
0.10.0
Added
- Radio mode — press
Rto toggle infinite play. When the queue runs low, koan automatically picks similar tracks using SubsonicgetSimilarSongs2(when a remote server is configured), cached similar-artist relationships, and genre/artist matching from the local library. A magentaRADIObadge appears in the hint bar when active. Configurable via[radio]in config.toml (lookahead, batch_size, use_subsonic)
0.9.2
Fixed
- UI freeze on track change —
stop_engine()no longer blocks the player command loop waiting for the decode thread to join. Engine teardown (thread join + AudioUnit dispose) is moved to a background cleanup thread, so the player stays responsive even when CoreAudio or I/O is slow to shut down - Escape sequence dump on crash — the panic hook was calling
disable_raw_mode()andLeaveAlternateScreenfrom whichever thread panicked, corrupting the terminal when a background thread (decode, download) hit an error. The hook now captures the main thread ID at install time and only restores terminal state from the TUI thread - Decode thread panic on missing file —
SourceEntry::from_fileusedpanic!when a file couldn't be opened (e.g. deleted during gapless lookahead). Themake_mssclosure is now fallible (-> io::Result), and decode errors are logged gracefully instead of crashing - AudioEngine drop race — removed unreliable
thread::yield_now()beforeAudioUnitUninitialize.AudioOutputUnitStopis synchronous (callback guaranteed finished on return), so no extra wait is needed. The callback is also explicitly removed as a safety net for the rare case where stop fails - Silent decode thread panics —
DecodeHandle::stop()now logs the panic message instead of silently swallowinghandle.join()errors
0.9.1
Added
- Queue persistence — queue and playback position are automatically saved every second and restored on next launch. Ctrl+C and
qboth trigger a clean save. Use--clearto start fresh instead of restoring - Graceful Ctrl+C — replaced raw
SIG_DFLwith a safe signal handler so Ctrl+C performs a clean shutdown (saving state, restoring terminal) instead of killing the process
Fixed
- Quit race condition — quit handlers were sending
PlayerCommand::Stop(which clears the playlist) before saving state, so persisted queue was always empty. Stop is now sent after saving
0.9.0
Added
- Navidrome share links — right-click a song or album header in the queue and select "Share link" to create a public sharing URL via the Subsonic API. The link is copied to clipboard and shown in the hint bar. Prefers album-level shares when all selected tracks are from the same album. Requires
[remote]to be configured with sharing enabled on the server - Double-click album headers — double-clicking an album header in the queue now starts playback from the first track of that album
0.8.2
Added
- Homebrew tap —
brew install radiosilence/koan/koan. Formula auto-updates on each release via CI
0.8.1
Added
- Help modal — press
?to open a two-column keybindings reference showing all modes (playback, navigation, queue edit, picker, library). Status bar now shows only high-priority hints; full reference lives in the modal
0.8.0
Added
- Output device selector — press
Shift+Dto open a modal listing all available CoreAudio output devices. Current device is marked with a green bullet. Selecting a device switches playback immediately (preserving position and pause state). Choice is persisted to[playback] output_devicein config.toml and restored on startup, with automatic fallback to system default if the device is unavailable
Fixed
- Stale album codec after format upgrade — upgrading files from MP3→FLAC (or any format change) now correctly updates the album's codec in the picker. Previously
get_or_create_album()only set codec on first insert, so the album row kept the old format even after all tracks were re-scanned - Streaming tracks skip mid-playback — two issues causing premature track advancement during streaming: (1) the pump thread treated
read() → Ok(0)as EOF even when the download reported more bytes available (OS buffer flush lag), now retries instead of breaking; (2)refresh_track_metadata(called when download completes mid-stream) didn't updateTrackInfo.duration_ms, leaving the UI with an underestimated duration from the initial 256KB partial probe — now re-probes the complete file
0.7.2
Fixed
koan initleaks home directory into config.toml —library.folders(containing the resolved~/Musicpath) was written to the shareableconfig.tomlinstead ofconfig.local.toml. Nowconfig.tomlomitslibrary.foldersentirely, andconfig.local.tomlgets the detected music directory as a starting point
0.7.1
Fixed
- Resilient tag parsing — files with corrupted tags (e.g. malformed UTF-16 ID3 frames) no longer fail the entire scan. When lofty errors, falls back to Symphonia for duration/codec/properties and indexes the file with whatever metadata is available
- Suppressed library log spam — noisy warn-level messages from lofty/symphonia internals are filtered from stderr (still written to log file). Fallback warnings from koan include the file path for diagnostics
0.7.0
Added
- DB cache for playlist loading — when adding files that are already in the library database, metadata is pulled from SQLite instead of re-reading from disk, making re-adds near-instant
- Scan progress bar —
koan scannow shows a clean inline progress indicator with track count and rate (e.g.• 1234 scanned (567/s)) instead of per-track log spam - Library source indicator — tracks in the TUI library browser show a colored icon indicating whether they are local (green HDD) or remote (cyan cloud)
0.6.3
Added
- Sub-pixel scrollbar — scrollbar thumb renders at 1/8th-cell resolution using Unicode block elements for smooth visual movement
- Parallel disk scanning — adding files from disk now uses rayon for parallel metadata reads, significantly faster for large collections
Fixed
- Scrollbar tracking with album headers — scrollbar now accounts for album header lines in its position/size calculations, fixing drift when dragging and inability to scroll to the end
- Mouse wheel scroll bounds — wheel scrolling now correctly bounds against the display line count (including album headers) instead of just the entry count
0.6.2
Added
- WebP cover art support — cover art in WebP format (embedded or external) is now decoded and displayed
0.6.1
Added
- Organize file path diff — organize modal now shows a before/after visual diff of file paths, highlighting changed path segments in green
- Ctrl-A select all — select entire playlist from normal mode (enters edit mode) or edit mode
- Album header context menu — right-click on album headers to apply actions (organize, remove, favourite, etc.) to the whole album group
Fixed
- ALAC codec detection — MP4 files containing ALAC audio are now correctly identified as ALAC instead of AAC, using lofty's
Mp4Filecodec probe - Unicode string slicing panics — fixed two panics in organize path diff caused by byte-slicing fullwidth/CJK characters; all path helpers now use char-based operations
- Modal mode restoration — context menu and organize modal now use a mode stack (push/pop) instead of hardcoding return to edit mode; closing a modal returns to whatever mode was active before opening it
Tests
- Unicode torture tests — comprehensive coverage for fullwidth Japanese, CJK, emoji (ZWJ, flags, skin tones), Arabic bismillah, Zalgo/combining diacritics, and extreme combining mark sequences
- ALAC codec tests — fallback tests for
mp4_codec()plus integration test against real ALAC files - Organize path diff tests — coverage for
common_path_prefix,shared_prefix_len,truncate_pathhelpers
0.6.0
Full codebase audit of v0.5.2 covering security, performance, architecture, dependencies, and test coverage. Every change was reviewed individually and as a combined integration.
Changed
- Render loop allocations eliminated — playlist version gate skips redundant O(n) visible queue rebuild when queue is idle; borrowed string keys in display line builder remove 2 allocations per entry per call; spectrum data changed from heap Vec to stack arrays ([f32; 48]) eliminating allocation on every frame clone at 60fps
- Symphonia codec features scoped — replaced blanket
features = ["all"]with only the codecs koan actually uses (FLAC, MP3, AAC, Vorbis, Opus, ALAC, WavPack, WAV, AIFF), reducing compile time row_to_track_rowhelper — deduplicated 4 identical 22-line row-mapping closures in tracks.rs into a single shared functionplan_single_movehelper — extracted shared move-planning logic (path formatting, sanitization, extension preservation, ancillary file handling) from twoplan_movesvariants in organize.rs- rusqlite removed from koan-music — 3 raw SQL calls replaced with koan-core query functions (
album_date,clear_cached_paths). Binary crate no longer links rusqlite directly - rusqlite features scoped —
bundled-full→bundled, removing unused extensions (load_extension, backup, blob, hooks, session) - Workspace dependencies — added
[workspace.dependencies]for rusqlite and walkdir, centralizing version management
Removed
- Dead code cleanup — removed 6 unused functions/fields:
LyricsState::clear,CoverArt::centered,scrollbar_hovertheme field,event.rsmodule,VisualizerState::num_bars, 3 unusedHoverZonevariants
Fixed
- Security hardening — credentials removed from stored remote URLs (reconstructed from config at playback time), config and DB files restricted to 0o600 on Unix, FTS5 and LIKE query inputs sanitized, HTTPS warning for non-localhost remotes, secure random salt via
getrandom, PID-namespaced cover art temp files - Streaming duration display — seek bar metrics now use the DB-sourced track duration instead of the probed partial-file duration, so elapsed/total and click-to-seek are correct during streaming playback
Tests
- Test coverage expanded — 332 → 371 tests. Added coverage for PlaybackTimeline (6), SharedPlayerState (12), favourites (8), Subsonic client (5), metadata probe (5). Removed 4 AI-generated duplicate streaming tests
0.5.2
Fixed
- Drag reorder selects wrong track — dragging a single track up/down no longer switches selection to the displaced track. The dragged track's ID is now captured before the move instead of reading from the stale visible queue cache
0.5.1
Added
- ReplayGain playback support — track and album ReplayGain tags are read via lofty at decode time and gain is applied with peak limiting. Configure via
[playback] replaygain(track,album, oroff) andpre_amp_dbin config.toml. Zero overhead when disabled - Streaming seek bar — during streaming playback the seek bar dims the not-yet-downloaded portion. Downloaded section renders as a solid line that grows as the download progresses. Seeking past the downloaded point is prevented (click, keyboard, and core seek all clamped)
- Accurate duration for streaming tracks — transport bar now prefers the database-sourced track duration over the probed partial-file duration, so elapsed/total always shows the real track length
Fixed
- TIFF cover art rejected — embedded TIFF artwork is now skipped during extraction, falling back to the next JPEG/PNG picture. Fixes
CGImageDestinationFinalize failederrors on macOS Now Playing - Spectrum peak markers hidden by bars — peak hold markers now render on top of bar fill instead of being overwritten
0.5.0
Added
- Spectrum analyser — 80s hi-fi LED-segment style spectrum visualiser renders above the transport bar when album art is present. 48-band FFT with configurable frequency scale (Bark/Mel/Log/Linear), eighth-block sub-cell resolution, green/yellow/red gradient, peak hold markers, and time-based exponential decay
- Dedicated analysis thread — FFT runs on a background thread (
VizAnalyzer) decoupled from both the decode and UI threads. The UI reads a pre-computedVizSnapshotevery frame with sub-microsecond lock hold times, keeping FFT work off the render thread - VizBuffer audio tap — circular sample buffer shared between decode thread and analysis thread via
parking_lot::Mutex - FFT pipeline — 2048-point real FFT via
realfftcrate. Hann window, dB magnitude scaling, Bark/Mel/Log/Linear frequency scales - A-weighted amplitude scaling — bars reflect perceived loudness using IEC 61672 A-weighting, matching human hearing sensitivity (Fletcher-Munson curves). Configurable via
amplitude_scale:aweight(default),perceptual(A-weight + gamma),sqrt,linear - Signal-level coloring — spectrum bars are colored by amplitude, not position. Green at safe headroom, yellow when hot, red only near clipping (0dBFS)
- Visualiser config —
[visualizer]section withenabled,fps(default: 60),scale,amplitude_scale,bar_decay_ms(default: 50),peak_decay_ms(default: 180). Also accepts[visualiser]spelling - Spectrum theme colours —
spectrum_low(green),spectrum_mid(yellow),spectrum_high(red),spectrum_peak(white) in theme config - FPS overlay —
[playback] show_fps = truedisplays an FPS counter in the top-right corner
0.4.0
Added
- Streaming playback for remote tracks — playback starts after 256 KB is buffered instead of waiting for the full download. A
StreamingSourcebacked by a shared in-memory buffer feeds Symphonia while the download continues in the background. When the download finishes, full lofty metadata and cover art are re-read and media key info (souvlaki) is updated progressively - Vim-style navigation everywhere — pickers, library browser, and queue all support Ctrl+U/Ctrl+D (half-page), PageUp/PageDown, Home/End. Library also accepts j/k/h/l, g/G
- Wrap-around cursor — pressing Up on the first item wraps to the last, and Down on the last wraps to the first (queue, library, picker)
- Lyrics panel — press
Lto toggle a lyrics panel (60/40 split with queue). Fetches synced and plain lyrics from LRCLIB (zero-config, no API key). Synced lyrics highlight the current line and auto-scroll with playback - Lyrics DB caching — fetched lyrics are cached in SQLite so subsequent views are instant
- LRCLIB search fallback — when exact match (
/api/get) returns 404, falls back to fuzzy search (/api/search) by artist + title - Incremental remote sync —
koan remote syncnow only fetches albums newer than the last sync timestamp, dramatically reducing sync time. Use--fullto force a complete re-sync - Resilient stale track removal — when local files are removed, remote-backed tracks are demoted to remote-only (preserving streaming fallback) instead of being deleted entirely
Changed
- Fixed-timestep render loop — replaced tick-on-timeout event loop with a game-engine-style frame-deadline loop. Animations (ticker, spinner) no longer stall during mouse interaction or key holds
- Configurable frame rate —
[playback] target_fps(default: 60) controls TUI redraw rate. Accepts 30, 60, or 120 - Transport icons — play/pause/stop status icons use Unicode symbols instead of ASCII
Removed
- Event::Tick — tick variant removed from event enum. Ticking is now unconditional every frame
Fixed
- Standalone picker mouse support —
koan pick --artist/--albumnow enables mouse capture. Click to select, double-click to confirm, scroll wheel to navigate - Lyrics fetch on toggle — pressing
Lmid-track now fetches lyrics immediately. Previously, lyrics only loaded on track change - Lyrics error logging — fetch errors are now logged to stderr instead of being silently swallowed
- Favourites import for remote tracks — starred tracks from Navidrome now correctly import as local favourites. Previously, remote-only tracks (with no local path) were silently skipped during import
- Favourites sync error logging — errors from
getStarred2andimport_remote_favouritesare now surfaced instead of silently returning 0 - Event drain starvation — opening album art (or any slow render) no longer freezes the UI. The event loop now always polls for input even when behind on frame budget
- Cover art zoom performance — full-screen album art view no longer runs Lanczos3 resize every frame. Rendered output is cached and reused until terminal size changes
- Ticker double-speed after merge — duplicate ticker animation block from merge caused scrolling text to advance twice per frame
- Anchored drag reorder — dragging selected tracks now moves them anchored to the mousedown position instead of snapping to the top of the selection
- Album header drag — clicking and dragging an album header reorders the entire album group as a unit
- Play/pause click — clicking the status icon (play/pause indicator) next to the seek bar now toggles playback
- Download progress on all tracks — tracks before the playing position now correctly show download progress and status instead of being unconditionally marked as played
0.3.0
Added
- Ticker-style transport bar — when the artist/title text overflows the available width, it scrolls horizontally like a ticker banner. Album, year, and codec info stay fixed. Scroll speed is configurable via
playback.ticker_fpsin config (default: 8) - Favourites — press
fto favourite/unfavourite tracks. A yellow star (★) appears in the queue gutter. Persisted to SQLite. Available in the context menu too - Favourite sync — favouriting a remote track stars it on Navidrome.
koan remote syncnow pushes local favourites and pulls remote starred songs - Subsonic star/unstar/getStarred2 API — new SubsonicClient methods for managing server-side favourites
- Rich context menu — right-click (or
Spacein edit mode) opens a positioned context menu with Play, Favourite, Track info, Remove, and Organize actions. Hotkey shortcuts work within the menu - Mouse hover highlighting — queue and library items show underline on hover
- Event drain loop — mouse move events are coalesced so the UI always renders the latest cursor position
- HoverZone tracking — typed enum tracks which UI element (queue item, library item, seek bar, etc.) is under the mouse
Changed
- Scroll step reduced — mouse scroll wheel moves 1 line instead of 3
- Queue jump scroll —
/search now scrolls the matched track to near the top of the visible area (with album header) instead of keeping current scroll position
Fixed
- Scrollbar drag jump — clicking the scrollbar thumb no longer jumps to a wrong position. The grab offset within the thumb is tracked so dragging feels natural. Clicking the track area still jumps as expected
- Multi-select drag reorder — dragging multiple selected tracks no longer causes chaotic oscillation. Moves only trigger when the target is outside the current selection range
- Drag undo batching — one drag operation (single or multi-track) is now a single undo step instead of one per row crossed
0.2.3
Added
- Cover art in Now Playing — macOS Control Center shows embedded album art (extracted to temp file, passed as file:// URL to souvlaki)
- Seek from Control Center — absolute position, relative with duration, and direction-only (10s steps)
- Quit from Control Center — clean shutdown via atomic flag on SharedPlayerState
Removed
- Dead file watcher — notify/FSEvents module was implemented but never wired in. Removed watcher.rs, notify deps,
config.watchfield
Fixed
- mise binary name — release tarballs now contain
koaninstead ofkoan-macos-arm64, fixing mise installs
0.2.0
First public release. Full TUI rewrite, undo/redo, file organization, CI/CD pipeline.
Added
- Ratatui TUI — full-screen terminal UI with transport bar (click-to-seek), album-grouped queue, fuzzy picker overlay, library browser, track info modal with embedded album art (halfblock rendering), scrollbar, mouse support throughout
- Undo/redo — 100-deep undo stack covering all playlist operations (add, remove, move, clear).
Ctrl+Zto undo,Ctrl+YorCtrl+Shift+Zto redo. Batch operations (multi-delete, multi-move) undo as a single step - File organization — in-TUI organize modal: select tracks in edit mode →
Space→ Organize → pick a named pattern → preview → execute. Playlist paths update live, playback continues uninterrupted. Ancillary files move with the music - Format string engine — fb2k-compatible title formatting:
%field%references,[conditional]blocks,$function(args)calls. 30+ built-in functions (string, logic, numeric, path). 234 tests - Named organize patterns — define reusable patterns in config (
[organize.patterns]), set a default, pick from them in the TUI modal - Context menu —
Spacein edit mode opens action overlay (currently: Organize) - Drag/drop — drag files or folders from Finder into the terminal to add to the queue (bracketed paste)
- Queue editing — edit mode (
e) with Finder-style multi-selection (shift-arrows, option-click toggle, ctrl-click range), reorder (j/k), delete (d), multi-drag - Library browser — split-pane tree view (artists → albums → tracks), substring filter (
f//), click/double-click support - Picker actions —
Enterappends,Ctrl+Enterappends and plays,Ctrl+Rreplaces entire queue - Mouse support — double-click to play, click-to-seek, drag-to-reorder, scrollbar drag, scroll wheel, picker click/dismiss — works in every mode
- Priority play — double-click a downloading track to play it as soon as it finishes
- Media keys — macOS Control Center integration via souvlaki (play/pause, next/prev, now playing info)
- Track info modal —
ishows full metadata + audio format details + embedded album art - Cover art zoom —
zfor full-screen album art (halfblock rendering) - Dynamic shell completions —
source <(COMPLETE=zsh koan)for artist/album ID tab-completion from the DB - Parallel remote sync — album detail fetches parallelized with rayon, batch DB writes per page
koan init— scaffolds~/.config/koan/with config templates (organize patterns, playback defaults, library paths), database, cache dir, and.gitignorefor dotfile reposkoan pick— in-process fuzzy picker powered by nucleo (replaces fzf dependency).--album/--artistmodes with drill-down- CI/CD pipeline — test + clippy + fmt check, cross-compiled binaries (arm64 + x86_64), GitHub releases with auto-tagging, crates.io publishing (
koan-corethenkoan-music) - MIT LICENSE file
Changed
- Crate renamed —
koan-cli→koan-music(binary stayskoan), directorycrates/koan-music/ - Config path —
~/.config/koan/(was~/Library/Application Support/koan/) - Two-layer config —
config.toml(committable) +config.local.toml(gitignored) - Password storage — stored in
config.local.tomlviakoan remote login, not macOS Keychain
Removed
koan organizeCLI subcommand — file organization is now TUI-only (context menu → organize modal)- FFI/Swift layer — removed entirely, pure Rust
- fzf dependency — replaced with built-in nucleo fuzzy picker
Fixed
- Album picker adds wrong tracks — was passing album IDs as track IDs, now correctly expands via DB query
- Track artist vs album artist — stored separately in DB, compilations display correctly
- Seek past end of track — skips to next instead of crashing
- Scroll past end — queue scroll clamps correctly
- Scroll in modals — routes to active modal instead of always scrolling queue
- Library shows album artists only — no spurious entries from featured artists on compilations
- Crash on pick subcommand — fixed usize underflow race with
saturating_sub, added panic hook for terminal restore - Queue metadata for local tracks — was blank, now populated correctly
- Album header dimming — only dims when ALL tracks in group are played
0.1.0
Initial release.
- Bit-perfect CoreAudio playback (AUHAL, automatic sample rate switching)
- Gapless transitions
- Format support: FLAC, MP3, AAC, Vorbis, Opus, ALAC, WavPack, WAV/AIFF (Symphonia)
- Library indexing with rayon, SQLite FTS5 search
- Subsonic/Navidrome remote sync
- Track deduplication (path → remote_id → content match)
- CLI: play, scan, search, library, config, probe, devices, remote login/sync/status