GitHub - danfry1/waxon: A vim-modal Spotify client for the terminal (original) (raw)
A vim-modal Spotify client for the terminal.
Install ·Features ·Keybindings ·Commands
Install
Homebrew:
brew trust danfry1/tap # one-time: trust the third-party tap
brew install danfry1/tap/waxon
Recent Homebrew versions refuse to load formulae from third-party taps until they're trusted. If you see
Error: Refusing to load formula ... from untrusted tap, run thebrew trust danfry1/tapline above (once) and retry.
Go:
go install github.com/danfry1/waxon@latest
Binary: download from the Releases page.
Quick Start
waxon auth # Connect your Spotify account (one-time setup) waxon # Launch the TUI
Requires a Spotify Premium account and a terminal with true color support.
Features
Vim Navigation
Navigate everything without leaving the home row — j/k to move, gg/G to jump, h/l to switch panes.
Now Playing
Full-screen album art rendered with Unicode half-blocks, gradient backgrounds, and a vinyl spinning mode.
Synced Lyrics
Press l in Now Playing for time-synced lyrics (via lrclib — no account, no API key, nothing to set up). The current line lights up and the rest gently fade as the song plays.
Search
Find tracks, artists, and albums across Spotify.
Artist & Album Browsing
Explore discographies, browse full albums, and navigate with a browser-like back stack.
Command Mode
Vim-style commands for volume, shuffle, repeat, device switching, and more.
Keybindings
Navigation
| Key | Action |
|---|---|
| j / k | Move down / up |
| gg | Go to top |
| G | Go to bottom |
| Ctrl+u / Ctrl+d | Half page up / down |
Panes
| Key | Action |
|---|---|
| h / l | Focus left / right pane |
| Tab | Cycle pane |
| 1 / 2 | Library / queue section |
Go-to (g prefix)
| Key | Action |
|---|---|
| gl | Go to library |
| gq | Go to queue |
| gc | Jump to currently playing track (loads its playlist/album if you've navigated away) |
| gr | Recently played |
Playback
| Key | Action |
|---|---|
| Space | Play / pause |
| Enter | Play selected |
| n / p | Next / previous track |
| [ / ] | Seek -5s / +5s |
Actions
| Key | Action |
|---|---|
| o | Context actions menu |
| a | Add to queue |
| / | Filter current view |
| s | Spotify search |
| D | Device switcher |
| : | Command mode |
Other
| Key | Action |
|---|---|
| N | Now Playing view |
| f / a / o | Like / queue / actions for the playing track (in Now Playing) |
| V | Toggle vinyl mode (in Now Playing) |
| l | Toggle synced lyrics (in Now Playing) |
| Backspace / b | Go back |
| ? | Toggle help overlay |
| q | Quit |
| Esc | Close / cancel |
Commands
Enter command mode by pressing :, then type a command.
| Command | Description |
|---|---|
| :vol <0-100> | Set volume |
| :shuffle | Toggle shuffle |
| :repeat off|all | one |
| :device | Open device switcher |
| :search | Search Spotify |
| :recent | Recently played |
| :q | Quit |
Using Your Own Spotify App (Optional)
waxon works out of the box with no configuration — it ships with a shared client ID used by several open-source Spotify clients. Most users don't need to change anything.
If you'd prefer to use your own Spotify developer app:
- Go to the Spotify Developer Dashboard and create an app
- Set the redirect URI to
http://127.0.0.1:27228/callback - Copy the Client ID and run setup with it:
SPOTIFY_CLIENT_ID=your_client_id waxon auth The client ID is saved to ~/.config/waxon/config.json automatically, so you only need to set the environment variable once during setup.
Environment Variables
| Variable | Description |
|---|---|
| SPOTIFY_CLIENT_ID | Override the saved Spotify Client ID |
| WAXON_LOG | Path to debug log file (e.g. /tmp/waxon.log) |
Acknowledgements
Built with Bubbletea, Bubbles, and Lip Gloss by Charmbracelet. Demo recordings made with VHS. Huge thanks to the Charm team for making terminal UIs a joy to build.
License
This project is licensed under the GNU General Public License v3.0.