A Spotify client for the terminal written in Rust.

The terminal in the demo above is using the Rigel theme.

• Installation
• Connecting to Spotify’s API
• Usage
• Limitations
• Using with spotifyd
• Development
• Contributors
• Roadmap

The binary executable is spt.

For both macOS and Linux

brew install Rigellute/tap/spotify-tui

To update, run

brew upgrade spotify-tui

For a system with Snap installed, run

snap install spt --channel=edge

The latest version will be installed for you automatically.

For those on Arch Linux you can find the package on AUR here. If however you're using an AUR helper you can install directly from that, for example (in the case of yay), run

yay -S spotify-tui

Available on the official repositories. To install, run

sudo xbps-install -Su spotify-tui

Use this option if your architecture is not supported by the pre-built binaries found on the releases page.

First, install Rust (using the recommended rustup installation method) and then

cargo install spotify-tui

This method will build the binary from source.

To update, run

cargo install spotify-tui --force

For compilation on Linux the development packages for libssl are required. For basic installation instructions, see install OpenSSL. In order to locate dependencies, the compilation also requires pkg-config to be installed.

If you are using the Windows Subsystem for Linux, you'll need to install additional dependencies.

1. Download the latest binary for your OS.
2. cd to the file you just downloaded and unzip
3. cd to spotify-ui and run with ./spt

spotify-tui needs to connect to Spotify’s API in order to find music by name, play tracks etc.

Instructions on how to set this up will be shown when you first run the app.

But here they are again:

1. Go to the Spotify dashboard
2. Click Create a Client ID and create an app
3. Now click Edit Settings
4. Add http://localhost:8888/callback to the Redirect URIs
5. You are now ready to authenticate with Spotify!
6. Go back to the terminal
7. Run spt
8. Enter your Client ID
9. Enter your Client Secret
10. You will be redirected to an official Spotify webpage to ask you for permissions.
11. After accepting the permissions, you'll be redirected to localhost. If all goes well, the redirect URL will be parsed automatically and now you're done. If the local webserver fails for some reason you'll be redirected to a blank webpage that might say something like "Connection Refused" since no server is running. Regardless, copy the URL and paste into the prompt in the terminal.

And now you are ready to use the spotify-tui 🎉

You can edit the config at anytime at ${HOME}/.config/spotify-tui/client.yml.

The binary is named spt.

When running spotify-tui press ? to bring up a help menu that shows currently implemented key events and their actions.

A configuration file is located at ${HOME}/.config/spotify-tui/config.yml (not to be confused with client.yml which handles spotify authentication)

The following is a sample config.yml file:

# Sample config file

behavior:
  seek_milliseconds: 5000

keybindings:
  # Key stroke can be used if it only uses two keys:
  # ctrl-q works,
  # ctrl-alt-q doesn't.
  back: "ctrl-q"

  jump_to_album: "a"

  # Shift modifiers use a capital letter (also applies with other modifier keys
  # like ctrl-A)
  jump_to_artist_album: "A"

  manage_devices: "d"
  decrease_volume: "-"
  increase_volume: "+"
  toggle_playback: " "
  seek_backwards: "<"
  seek_forwards: ">"
  next_track: "n"
  previous_track: "p"
  copy_song_url: "c"
  copy_album_url: "C"
  help: "?"
  shuffle: "s"
  repeat: "r"
  search: "/"

This app uses the Web API from Spotify, which doesn't handle streaming itself. So you'll need either an official Spotify client open or a lighter weight alternative such as spotifyd.

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

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 spt
3. Press d to go to the device selection menu and the spotifyd "device" should be there - if not check these docs

• tui-rs
• rspotify

1. Install OpenSSL
2. Install Rust
3. Install xorg-dev (required for clipboard support)
4. Clone or fork this repo and cd to it
5. And then cargo run

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

Thanks goes to these wonderful people (emoji key):

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 💻

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

The goal is to eventually implement almost every Spotify feature.

• Add songs to a playlist
• Be able to scroll through result pages in every view
• View Library "Made for you"

This table shows all that is possible with the Spotify API, what is implemented already, and whether that is essential.