tuify

Tuify

A terminal-based Spotify client. Browse playlists, search for music and podcasts, control playback — Spotify without all the noise.

Features

• Playback Control — Play, pause, skip, previous, shuffle, seek
• Playlists — Browse and play your Spotify playlists
• Podcasts — Browse saved shows and episodes
• Search — Find tracks, episodes, artists, albums, and shows
• Now Playing — Live progress bar, track info, shuffle state, active device indicator
• Device Selector — Switch playback between Spotify Connect devices
• Mini Mode — Compact single-line view with track info and progress
• Mouse Support — Scroll wheel to navigate lists, click to select, double-click to play or drill down
• Visualizers — Album art, starfield, spectrum, oscillogram, spectrogram, VU meter, and Milkdrop-style presets (spiral, tunnel, kaleidoscope, ripple)
• Lyrics — Fetches and displays lyrics from Genius.com
• Dark & Light Terminals — Adaptive color palette that adjusts automatically

Requirements

• A Spotify Premium account
• A Spotify Developer App

Install

macOS / Linux

brew install lounge/tap/tuify

Windows

Install Scoop, then:

scoop bucket add lounge https://github.com/lounge/scoop-bucket
scoop install tuify

Direct download

Pre-built binaries for all platforms are available on the Releases page.

Getting Started

1. Go to https://developer.spotify.com/dashboard and create an app
2. Set the redirect URI to http://127.0.0.1:4444/callback
3. Check the Web API checkbox
4. Copy your Client ID
5. Run tuify — it will ask for your Client ID on first launch
6. A browser window will open to authorize with Spotify

Keybindings

Search Shortcuts

Type a prefix in the search bar to filter by type:

Vim Mode

Enable vim-style keybindings by setting "vim_mode": true in your config file.

Visualizers

Album Art and Lyrics work out of the box. The audio-reactive visualizers require librespot — see the section below.

Librespot (Optional)

Librespot is an open-source Spotify Connect client. Installing it unlocks direct audio streaming and all audio-reactive visualizers.

Setup

1. Install librespot and make sure it's in your PATH
2. Set "enable_librespot": true in ~/.config/tuify/config.json
3. Restart tuify — it will connect as a Spotify device automatically

If the connection drops, tuify detects the failure, restarts librespot, and transfers playback back automatically. If you manually switch to another device in Spotify, tuify respects that and won't reclaim playback. When librespot becomes inactive (playback moved away), the UI updates immediately via Spotify Connect signals — no API polling delay.

Librespot Config

Add these to ~/.config/tuify/config.json:

Audio Backends

Only "pipe" enables audio-reactive visualizers.

Other backends (jackaudio, portaudio, gstreamer, sdl) require enabling cargo features when building librespot. See the librespot Audio Backends wiki.

Configuration

All configuration is stored in ~/.config/tuify/ (or $XDG_CONFIG_HOME/tuify/).

Theme

The theme block lets you override every UI color. Each role takes a {light, dark} hex pair, so the override picks up automatically based on the terminal's background. First-time setup writes the current defaults into config.json, so opening the file shows you the full set ready to edit. Removing a role (or setting either hex to "") falls back to the built-in default for that mode. Each color must be #RGB or #RRGGBB.

What each role drives:

{
  "theme": {
    "primary":        { "light": "#874BFD", "dark": "#58f796" },
    "secondary":      { "light": "#6232CC", "dark": "#b48eff" },
    "muted":          { "light": "#9B9B9B", "dark": "#626262" },
    "subtle":         { "light": "#6C6C6C", "dark": "#8a8a8a" },
    "dim":            { "light": "#BCBCBC", "dark": "#444444" },
    "error":          { "light": "#FF0000", "dark": "#ff0087" },
    "text":           { "light": "#1a1a1a", "dark": "#dddddd" },
    "text_dim":       { "light": "#A49FA5", "dark": "#777777" },
    "tip":            { "light": "#D4A017", "dark": "#FFD866" },
    "on_primary":     { "light": "#000000", "dark": "#000000" },
    "gradient_start": { "light": "#e4d4f7", "dark": "#110a24" },
    "gradient_end":   { "light": "#f8f5fc", "dark": "#040208" }
  }
}

Logs

Tuify writes a debug log to ~/.config/tuify/debug.log on each run. The log is overwritten every time you start tuify. Check this file if something isn't working as expected.

Development

Build from source

Requires Go 1.26+. On Linux, also install libasound2-dev.

git clone https://github.com/lounge/tuify.git
cd tuify
go build
go test ./...
golangci-lint run ./...   # matches CI; catches formatting + lint issues

Architecture

TODO

• Make it work when connected to external devices (Sonos) - doesn't work for some stupid reason... (https://github.com/spotify/web-api/issues/1337).

License

MIT