A Spotify client for the terminal written in Rust, powered by Ratatui.

A community-maintained fork of spotify-tui, actively developed with new features like native streaming, synced lyrics, and real-time audio visualization.

• Help Wanted
• Performance
• Privacy Notice
• Migrating from spotify-tui
• Installation
• Connecting to Spotify
• Usage
• Native Streaming
• Configuration
• Limitations
  • Deprecated Spotify API Features
• Using with spotifyd
• Libraries used
• Development
  • Windows Subsystem for Linux
• Maintainer
• spotatui Contributors
• Upstream Contributors (spotify-tui)
• Star History
• Roadmap

spotatui is currently maintained by a solo developer. More contributors would be hugely appreciated! Here's how you can help:

• Star the repo to help others discover the project
• Report bugs or request features in Issues
• Join the community in Discussions
• Submit a PR for code, docs, or themes

See CONTRIBUTING.md for more details!

spotatui is extremely lightweight compared to the official Electron client.

Tested on Arch Linux (Hyprland).

Anonymous Global Counter: spotatui includes an opt-in feature that contributes to a global counter showing how many songs have been played by all users worldwide. This feature:

• Is completely anonymous - no personal information, song names, artists, or listening history is collected
• Only sends a simple increment when a new song starts playing
• Is enabled by default but can be opted out at any time
• Can be disabled by setting enable_global_song_count: false in ~/.config/spotatui/config.yml

We respect your privacy. This is purely a fun community metric with zero tracking of individual users.

If you used the original spotify-tui before:

• The binary name changed from spt to spotatui.
• Config paths changed:
  • Old: ~/.config/spotify-tui/
  • New: ~/.config/spotatui/

You can copy your existing config:

mkdir -p ~/.config/spotatui
cp -r ~/.config/spotify-tui/* ~/.config/spotatui/

You may be asked to re-authenticate with Spotify the first time.

# Cargo (recommended)
cargo install spotatui

# Arch Linux (AUR)
yay -S spotatui

Or download pre-built binaries from GitHub Releases.

See the Installation Wiki for platform-specific requirements and building from source.

Run spotatui and follow the on-screen instructions to connect your Spotify account.

You'll need to create a Spotify Developer app at the Spotify Dashboard.

See the Installation Wiki for step-by-step setup.

The binary is named spotatui.

Running spotatui with no arguments will bring up the UI. Press ? to bring up a help menu that shows currently implemented key events and their actions. There is also a CLI that is able to do most of the stuff the UI does. Use spotatui --help to learn more.

See Keybindings Wiki for the full list of keyboard shortcuts.

Here are some example to get you excited.

spotatui --completions zsh # Prints shell completions for zsh to stdout (bash, power-shell and more are supported)

spotatui play --name "Your Playlist" --playlist --random # Plays a random song from "Your Playlist"
spotatui play --name "A cool song" --track # Plays 'A cool song'

spotatui playback --like --shuffle # Likes the current song and toggles shuffle mode
spotatui playback --toggle # Plays/pauses the current playback

spotatui list --liked --limit 50 # See your liked songs (50 is the max limit)

# Looks for 'An even cooler song' and gives you the '{name} from {album}' of up to 30 matches
spotatui search "An even cooler song" --tracks --format "%t from %b" --limit 30

spotatui can play audio directly without needing spotifyd or the official Spotify app. Just run spotatui and it will appear as a Spotify Connect device.

• Works with media keys, MPRIS (Linux), and macOS Now Playing
• Premium account required

See the Native Streaming Wiki for setup details.

A configuration file is located at ${HOME}/.config/spotatui/config.yml.

See the Configuration Wiki for the full config file reference.

You can also configure spotatui in-app by pressing Alt-, to open Settings.

See Themes Wiki for built-in presets (Spotify, Dracula, Nord, etc.).

This app uses the Web API from Spotify, which doesn't handle streaming itself. You have three options for audio playback:

1. Native Streaming (NEW!) - spotatui can now play audio directly using its built-in streaming feature. See Native Streaming below.
2. Official Spotify Client - Have the official Spotify app open on your computer
3. Spotifyd - Use a lightweight alternative like spotifyd

If you want to play tracks, Spotify requires that you have a Premium account.

Note: As of November 2024, Spotify deprecated and removed access to certain API endpoints for new applications. The following features are included in this app but will only work if your Spotify Developer application was created before November 27, 2024:

• Audio Visualization (press v): Now uses local real-time FFT analysis of your system audio. The visualization no longer depends on Spotify's deprecated Audio Analysis API.

  Platform Support:

  Platform	Status	Notes
  Windows	Works out of the box	Uses WASAPI loopback
  Linux	Works out of the box	Uses PipeWire/PulseAudio monitor devices
  macOS	Requires setup	Needs a virtual audio device (see below)

  macOS Users: macOS doesn't natively expose system audio loopback. To use audio visualization, install a virtual audio device like BlackHole (free) or Loopback (paid). Configure it to capture system audio and set it as your default input device.

  Note: The audio visualization is system-wide - it captures all audio playing on your system, not just Spotify. This means it will also react to YouTube videos, games, or any other audio source!

• Related Artists: When viewing an artist page, the "Related Artists" section shows similar artists based on Spotify's recommendation algorithm. This feature only works if your Spotify Developer application was created before November 27, 2024.

For more information, see Spotify's announcement about API changes.

Note: If you're using native streaming, you don't need spotifyd!

Follow the spotifyd documentation to get set up.

After that there is not much to it.

1. Start running the spotifyd daemon.
2. Start up spotatui
3. Press d to go to the device selection menu and the spotifyd "device" should be there - if not check these docs

• ratatui - Terminal UI framework
• rspotify - Spotify Web API client
• librespot - Spotify Connect streaming
• tokio - Async runtime
• crossterm - Terminal manipulation
• clap - CLI argument parsing

1. Install OpenSSL
2. Install Rust
3. Install xorg-dev (required for clipboard support)
4. Linux only: Install PipeWire development libraries (required for audio visualization)

   # Debian/Ubuntu
   sudo apt-get install libpipewire-0.3-dev libspa-0.2-dev
   
   # Arch Linux
   sudo pacman -S pipewire
   
   # Fedora
   sudo dnf install pipewire-devel

5. Clone or fork this repo and cd to it
6. And then cargo run

See CONTRIBUTING.md for pull request guidelines.

You might get a linking error. If so, you'll probably need to install additional dependencies required by the clipboard package

sudo apt-get install -y -qq pkg-config libssl-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

Maintained by LargeModGames.

Originally forked from spotify-tui by Alexander Keliris.

Looking for contributors! spotatui is actively maintained but could use your help. Whether it's bug fixes, new features, documentation, or testing - all contributions are welcome!

LargeModGames 💻 📖 🚧 🤔 🚇 ⚠️

MysteriousWolf 💻

rawcode1337 💻 🐛

copeison 📦

jacklorusso 📖

H41L33 📖

Want to see your name here? Check out our open issues or the Roadmap below!

Thanks to all the contributors who built the original spotify-tui that this project is forked from:

Alexander Keliris 💻 📖 🎨 📝 🤔 🚇 📦 👀	Mickael Marques 💵	Grzegorz Koperwas 📖	Austin Gassert 💻	Calen Robinette 💻	M*C*O 🚇
Andrew Chin 💻	Sam Naser 💻	Micha 💻	neriglissar 💻	Timon 💻	echoSayonara 💻	D-Nice 📖 🚇
Grzegorz Pawlik 💻	Lennart Bernhardt 💻	Arnaud Lefebvre 💻	tem1029 💻	Peter K. Moss 💻	Geoff Shannon 💻	Zachary Mayhew 💻
jfaltis 💻	Marcel Schramm 📖	Fangyi Zhou 💻	Max 💻	Sven van der Vlist 💻	jacobchrismarsh 💻	Nils Rauch 💻
Nick Stockton 💻 🐛 🚧 💬 📖	Stuart Hinson 💻	Sam Calvert 💻 📖	Jeroen Wijenbergh 📖	Kimberley Cook 📖	Audrey Baxter 💻	Norman 📖
Peter Maatman 💻	AlexandreS 💻	Finn Vos 💻	Carlos Hernandez 📦	Pedro Alves 💻	jtagcat 📖	Benjamin Kitor 💻
Aleš Najmann 📖 📦	Jeremy Stucki 💻	(´⌣`ʃƪ) 💻	Artem Polishchuk 📦	Chris Sosnin 💻	Ben Buhse 📖	Sean Li 💻
TimotheeGerber 💻 📖	Ferdinand Ratajczak 💻	Sheel Choksi 💻	Michael Hellwig 📖	Oliver Daniel 💻	Drew Fisher 💻	ncoder-1 📖
Macguire Rintoul 📖	Ricardo Holguin 💻	Keisuke Toyota 💻	Craig Astill 💻	Onielfa 💻	usrme 📖	Sergey A. 💻
Hideyuki Okada 💻	kepae 💻 📖	Érico Nogueira Rolim 💻	Alexander Meinhardt Scheurer 💻	Ondřej Kinšt 💻	Kryan90 📖	n-ivanov 💻
bi1yeu 💻 📖	May 💻	Bruno A. Muciño 💻	Finn Hediger 💻	dp304 💻	Marco Micera 📖	Marco Ieni 🚇
Artúr Kovács 💻	Antony Kellermann 💻	Rasmus Pedersen 💻	noir-Z 📖	David Bailey 📖	sheepwall 💻	Hwatwasthat 💻
Jesse 💻	Sang 📖	Yuuki Takahashi 📖	Alejandro Angulo 💻	Anton Kostin 📖	Justin Sexton 💻	Jiati Le 📖
Matthew Cobbing 💻	Milo 🚇	Diego Veralli 💻	Maja Bojarska 💻

This project follows the all-contributors specification. Contributions of any kind welcome!

The goal is to eventually implement almost every Spotify feature.

High-priority features:

• Add songs to a playlist
• Scroll through result pages in every view

See the Roadmap Wiki for the full API coverage table.