must - MUSic TUI A fast, beautiful TUI music player for your local music library and Subsonic-compatible streaming server. Built with Go + Bubble Tea.

See additional SCREENSHOTS.md. Includes themes, views, modals, and IPC examples.

Optional human-style typed metadata title_animantion = 'human' off by default.

Machine-style title_animation = 'machine'

There's a million music players, why must?

1. TUI speed — incredibly fast, responsive, keyboard-driven.

2. Play local music files, from your streaming server, or both at the same time.

3. Prominent high-res album art in the terminal.

4. Easy keybindings, always visible in footer (toggle with M). No memorization needed.

5. Lyrics and artist info view, with artist thumb, image gallery, discography, and bio.

6. Fuzzy search all or specific tags (artist, album, year, genre), plus local and Subsonic playlists.

7. IPC control — control must from the command line: must next, must previous, must pause, etc.

8. Download/temp directory browser — trial those potentially janky mp3s you grabbed before promoting them to your library.

9. Omarchy theme integration with live reloads.

10. Integrations: last.fm and/or Listenbrainz scrobbling, Lidarr library management.

11. Gapless playback and ReplayGain normalization (track or album mode) via mpv.

12. Startup, find and play (with shuffle option) from the command line: must p ok computer, must ps beatles (shuffled), must ps genre:electronic or even must ps year:1980-1989 (play all 80s music shuffled).

Not convinced? See a full COMPARISON with popular TUI music players.

Features

• Music Library: Scan and browse your music collection with a 3-column browser (artists, albums, tracks), genre and playlist browsing, and field-specific search. Toggle local, Subsonic, or both.
• Smart Search: FTS5-powered full-text search with field queries (artist:radiohead year:1997) and year range filtering. Local and Subsonic playlists are searchable and browsable from the TUI.
• MPV Backend: Full gapless audio playback with seek, repeat (off/all/one), shuffle, progress tracking, and ReplayGain normalization
• Lyrics: Fetch plain and synced lyrics from LRCLib
• Artist Info: Bios from TheAudioDB, Discogs, and Wikipedia. Discographies from MusicBrainz. Artist images from local files or online APIs.
• Album Art: Smart terminal image support via go-termimg (Kitty, iTerm2, Sixel, halfblocks fallback). Local-first with online fallback.
• Scrobbling: Last.fm and ListenBrainz support
• Lidarr Integration: View artist/album monitoring status, open in Lidarr
• Visualizer: 9 real-time audio visualizations (bars, braille, wave, stars, rain, etc.)
• Themes: 6 built-in themes, custom colors.toml, automatic Omarchy theme detection with live-reloads
• Playlist Management: Reorder (J/K/g/G), save (S), delete (d), clear (D), enqueue next (E), and reverse playlist order (X).
• Session Restore: Automatically restores last session on startup
• Sleep Timer & Alarm Clock: Fall asleep or wake up to your music
• 4 Layouts: large (default), medium, compact, narrow (sidebar or mobile format)
• IPC Control: Control a running must instance from the terminal (must next, must find radiohead, etc.). must play <query> also auto-starts must if not running — just type must p radiohead from anywhere.
• Subsonic/Navidrome Integration: Search and stream from any Subsonic-compatible server (Navidrome, Jellyfin, etc.). Use subsonic:artist:<q>, subsonic:album:<q>, etc. in IPC searches, or configure a server name alias like navidrome:<q>. Search modal supports local-only, subsonic-only, or combined search mode.
• Options Modal: Adjust replaygain, view, and visualizer settings on the fly
• Temp Directories Modal: Easily find and play music not stored in the main library. Perfect for listening to recent downloads before deciding whether to add to your library.
• Media Keys Support: Use your keyboard's media keys to control playback (e.g. Fn+F4 to play/pause). Requires mpv-mpris.
• Desktop Notifications: On song changes, with optional album art. Requires libnotify.
• Title Animation: Optional typewriter reveal for now-playing metadata on track change (title_animation = "off" | "machine" | "human", scope song or all). Off by default.

Installation

Prerequisites

• mpv — Required for audio playback
• Go 1.26+ — To build from source
• Any NerdFont — For proper symbol display

Note: Windows and macOS support includes real audio visualization (WASAPI on Windows, SoX+BlackHole on macOS). Other platform features are experimental and untested — feedback appreciated.

New to mpv or NerdFonts? See HELP.md for platform-specific setup instructions.

Recommended

• mpv-mpris — Required for media key support
• libnotify — Required for desktop notifications. libnotify-bin on Debian/Ubuntu.
• Kitty, Ghostty, or Rio terminal — For best image support

Visualizer (Windows & macOS)

• Windows: Real audio capture uses built-in WASAPI — no additional software needed.
• macOS: Install SoX and BlackHole:

  brew install sox blackhole-2ch
  

  Then configure a Multi-Output Device in Audio MIDI Setup to route system audio through BlackHole.

Build from Source

git clone https://github.com/pdfrg/must.git
cd must
go build -o must ./cmd/must

Install with Go

go install github.com/pdfrg/must/cmd/must@latest

Supported Formats

MP3, FLAC, OGG, Opus, M4A, AAC, WMA, WAV

Documentation

See DOCUMENTATION.md for cli usage, IPC control commands, keybindings, configuration reference, album art/artist image priority, XDG paths, search architecture, and database schema.

Omarchy Integration

must follows your Omarchy theme automatically (live-reload, no setup) and pairs well with amla, a searchable music launcher popup (SUPER + M) that searches your must library — local files, temp/download albums, Subsonic/Navidrome, genres, years/decades, playlists — and dispatches play / enqueue / play-next / shuffle straight to the running must instance:

omarchy plugin add https://github.com/pdfrg/amla

Keybind (Omarchy 4 lua configs)

Omarchy ships SUPER + SHIFT + M bound to Spotify/Music. To give that key to must instead, add to ~/.config/hypr/bindings.lua:

-- Must (large) — stderr captured so panic traces survive terminal closure
hl.unbind("SUPER + SHIFT + M")
o.bind("SUPER + SHIFT + M", "Must", "xdg-terminal-exec --app-id=must.large -e sh -c 'must --layout large 2>>\"${XDG_STATE_HOME:-$HOME/.local/state}/must/stderr.log\"'")

Prefer to keep Spotify on SUPER + SHIFT + M? Bind must to SUPER + SHIFT + U instead (unbound by default):

o.bind("SUPER + SHIFT + U", "Must", "xdg-terminal-exec --app-id=must.large -e sh -c 'must --layout large 2>>\"${XDG_STATE_HOME:-$HOME/.local/state}/must/stderr.log\"'")

Floating window (Omarchy 4 lua configs)

Add to ~/.config/hypr/hyprland.lua so must opens as a centered floating window (the --app-id in the keybind must match the first argument here):

o.window("must.large", { size = { 1024, 838 }, float = true, center = true })

Launcher entry (Omarchy app menu)

A must.desktop is shipped in assets/ (uses xdg-terminal-exec with the same must.large app-id, so the float/size rule above applies). Install it with:

cp assets/must.desktop ~/.local/share/applications/

This puts Must in the Omarchy launcher alongside your other TUI apps — same pattern as rptui's assets/rptui.desktop.

Attribution

Audio visualizations: cliamp. Awesome music player with retro Winamp style in the terminal.

Title animation inspired by kew. Awesome minimal music player with a nice typewriter effect for the track title.

See Also

If you like must, please check out...

rptui a Radio Paradise TUI

amla a searchable Omarchy music launcher plugin that dispatches to must (or cliamp, or mpd)

License

MIT