A modern, keyboard-first terminal music player — local library, Spotify, radio, podcasts, synced lyrics, and a live visualizer, all in your terminal.
Everything in one view — and it follows your terminal's light or dark theme.
See more screenshots
Browse — genres and moods as a cover wall |
|
Playlists & search — keyboard-driven track lists |
Visualizer — live FFT spectrum |
Synced lyrics — karaoke and translation |
Full-screen album art |
Captured on Ghostty, which renders real inline album art.
Library
- Off-thread scanner with a binary cache for instant cold starts
- Plays FLAC, MP3, AAC/M4A, OGG, and WAV (symphonia)
- Fuzzy search, Miller-column browsing (Artists ▸ Albums ▸ Tracks), multi-key sort
- Favorites, 0–5★ ratings, play counts, and smart lists
- Cover-art grid — album & artist wall with real covers and online artist photos
Playback
- symphonia → cpal engine on a dedicated thread with a lock-free ring buffer
- 10-band graphic equalizer with a preamp and presets
- Gapless, crossfade, ReplayGain, and time-stretched speed
- Reorderable queue, repeat, and shuffle
Streaming & online
- Spotify (Premium) via librespot, routed through lyrfin's own engine — the visualizer, volume, and speed all apply; browse, search, playlists, and likes
- Internet radio — ~50k Radio Browser stations with search, filters, and favorites
- Podcasts stream from their public RSS feeds
Lyrics & visuals
- Synced
.lrc(sidecar or embedded), with online fallback (LRCLIB, NetEase, JioSaavn) - Karaoke word-wipe, teleprompter, bilingual view, and machine translation
- Live FFT visualizer with multiple modes and a waterfall history
- Inline album art via Kitty, sixel, or iTerm2 — half-block fallback elsewhere
Interface
- 7 instantly-switchable layouts; movable, dockable panes; responsive collapse
- 13 themes with optional follow-the-system light/dark, plus custom TOML and an album-art accent
- Full mouse support, rebindable keys, session restore, and listening stats
- Built-in tag editor for a track or a whole album, with online auto-tagging
Grab your platform's build from the Releases page — Linux x86-64, macOS (Intel & Apple Silicon), and Windows x86-64 — then:
tar xzf lyrfin-<target>.tar.gz
./lyrfinNote
macOS Gatekeeper. The binaries aren't notarized, so clear the quarantine
flag once: xattr -d com.apple.quarantine ./lyrfin
Requires Rust 1.96+. On Linux, install ALSA headers first
(sudo apt-get install libasound2-dev).
cargo install --git https://github.com/dilmun/lyrfinlyrfin # launch with your configured library
lyrfin ~/Music # scan a folder for this session
lyrfin --theme cyberpunk # start with a specific themePress ? for help, ; for settings, e for the equalizer, and 7 to connect Spotify.
Important
lyrfin is developed and tested on Ghostty. It targets common standards (truecolor, inline images, Unicode) and should work on other modern terminals, but they aren't officially verified yet.
Config lives at ~/.config/lyrfin/config.toml (%APPDATA%\lyrfin on Windows),
created with sensible defaults on first run. Most options are editable in-app via
the settings popup (;).
theme = "aurora" # or: cyberpunk · glacier · monolith · <custom>
music_dirs = ["/home/you/Music"]
volume = 72 # 0–100
gapless = true
crossfade_ms = 0 # 0 disables
album_art = true # inline cover artFull reference — every field, the theme format, and data paths — in
docs/CONFIGURATION.md.
Essentials (all rebindable — full list in docs/KEYBINDINGS.md):
| Key | Action | Key | Action | |
|---|---|---|---|---|
| Space | Play / pause | 1–7 | Switch layout | |
| n / p | Next / previous | / | Search | |
| ← / → | Seek | Tab | Cycle pane focus | |
| - / + | Volume | Enter | Play / open | |
| j / k | Move down / up | e | Equalizer | |
| s / r | Shuffle / repeat | t | Cycle theme | |
| f | Favorite | v | Visualizer mode | |
| . / , | Rate up / down | ; | Settings | |
| ? | Help | q | Quit |
- Broader terminal support (verified beyond Ghostty)
- Workspace profiles — switchable config / layout / library sets
- Scripting hooks (Lua or Rhai) for automation
- User-defined custom panes
Full detail and shipped milestones in docs/ROADMAP.md.
Contributions are welcome. See CONTRIBUTING.md for the
workflow and conventions, and docs/ARCHITECTURE.md for
the design (Event → Action → update → render).
cargo build --profile fast # optimized, fast to rebuild — best for dev
cargo test # reducer + snapshot tests (headless)
cargo fmt --all --check # formatting
cargo clippy --all-targets -- -D warnings # lintIf lyrfin is useful to you, a sponsorship or a ⭐ helps it keep going.
MIT © 2026 dilmun.
lyrfin is an independent project and is not affiliated with or endorsed by Spotify, Apple, Deezer, or any other service it interoperates with. Built on ratatui, symphonia, cpal, librespot, lofty, nucleo, and rustfft — thank you to those projects.