- Rust 99.4%
- Nix 0.6%
| src | ||
| .envrc | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| config.example.yaml | ||
| default.nix | ||
| flake.lock | ||
| flake.nix | ||
| README.md | ||
| REMAINING_FEATURES.md | ||
| screenshot.png | ||
| screenshot_old.png | ||
| shell.nix | ||
sonic-tui
A terminal-based music player for OpenSubsonic and Navidrome servers, inspired by jellyfin-tui.
Table of Contents
- Features
- Changelog
- Requirements
- Installation
- Configuration
- Keybindings
- AI DJ
- Dependencies
- Troubleshooting
- License
- Acknowledgments
Features
- Page-based interface - Dedicated pages for Queue, Artists, Albums, Tracks, Playlists, Search and DJ with tab navigation
- AI DJ - Optional: hand playback to dj, a self-hosted radio backend that picks the rotation and talks between songs (details)
- Mouse support - Click to select items, click page tabs to switch, scroll wheel navigation
- MPRIS - Media keys, desktop media widgets and
playerctlcontrol playback on Linux - Now Playing view - Album art, track details and the queue, all sized to the terminal: a bigger window means bigger artwork and more columns per track, not more empty space
- Album art display - Sixel/Kitty protocol support for inline images
- Audio visualizer - Real-time waveform visualization
- Lyrics - Synced lyrics from server with LRCLIB fallback, toggleable karaoke view with current line highlighting
- Queue management - Add, remove, shuffle, reorder tracks, and save as playlist
- Advanced playback - Shuffle, repeat (all/one), radio mode (similar songs), and random mode
- Playlist support - Browse, create, edit, and delete playlists
- Search - Search across artists, albums, and songs
- Favorites - Star/unstar and browse your favorite artists, albums, and songs
- Playback history - Track and replay your listening history
- Statistics - View top songs/albums/artists and recently added albums
- Filtering & sorting - Filter and sort content by multiple criteria (name, year, artist, track, duration, album count)
- Lazy loading - Large libraries load progressively as you scroll
- Scrobbling - Server-side scrobbling support
- Gapless playback - Seamless transitions between tracks
- Command palette - Quick access to all commands with fuzzy search
- Custom keybindings - Remap keys to your preference
- Vim-style keybindings - Navigate with hjkl
Changelog
Unreleased
Now Playing, redesigned
- Album art scales with the window - The art column is now as wide as a square cover needs at the height available, instead of a fixed 35% that was sized by width while the art was sized by height — so most of the column was permanently empty and the cover never grew past three-quarters of the panel. A taller terminal now means a bigger cover, up to half the page. The square is measured against the terminal's real font size rather than an assumed 2:1 cell ratio, so covers are square on terminals with squarer cells too
- Covers are fetched at 1000px, not 300px -
Resize::Fitnever scales an image up past its natural size in cells, so the old fetch capped the artwork at roughly 37×19 cells however much room the panel had. This is also what goes to the desktop over MPRIS, where 300px looked poor in a notification - The queue shows more than titles - Track number, title, artist, album and duration, in columns that drop out as the panel narrows rather than all being squeezed. Played tracks are dimmed, the playing one is marked and accented, and the heading carries the position, the track count and how much is left to play
- The page owns its now-playing panel - Title, artist, album and year, a seek-style progress bar, transport state, mode indicators and volume, laid out under the artwork. The compact header stands down on this page, which is where the four extra rows for the artwork came from; every other page keeps it
- Mode indicators name your actual keys - Read from the keybindings rather than hardcoded, so the header can no longer claim
[r]adiowhen radio has always beenR. They shorten to symbols instead of disappearing when the line gets tight - Lyrics fade with distance from the line being sung, which is what makes an untimed wall of text readable as a position in a song
- The visualizer draws at sub-cell resolution using partial blocks, and only appears once the artwork already has room to spare
ui.accent_colorworks - Named,#rrggbbor palette-index; it was accepted in the config and then ignored.ui.show_cover_artis likewise honoured now- Missing artwork draws a placeholder rather than going blank, which read as a rendering fault and made the layout jump whenever a fetch failed
Bug Fixes
- Fixed startup taking up to twenty seconds - The DJ handshake and the playlist fetch were awaited before the interface was drawn, on a bare terminal. Measured against a real server, the DJ connection alone ranged from 0.8 to 9.4 seconds and
pingfrom 0.2 to 9. Neither is needed to draw a first frame: both now run behind one, the DJ page says it is connecting, and the connect that used to block startup is picked up as soon as it lands. The one remaining wait — the initial server ping, which is what reports a wrong password to a normal shell — now says what it is waiting for instead of sitting silent - Fixed DJ artwork rendering smaller than the space set aside for it - The DJ backend serves 500×500 covers with no way to request another size, and
Resize::Fitnever scales an image up past its own size in cells. Artwork below what the panel can use is now enlarged to fit, which also covers a Subsonic server that ignores thesizeparameter or an album whose original art is small - Fixed hours rolling into the minutes field - A queue's total time read as
184:12, and a position read back before mpv had loaded a file rendered as-1:-30 - Fixed clicking the progress bar toggling lyrics - The whole left panel was registered as the artwork's click target, not just the artwork
0.7.0
New Features
- MPRIS - sonic-tui now appears on the D-Bus session bus as
org.mpris.MediaPlayer2.sonic_tui, so media keys, GNOME/KDE media widgets andplayerctlall work. Play/pause, next, previous, seek, volume, shuffle and repeat are controllable; title, artist, album, track length and album art are published. Cover art is written to the local cache and shared as afile://URI rather than a Navidrome URL, which would carry your credentials onto the session bus. With no session bus (a bare TTY, a container) the player behaves exactly as before - AI DJ - Optional integration with dj (details): an eighth page picks a station, then the server drives the rotation and talks between songs. Love/like/dislike, add-to-playlist and skip all work on the playing track
password_command- Read the Navidrome (and DJ) password from an external command such aspass show navidrome, so no credential need sit in the config fileP- Add the playing track to a playlist (Acontinues to act on the selection)
Bug Fixes
- Fixed crash on non-ASCII text (#5) - Titles were truncated by byte index, which panics when the cut lands inside a multi-byte character (
byte index 59 is not a char boundary; it is inside 'ょ'). Whether it crashed depended on terminal width. All twelve truncation sites now measure and cut by terminal display width - Fixed column misalignment on CJK text (#5) - Durations drifted out of line because padding was computed from code-point counts, but Japanese, Chinese and Korean characters occupy two terminal columns each
- Fixed the saved queue restoring a months-old session - The queue was only written on a clean exit, so any session ending in a closed terminal or a crash saved nothing. It is now persisted on every track change and queue edit
- Fixed missing album art after a Navidrome rescan - Cover requests ignored the HTTP status, so a 404 from a regenerated media ID fed an error page to the image decoder and then recorded the fetch as done, preventing any retry
- Fixed radio mode stopping after the first batch - The refill check tested total queue length, which never shrinks as you play, so it never triggered
- Fixed karaoke never engaging when the server has lyrics - Plain server lyrics pre-empted LRCLIB, the only source of timed lyrics
- Fixed UI freezing on a slow server - Scrobbles were awaited on the render loop with a 30-second timeout, blocking both drawing and input
- Fixed the terminal being left unusable after a panic - A panic hook now restores the terminal before the message prints
- Fixed the log being wiped on every start - It is appended to, so the log from a crashed run survives
- Fixed same-titled albums merging in statistics - Album play counts keyed on title alone, so every Greatest Hits collapsed into one row
- Fixed a network error quitting the player - Almost every action reaches the server somewhere, and those errors propagated out of the event loop and ended the process. One slow response — pressing Enter on an album while the server was busy, or a radio refill on a flaky connection — quit mid-song. Failures now appear on the status line
- Fixed a crash when removing or reordering the queue - Starting radio, opening a playlist or playing an album replaces the queue without moving the selection, so a selection left over from a longer queue pointed past the end and
d/J/Kin Now Playing panicked - Fixed a crash on narrow terminals - The command palette applied a 30-column minimum width unconditionally, which underflowed below that and drew outside the screen buffer
- Fixed the terminal being left in raw mode when startup fails - Connecting now happens before the alternate screen is entered, and restoration runs on every exit path rather than only the clean one
- Fixed radio hammering the server - When a seed had no similar songs the refill condition never became false, so the same request went out about ten times a second for as long as radio was on
- Fixed DJ mode stalling in silence - A segment mpv could not open left the DJ idle forever with nothing on screen to explain it. Segments that never start are now skipped, and the DJ stops after three
- Fixed repeat-one only scrobbling once - History, "now playing" and scrobbling compared song ids, which cannot tell a replay from the play already running
- Fixed clicks selecting the wrong row - The renderer and the mouse handler each worked out the scroll offset independently and disagreed by one row on any scrolled list
- Fixed Ctrl+C clearing the filter instead of quitting - Modifiers were ignored entirely, so Ctrl+C matched the plain
cbinding. Ctrl+E no longer enqueues, Alt+S no longer shuffles - Fixed rebinding some keys doing nothing - Hard-coded keys were interleaved with configured ones and won by position, so binding
searchtojnever fired. The playlist manager could not be opened at all; it is now on the command palette - Fixed the help screen being unreadable past the fold - It is scrollable, lists your actual bindings, and no longer claims there are seven pages
Performance
- Large libraries no longer stutter - Every frame deep-copied the entire filtered list and formatted a row for each entry, visible or not. Rows are built only for what fits on screen, and filtering borrows instead of cloning
- Idle CPU is now zero - The interface redrew ten times a second whether or not anything had changed, including while paused with nothing on screen moving
- Artwork and lyrics no longer freeze the interface - Cover art, lyrics, DJ segment media and DJ history were all fetched on the render loop; a slow server blocked drawing and input for the length of the request
- Queue and history writes moved off the render loop, and the queue no longer grows without bound in radio and random mode
v0.6.0 (2026-03-11)
New Features
- Enhanced Statistics Dashboard - Press
Ito view:- Weekly activity bar chart showing listening time per day
- Listening streak counter (consecutive days)
- Artist diversity score (unique artists played)
- Peak listening hour
- Improved top songs/albums/artists display
- Number key navigation - Press 1-8 to jump directly to pages (Queue/Artists/Albums/Tracks/Playlists/Favorites/Search/DJ)
- Synced Lyrics Karaoke Mode - Press
Lor click album art to toggle lyrics view with real-time line highlighting - Command Palette - Press
:for quick access to all commands (navigation, playback, queue management) with fuzzy search - Search page improvements - Fixed search functionality with visible cursor and inline results
Bug Fixes
- Fixed double scrobbling - Plays are no longer sent to Navidrome/scrobblers twice
Removed
- Crossfade - Removed (was causing audio issues); gapless playback remains
- Discord Rich Presence - Removed due to unreliable IPC communication
UI Improvements
- Global now-playing header - Track info, progress bar, elapsed/remaining time, and mode indicators now appear at the top of all pages (not just Queue)
- Centered album art - Queue page album art is now properly centered in its panel, with automatic scaling for narrow terminals
- Shuffle restoration - Disabling shuffle now restores the original queue order instead of keeping the shuffled order
- Cleaner layout - Removed redundant bottom progress bar; all playback info is now in the header
v0.5 (2026-03-10)
UI Redesign
- Page-based navigation - Replaced multi-panel layout with dedicated pages: Queue, Artists, Albums, Tracks, Playlists, Favorites, and Search
- Tab bar - Bottom navigation bar shows all pages with icons, switch with Tab/Shift+Tab or click
- Queue page - Album art and song info on left, navigable queue list on right
- Favorites page - Three-column view of starred artists, albums, and songs with h/l navigation between columns
- Browse modals - Selecting an artist opens an albums modal; selecting an album opens a songs modal with track numbers and durations
- Mouse support - Full mouse support including:
- Click page tabs to switch pages
- Click list items to select
- Scroll wheel to navigate lists
- Works in all modals (search results, favorites, history, playlists)
- Lazy loading - Artists, Albums, and Tracks pages load progressively as you scroll, supporting very large libraries without startup delay. The chunk size is
ui.page_size(default 100, clamped 25-200) — enough to fill a tall terminal on first load without paying for the whole library up front
Improvements
- Session persistence - Queue and playback position are restored on startup (without auto-playing)
- Unified list navigation - All pages use consistent j/k/g/G navigation
v0.4 (2026-02-18)
Features
- Random mode - Press
Xto fill queue with random songs from your library. Auto-refills as you listen. Mutually exclusive with radio mode - Background prefetching - Cover art and lyrics for the next song are fetched in the background, eliminating UI stutter during track transitions
- Artwork/lyrics auto-update - Cover art and lyrics now properly update on automatic track advances (previously stayed stuck on first song)
Improvements
- Codebase refactor - Split monolithic
app/mod.rs(2,648 lines) into 7 focused submodules: library, playback, radio, modes, media, history, prefetch - New player method -
clear_queue_after_current()for preserving current playback while managing the queue
Configuration
keybindings.random- Keybinding for random mode (default:X)
v0.3.1 (2026-02-08)
Features
- Artist-level enqueue - Press
aon an artist to enqueue all their music at once (context-sensitive: works on artists, albums, and songs) - Improved sorting help - Help screen now shows all available sort modes for each panel (Artists: A-Z/Z-A/Count, Albums: A-Z/Z-A/Year/Artist, Songs: Track/A-Z/Z-A/Artist/Album/Duration)
- Centered help bar - Bottom quick reference bar is now centered for better readability
Improvements
- Performance optimization - Reduced CPU usage by ~80% (changed event loop from 60 FPS to 10 FPS)
- Optimized visualizer - Faster calculations using simple pseudorandom instead of hash operations
- Fixed scrobbling - Now properly sends "now playing" status to Navidrome/Last.fm in addition to scrobble at 90% completion
- Smooth track transitions - Removed blocking prefetch that caused UI freezes between songs
Documentation
- Added
CACHING_IMPLEMENTATION_PLAN.md- Detailed plan for implementing true background caching in the future
Requirements
- A terminal with Sixel or Kitty image protocol support (for album art)
- mpv (libmpv) for audio playback
- An OpenSubsonic-compatible server (Navidrome, Airsonic, etc.)
Installation
Using cargo
cargo install --git https://codeberg.org/thelinuxcast/sonic-tui
From source
# Clone the repository
git clone https://codeberg.org/thelinuxcast/sonic-tui
cd sonic-tui
# Build and install
cargo install --path .
The binary will be installed to ~/.cargo/bin/sonic-tui. Make sure ~/.cargo/bin is in your PATH.
NixOS
A shell.nix is provided for development:
nix-shell
cargo build --release
Or install directly with:
nix-shell
cargo install --path .
Configuration
Create a configuration file at ~/.config/sonic-tui/config.yaml:
server:
url: "https://your-navidrome-server.com"
username: "your-username"
password: "your-password"
audio:
volume: 100
max_bitrate: null # null for original quality, or set to 320, 256, etc.
gapless: true
ui:
show_cover_art: true
color_from_cover: false
accent_color: null # null for default, or hex color like "#ff5500"
show_visualizer: true
keybindings:
# Customize any keybinding by changing its value
# See config.example.yaml for all available keybindings
quit: "q"
help: "?"
search: "/"
# ... and many more
See config.example.yaml for all available configuration options and keybindings.
Keybindings
Note: All keybindings can be customized in config.yaml under the keybindings section. The keys listed below are the defaults.
Global
| Key | Action |
|---|---|
q |
Quit |
? |
Show help |
: |
Command palette |
/ |
Search |
\ |
Filter current list |
c |
Clear filter |
o |
Cycle sort mode |
P |
Playlists |
F |
Go to Favorites page |
H |
Playback history |
I |
Statistics & insights |
L |
Toggle lyrics view (replaces album art) |
f |
Now Playing view |
Space |
Play/Pause |
n |
Next track |
p |
Previous track |
s |
Toggle shuffle |
X |
Toggle random mode (add/remove random songs to queue) |
r |
Cycle repeat mode (off → all → one) |
R |
Toggle radio mode (similar songs) |
+ / = |
Volume up |
- |
Volume down |
Left / Right |
Seek backward/forward 5s |
S |
Star/unstar the selected item (loves the playing track in DJ mode) |
P |
Add the playing track to a playlist |
Page Navigation
| Key | Action |
|---|---|
Tab |
Next page |
Shift+Tab |
Previous page |
1-8 |
Jump to page (1=Queue, 2=Artists, 3=Albums, 4=Tracks, 5=Playlists, 6=Favorites, 7=Search, 8=DJ) |
| Pages | Queue → Artists → Albums → Tracks → Playlists → Favorites → Search → DJ |
List Navigation
| Key | Action |
|---|---|
j / Down |
Move down in list |
k / Up |
Move up in list |
h / l |
Switch columns (Favorites/Search pages) |
g |
Go to top of list |
G |
Go to bottom of list |
Enter |
Select / Drill in / Play |
Esc |
Back / Close modal |
Artists Page
| Key | Action |
|---|---|
' then A-Z |
Jump to artists starting with that letter |
' then 0-9 |
Jump to artists starting with a number |
Browse Modals
| Key | Action |
|---|---|
Enter |
Open artist's albums / album's songs |
e |
Enqueue selected item |
E |
Enqueue all items |
Esc |
Close modal |
Mouse
| Action | Effect |
|---|---|
| Click tab | Switch to page |
| Click item | Select item |
| Scroll wheel | Navigate list up/down |
Queue
| Key | Action |
|---|---|
e |
Add to queue |
E |
Add to queue (play next) |
a |
Add artist/album to queue (context-sensitive) |
A |
Add the selected song to a playlist (P adds the playing one) |
d |
Remove from queue (on Queue page) |
x |
Clear queue (on Queue page) |
J / K |
Move item down/up (on Queue page) |
w |
Save queue as playlist (on Queue page) |
Now Playing View
| Key | Action |
|---|---|
Tab / t |
Toggle lyrics/queue |
Esc / f / q |
Exit to main view |
j / k |
Navigate queue (when queue is shown) |
Enter |
Play selected song from queue |
Space / n / p / ← / → |
Playback controls still work |
Playlists
| Key | Action |
|---|---|
Enter |
Play playlist |
e |
Enqueue playlist |
d |
Delete playlist |
n |
Create new playlist (when adding song) |
Search
| Key | Action |
|---|---|
Tab |
Cycle between Artists/Albums/Songs |
Enter |
Select result |
Esc |
Close search |
AI DJ
Optional. Points sonic-tui at dj, a self-hosted AI radio backend that sits in front of the same Navidrome library — it owns the rotation, decides what plays next, and records spoken breaks between songs. You'll need it running somewhere first; see its README for setup.
Add a dj: section to your config and an eighth page appears:
dj:
url: "https://radio.example.com"
password_command: "pass show dj-radio" # or password: "..."
The DJ page is a station picker, nothing more. Press 8 (or Tab round to DJ), pick a station, hit Enter — and you land on Now Playing, because that's where anything that's actually playing belongs. Saved artist stations are listed first with ◈, genre stations below with ♬.
Once on air, the Now Playing page shows the DJ instead of the local queue:
- Left panel — album art for tracks; during a break, the DJ's script in full, with what's coming up after it. A break has no cover and no lyrics, so the panel has exactly one thing to show.
- Right panel — what the DJ has already played this session, skipped tracks dimmed. See below for why it isn't a list of what's next.
- Lyrics (
L) work normally on DJ tracks — they're your own library, so the usual Navidrome/LRCLIB path applies. Breaks have none.
All of these act on what's playing, and all work both on the normal pages and inside the Now Playing view (f):
| Key | Action |
|---|---|
Enter |
Start the selected station (DJ page) |
S |
❤ Love — stars it in Navidrome and gives it 3× selection weight |
> |
👍 Like — 1.5× weight |
< |
👎 Dislike — 0.1× weight, and skips |
P |
Add the playing track to a playlist |
n |
Skip — reported to the DJ so it weights the track down |
D |
Stop the DJ and hand playback back to the local queue |
Leaving DJ mode. D stops it explicitly, but you don't have to: playing anything locally — an album, a track, radio, random — ends DJ mode on its own. The two states are mutually exclusive by construction (DJ mode means there is no local current_song), and that contradiction is what's detected, rather than every play path having to remember to clear a flag.
| f | Now Playing view — j/k scroll history; everything above stays live |
P vs A. A adds whatever is selected in a list; P adds whatever is playing. P works during ordinary playback too — it's the only way to reach the DJ's current track, which by design never appears in a local list. During a break it says so rather than doing nothing, since a break isn't a track.
Where each vote ends up. Love writes to both the DJ's weighting and Navidrome's stars, so a loved track shows up on the Favourites page (F) like any other favourite. Like and dislike are DJ-only — they steer rotation but have no Navidrome equivalent, because Subsonic has no concept between "starred" and "not starred".
How it differs from radio mode. Radio mode fills your local queue with Navidrome's similar-song suggestions and plays it like any other queue. DJ mode plays nothing locally: it asks the server for one segment at a time, and a segment may be a spoken break rather than a track.
Three consequences worth knowing:
- There is no "up next", by design.
/api/nextconsumes — it removes the segment from the server's queue and never offers it again — and the backend publishes no read-only view of what's upcoming. So looking ahead would mean taking a segment we might not play, and a taken segment that goes unplayed is lost for good. The right panel shows history instead, which is honest about what's known. - Breaks aren't tracks. They have no library ID, so they're deliberately not modelled as songs — doing that would write fictional entries into your listening history and scrobble them.
- No local scrobbling in DJ mode. The DJ backend scrobbles to Navidrome itself; sonic-tui only reports segment start/finish so the server can keep its own play history straight.
Authentication. The DJ backend uses a session cookie and gates its audio endpoints, not just its API. mpv has its own HTTP stack and shares nothing with the app's HTTP client, so the session is handed to it explicitly via http-header-fields — miss that and the station list loads fine while playback silently 401s.
Dependencies
Runtime
- mpv (for audio playback)
- A Sixel-capable terminal (optional, for album art):
- kitty
- WezTerm
- foot
- mlterm
- xterm (with Sixel support enabled)
Build
- Rust 1.70+
- pkg-config
- OpenSSL development headers
- mpv development headers
Debian/Ubuntu
sudo apt install pkg-config libssl-dev libmpv-dev
Fedora
sudo dnf install pkg-config openssl-devel mpv-libs-devel
Arch Linux
sudo pacman -S pkg-config openssl mpv
macOS
brew install pkg-config openssl mpv
Troubleshooting
No album art showing
Make sure your terminal supports the Sixel or Kitty image protocol. You can test with:
# For Sixel
img2sixel /path/to/image.png
# For Kitty
kitty +kitten icat /path/to/image.png
Audio not playing
Ensure mpv is installed and working:
mpv --version
mpv /path/to/audio/file.mp3
Connection errors
Verify your server URL includes the protocol (http:// or https://) and check your credentials.
License
GPL-3.0
Acknowledgments
- jellyfin-tui - Inspiration and reference
- ratatui - Terminal UI framework
- libmpv - Audio playback
