#spotify #tui #cli #terminal

app spotify-tui

A terminal user interface for Spotify

17 releases (breaking)

✓ Uses Rust 2018 edition

new 0.17.1 Mar 30, 2020
0.16.0 Mar 12, 2020
0.11.0 Dec 23, 2019
0.10.0 Nov 30, 2019

#6 in Command line utilities

Download history 93/week @ 2019-12-10 68/week @ 2019-12-17 98/week @ 2019-12-24 59/week @ 2019-12-31 147/week @ 2020-01-07 109/week @ 2020-01-14 129/week @ 2020-01-21 88/week @ 2020-01-28 99/week @ 2020-02-04 111/week @ 2020-02-11 146/week @ 2020-02-18 280/week @ 2020-02-25 140/week @ 2020-03-03 177/week @ 2020-03-10 240/week @ 2020-03-17 151/week @ 2020-03-24

629 downloads per month

MIT/Apache

560KB
7.5K SLoC

Spotify TUI

Continuous Integration Crates.io

All Contributors

A Spotify client for the terminal written in Rust.

Demo

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

Installation

The binary executable is spt.

Homebrew

For both macOS and Linux

brew install Rigellute/tap/spotify-tui

To update, run

brew upgrade spotify-tui

Snap

For a system with Snap installed, run

snap install spt

The stable version will be installed for you automatically.

If you want to install the nightly build, run

snap install spt --edge

AUR

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

Void Linux

Available on the official repositories. To install, run

sudo xbps-install -Su spotify-tui

Cargo

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

Note on Linux

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.

Windows 10

Scoop installer

First, make sure scoop installer is on your windows box, for instruction please visit scoop.sh

Then open powershell and run following two commands:

scoop bucket add scoop-bucket https://github.com/Rigellute/scoop-bucket
scoop install spotify-tui

After that program is available as: spt or spt.exe

Manual

  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

Connecting to Spotify’s API

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.

Usage

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.

Configuration

A configuration file is located at ${HOME}/.config/spotify-tui/config.yml, for snap ${HOME}/snap/spt/current/.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

# The theme colours can be an rgb string of the form "255, 255, 255" or a string that references the colours from your terminal theme: Reset, Black, Red, Green, Yellow, Blue, Magenta, Cyan, Gray, DarkGray, LightRed, LightGreen, LightYellow, LightBlue, LightMagenta, LightCyan, White.
theme:
  active: Cyan
  banner: LightCyan
  error_border: Red
  error_text: LightRed
  hint: Yellow
  hovered: Magenta
  inactive: Gray
  playbar_background: Black
  playbar_progress: LightCyan
  playbar_text: White
  selected: LightCyan
  text: "255, 255, 255"

behavior:
  seek_milliseconds: 5000
  volume_increment: 10
  # The lower the number the higher the "frames per second". You can decrease this number so that the audio visualisation is smoother but this can be expensive!
  tick_rate_milliseconds: 250

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: "/"
  audio_analysis: "v"

Limitations

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.

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

Libraries used

Development

  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

Windows Subsystem for Linux

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

Contributors

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

💻

Finn Vos

💻

Carlos Hernandez

📦

Pedro Alves

💻

jtagcat

📖

Benjamin Kitor

💻

Aleš Najmann

📖 📦

Jeremy Stucki

💻

(´⌣`ʃƪ)

💻

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

Roadmap

The goal is to eventually implement almost every Spotify feature.

High-level requirements yet to be implemented

  • Add songs to a playlist
  • Be able to scroll through result pages in every view

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

API method Implemented yet? Explanation Essential?
track No returns a single track given the track's ID, URI or URL No
tracks No returns a list of tracks given a list of track IDs, URIs, or URLs No
artist No returns a single artist given the artist's ID, URI or URL Yes
artists No returns a list of artists given the artist IDs, URIs, or URLs No
artist_albums Yes Get Spotify catalog information about an artist's top 10 tracks by country. Yes
artist_top_tracks No Get Spotify catalog information about artists similar to an Yes
artist_related_artists No Get Spotify catalog information about artists similar to an identified artist. Similarity is based on analysis of the Spotify community's listening history. Yes
album Yes returns a single album given the album's ID, URIs or URL Yes
albums No returns a list of albums given the album IDs, URIs, or URLs No
search_album Yes Search album based on query Yes
search_artist Yes Search artist based on query Yes
search_track Yes Search track based on query Yes
search_playlist Yes Search playlist based on query Yes
album_track Yes Get Spotify catalog information about an album's tracks Yes
user No Gets basic profile information about a Spotify User No
playlist Yes playlist Yes
current_user_playlists Yes Get current user playlists without required getting his profile Yes
user_playlists No Gets playlists of a user No
user_playlist No Gets playlist of a user No
user_playlist_tracks Yes Get full details of the tracks of a playlist owned by a user Yes
user_playlist_create No Creates a playlist for a user Yes
user_playlist_change_detail No Changes a playlist's name and/or public/private state Yes
user_playlist_unfollow No Unfollows (deletes) a playlist for a user Yes
user_playlist_add_track No Adds tracks to a playlist Yes
user_playlist_replace_track No Replace all tracks in a playlist No
user_playlist_recorder_tracks No Reorder tracks in a playlist No
user_playlist_remove_all_occurrences_of_track No Removes all occurrences of the given tracks from the given playlist No
user_playlist_remove_specific_occurrenes_of_track No Removes all occurrences of the given tracks from the given playlist No
user_playlist_follow_playlist No Add the current authenticated user as a follower of a playlist. Yes
user_playlist_check_follow No Check to see if the given users are following the given playlist Yes
me No Get detailed profile information about the current user. Yes
current_user No Alias for me Yes
current_user_playing_track Yes Get information about the current users currently playing track. Yes
current_user_saved_albums No Gets a list of the albums saved in the current authorized user's "Your Music" library Yes
current_user_saved_tracks Yes Gets the user's saved tracks or "Liked Songs" Yes
current_user_followed_artists No Gets a list of the artists followed by the current authorized user Yes
current_user_saved_tracks_delete No Remove one or more tracks from the current user's "Your Music" library. Yes
current_user_saved_tracks_contain No Check if one or more tracks is already saved in the current Spotify user’s “Your Music” library. Yes
current_user_saved_tracks_add Yes Save one or more tracks to the current user's "Your Music" library. Yes
current_user_top_artists No Get the current user's top artists Yes
current_user_top_tracks No Get the current user's top tracks Yes
current_user_recently_played No Get the current user's recently played tracks Yes
current_user_saved_albums_add No Add one or more albums to the current user's "Your Music" library. Yes
current_user_saved_albums_delete No Remove one or more albums from the current user's "Your Music" library. Yes
user_follow_artists No Follow one or more artists Yes
user_unfollow_artists No Unfollow one or more artists Yes
user_follow_users No Follow one or more users No
user_unfollow_users No Unfollow one or more users No
featured_playlists No Get a list of Spotify featured playlists Yes
new_releases No Get a list of new album releases featured in Spotify Yes
categories No Get a list of new album releases featured in Spotify Yes
recommendations No Get Recommendations Based on Seeds Yes
audio_features No Get audio features for a track No
audios_feature No Get Audio Features for Several Tracks No
audio_analysis No Get Audio Analysis for a Track No
device Yes Get a User’s Available Devices Yes
current_playback Yes Get Information About The User’s Current Playback Yes
current_playing No Get the User’s Currently Playing Track No
transfer_playback No Transfer a User’s Playback No
start_playback Yes Start/Resume a User’s Playback Yes
pause_playback Yes Pause a User’s Playback Yes
next_track Yes Skip User’s Playback To Next Track Yes
previous_track Yes Skip User’s Playback To Previous Track Yes
seek_track No Seek To Position In Currently Playing Track Yes
repeat Yes Set Repeat Mode On User’s Playback Yes
volume No Set Volume For User’s Playback No
shuffle Yes Toggle Shuffle For User’s Playback Yes

Dependencies

~17MB
~323K SLoC