waxon

Spotify, from the home row.

waxon is a Spotify client for the terminal with vim keys. It plays music by itself or drives the Spotify app, with album art and synced lyrics.

brew trust danfry1/tap
brew install danfry1/tap/waxon

macOS and Linux. Homebrew asks you to trust a third-party tap once.

Needs Spotify Premium.

Click the terminal and type, or tap the keys.

:theme

Two ways to play.

In waxon

waxon is the player. It runs its own Spotify Connect device, so there's no Spotify app to keep open. Setup installs and signs in the player for you.

As a remote

waxon drives the Spotify app on this computer, or your phone, or a speaker. If the app is closed, M opens it and hands the music over.

M switches between them and carries on from the same second; press it here or in the demo. Your keyboard's media keys and the system's Now Playing work either way.

gq

The queue, as you'd expect it.

What's playing, what you've queued, then what's next from the playlist. Enter skips straight to a track and keeps the rest of the queue.

Scripts and status bars.

Every action is also a command, so waxon fits into tmux, waybar, hotkey daemons and shell scripts without opening the app.

waxon status prints what's playing in any format you like, or as JSON.

$ waxon status
▶ Let It Happen — Tame Impala
$ waxon play daft punk get lucky
$ waxon vol +5
$ waxon status --format '{icon} {title} [{position}/{duration}]'
▶ Get Lucky [0:41/6:09]
$ waxon status --json | jq .device
"waxon (studio)"
0:main*▶ Get Lucky — Daft Punk │ 21:14

Search and artist pages

s searches Spotify. Artist pages open with Play and Shuffle, then the popular tracks and albums.

Playlists

o on a track adds it to a playlist or removes it, and visual mode does a run of tracks at once.

Small terminals

Under 80 columns waxon shows one pane at a time, so it fits a tmux side pane.

Your keys

Every key can be remapped in config.json, and ? always shows the ones you have.

After installing

Run waxon

The first run is a guided setup of about a minute: sign in to Spotify in your browser, then choose where music plays.

Press ?

Help lists every key, including the ones you've remapped. The README covers the rest.

Stuck?

waxon doctor checks your login, devices, network and terminal, and says what to fix.

It talks to Spotify, and that's it.

waxon has no telemetry or analytics. Besides Spotify it talks only to lrclib, for lyrics, and to GitHub once a day to check for a new release; you can turn both off. Sign-in uses PKCE, so there's no client secret, and your password only ever goes to Spotify's own sign-in page.

On a work network it uses your proxy settings, and "lyrics": false keeps it to Spotify alone.

  • accounts.spotify.comSigning in
  • api.spotify.comYour library, search and playback
  • *.scdn.coAlbum and playlist covers
  • lrclib.netLyrics, looked up by the track's title, artist, album and length
  • Spotify's audio serversOnly when waxon is the player