Disco Terminal

A Spotify client that runs entirely in your terminal. Album art, a real-time cava audio visualizer, full-app color theming, synced lyrics, and playback control — in iTerm2, kitty, or Windows Terminal, without leaving your shell or focusing the Spotify window. Turn your terminal into a disco.

Yes — everything above is a terminal emulator rendering text.

pipx install discoterminal

See it move

Pick a palette and the whole app rethemes — visualizer, borders, buttons, labels:

Eight visualizer styles (area, bars, mirror, peaks, outline, dots, led, rain):

Synced lyrics follow the song, Spotify-style; the card flips between now-playing, artist info, and lyrics:

More demos & screenshots (search, playlists, playback, cards…)

Search anything

Playlists sidebar

Playback controls

Cards & pickers

Visualizer on / off

Built with Textual. Playback control picks the best backend for your platform automatically:

The Spotify Web API (OAuth PKCE) powers your library, search, devices, queue, and is the universal control fallback. Override backend selection with {"backend": "shpotify" | "playerctl" | "webapi"} in config.

Features

• 🎨 Now playing card with album art (sixel/TGP/halfcell), live progress bar, and click-to-seek
• 📊 Audio visualizer — embedded cava, 8 render styles (area, bars, mirror, peaks, outline, dots, led, rain), 14 color palettes
• 🌈 Whole-app theming — pick a palette and every border, button, and label recolors to match
• 🔀 Card flip — artist info (genres, followers, popularity, top tracks) with artist photo
• 📻 Your playlists in a collapsible sidebar, fetched live from your account
• 🔍 Search anything — tracks, albums, playlists, artists — pick from a results modal
• 🎤 Lyrics via lrclib.net (no API key)
• ♥ Like/unlike the current track, ⏭ queue viewer, 📱 device switcher
• 🕺 Rave mode — beat-detected palette strobes across the whole app, or a fullscreen VJ takeover (flash rate capped at 4/sec)
• ⌨️ Everything keyboard-driven; playback via Web API so the Spotify app never steals focus

Install

macOS:

brew install shpotify cava            # local control + visualizer
pipx install discoterminal                 # or: pip install discoterminal
discoterminal

Linux:

sudo apt install playerctl cava       # or your distro's equivalent
pipx install discoterminal
discoterminal

Windows (experimental — testers wanted):

pip install discoterminal                  # control goes through the Web API
discoterminal                              # cava optional; needs a sixel-capable terminal

Requires Python 3.11+ and the Spotify desktop app. The Web API features (playlists, search, queue, lyrics card, artist info) need a Premium account — a Feb 2026 Spotify policy requires Premium for Web-API dev-mode apps. Local playback control via shpotify/playerctl works without Premium.

Spotify API setup (one time)

1. Go to the Spotify developer dashboard and create an app.

   • If the Web API checkbox is greyed out on the create form (a known dashboard bug): create the app without it, then Edit the app and add Web API there — it won't be greyed out on edit.

2. Add redirect URI: http://127.0.0.1:8888/callback

3. Copy the Client ID into ~/.config/discoterminal/config.json:

   { "client_id": "your-client-id-here" }
   

   (or export SPOTIPY_CLIENT_ID=...)

4. First launch opens a browser to log in once; the token is cached after. No client secret needed — discoterminal uses the PKCE flow.

Visualizer audio setup (macOS only, optional)

Linux and Windows: nothing to do — cava captures system audio natively (PulseAudio/PipeWire monitor, WASAPI loopback).

macOS has no built-in way for apps to hear system output, so cava needs a loopback device:

brew install blackhole-2ch
sudo killall coreaudiod              # load the driver
swift scripts/setup-audio.swift      # create + activate a Multi-Output device

The script builds a "Disco Terminal Multi-Out" device (your speakers + BlackHole) via CoreAudio and switches the system output to it. discoterminal auto-detects BlackHole and points cava at it. Skip all this and the visualizer simply shows a hint instead.

Note: with a Multi-Output device active, macOS volume keys are disabled (aggregate-device limitation). Use discoterminal's +/- — they control Spotify's own volume.

Turn it off / undo:

swift scripts/setup-audio.swift off      # back to speakers (device kept)
swift scripts/setup-audio.swift remove   # back to speakers + delete the device

Re-running without arguments turns it back on. Or just pick any output in System Settings → Sound.

Automatic mode: once the Multi-Out device exists, discoterminal switches to it on launch and restores your previous output on quit — you only run the setup script once, ever. Opt out with {"auto_multiout": false} in config.json.

Keys

Startup arguments: discoterminal next, discoterminal <playlist name>, discoterminal play artist NF — opens the TUI and runs the action.

Config reference

~/.config/discoterminal/config.json:

Development

pip install -e ".[dev]"
pytest
ruff check src tests
mypy src

Tests run headless with mocked Spotify backends — no account or audio setup needed. CI covers Linux, macOS, and Windows.

License

MIT