MCPcopy Index your code
hub / github.com/danfry1/waxon

github.com/danfry1/waxon @v1.5.0

Chat with this repo
repository ↗ · DeepWiki ↗ · release v1.5.0 ↗ · + Follow
900 symbols 3,123 edges 47 files 309 documented · 34%
What it actually does AI analysis from the code graph — generated when you open this
loading…
README

waxon logo

waxon

A vim-modal Spotify client for the terminal.

Install · Features · Keybindings · Commands

waxon demo

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 the brew trust danfry1/tap line 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.

vim navigation

Now Playing

Full-screen album art rendered with Unicode half-blocks, gradient backgrounds, and a vinyl spinning mode.

now playing view

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.

time-synced lyrics

Search

Find tracks, artists, and albums across Spotify.

search

Artist & Album Browsing

Explore discographies, browse full albums, and navigate with a browser-like back stack.

artist and album browsing

Command Mode

Vim-style commands for volume, shuffle, repeat, device switching, and more.

command mode

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 Set repeat mode
:device Open device switcher
:search <query> 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:

  1. Go to the Spotify Developer Dashboard and create an app
  2. Set the redirect URI to http://127.0.0.1:27228/callback
  3. 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.

Extension points exported contracts — how you extend this code

PlaybackSource (Interface)
PlaybackSource provides playback control beyond basic TrackSource operations. [3 implementers]
source/rich.go
TrackSource (Interface)
(no doc) [3 implementers]
source/source.go
ArtworkProvider (Interface)
ArtworkProvider is an optional interface that source implementations can satisfy to provide embedded artwork instead of [1 …
app/artwork_provider.go
LibrarySource (Interface)
LibrarySource provides access to the user's music library. [3 implementers]
source/rich.go
SearchSource (Interface)
SearchSource provides search and browse capabilities. [3 implementers]
source/rich.go
LyricsSource (Interface)
LyricsSource provides lyrics for a track. Returns (nil, nil) when no lyrics are available so callers can show an empty s [3 …
source/rich.go
RichSource (Interface)
RichSource combines all source capabilities. Implementations must satisfy TrackSource, PlaybackSource, LibrarySource, Se
source/rich.go

Core symbols most depended-on inside this repo

track
called by 170
demo/data.go
Update
called by 140
app/app.go
SetTracks
called by 48
app/tracklist.go
Show
called by 40
app/toast.go
scheduleAutoDismiss
called by 30
app/toast.go
Visible
called by 28
app/toast.go
NewSearch
called by 20
app/search.go
String
called by 19
app/mode.go

Shape

Function 525
Method 271
Struct 86
TypeAlias 10
Interface 8

Languages

Go100%

Modules by API surface

app/update_test.go260 symbols
app/app.go47 symbols
app/app_test.go39 symbols
source/rich.go38 symbols
app/tracklist.go36 symbols
spotify/api_test.go35 symbols
app/commands.go34 symbols
demo/demo.go32 symbols
auth/oauth_test.go31 symbols
app/stub_test.go29 symbols
app/sidebar.go24 symbols
spotify/player.go21 symbols

For agents

$ claude mcp add waxon \
  -- python -m otcore.mcp_server <graph>

⬇ download graph artifact