Need help with spotify-tui?
Click the โ€œchatโ€ button below for chat support from the developer who created it, or find similar developers for support.

About the developer

Rigellute
7.1K Stars 246 Forks MIT License 1.2K Commits 86 Opened issues

Description

Spotify for the terminal written in Rust ๐Ÿš€

Services available

!
?

Need anything else?

Contributors list

No Data

Spotify TUI

Continuous Integration Crates.io

All Contributors <!-- ALL-CONTRIBUTORS-BADGE:END -->

Follow Alexander Keliris (Rigellute)

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 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

Nix

Available as the package

spotify-tui
. To install run:
nix-env -iA nixpkgs.spotify-tui

Where

nixpkgs
is the channel name in your configuration. For a more up-to-date installation, use the unstable channel. It is also possible to add the package to
environment.systemPackages
(for NixOS), or
home.packages
when using home-manager.

Void Linux

Available on the official repositories. To install, run

sudo xbps-install -Su spotify-tui

Fedora/CentOS

Available on the Copr repositories. To install, run

sudo dnf copr enable atim/spotify-tui -y && sudo dnf install 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-tui
    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 an app
    • You now can see your
      Client ID
      and
      Client Secret
  3. Now click
    Edit Settings
  4. Add
    http://localhost:8888/callback
    to the Redirect URIs
  5. Scroll down and click
    Save
  6. You are now ready to authenticate with Spotify!
  7. Go back to the terminal
  8. Run
    spt
  9. Enter your
    Client ID
  10. Enter your
    Client Secret
  11. Press enter to confirm the default port (8888) or enter a custom port
  12. You will be redirected to an official Spotify webpage to ask you for permissions.
  13. 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 # current playing song in list banner: LightCyan # the "spotify-tui" banner on launch error_border: Red # error dialog border error_text: LightRed # error message text (e.g. "Spotify API reported error 404") hint: Yellow # hint text in errors hovered: Magenta # hovered pane border inactive: Gray # borders of inactive panes playbar_background: Black # background of progress bar playbar_progress: LightCyan # filled-in part of the progress bar playbar_text: White # artist name in player pane selected: LightCyan # a) selected pane border, b) hovered item in list, & c) track title in player text: "255, 255, 255" # text in panes header: White # header text in panes (e.g. 'Title', 'Artist', etc.)

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

Enable text emphasis (typically italic/bold text styling). Disabling this might be important if the terminal config is otherwise restricted and rendering text escapes interferes with the UI.

enable_text_emphasis: true

Controls whether to show a loading indicator in the top right of the UI whenever communicating with Spotify API

show_loading_indicator: true

Determines the text icon to display next to "liked" Spotify items, such as

liked songs and albums, or followed artists. Can be any length string.

liked_icon: "โ™ฅ"

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: "" next_track: "n" previous_track: "p" copy_song_url: "c" copy_album_url: "C" help: "?" shuffle: "s" repeat: "r" search: "/" audio_analysis: "v" jump_to_context: "o" basic_view: "B" add_item_to_queue: "z"

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

๐Ÿ’ป

(ยดโŒฃ`สƒฦช)

๐Ÿ’ป

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

๐Ÿ“–

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 | | artistalbums | Yes | Get Spotify catalog information about an artist's albums | Yes | | artisttoptracks | Yes | Get Spotify catalog information about an artist's top 10 tracks by country. | Yes | | artistrelatedartists | Yes | 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 | | searchalbum | Yes | Search album based on query | Yes | | searchartist | Yes | Search artist based on query | Yes | | searchtrack | Yes | Search track based on query | Yes | | searchplaylist | Yes | Search playlist based on query | Yes | | albumtrack | Yes | Get Spotify catalog information about an album's tracks | Yes | | user | No | Gets basic profile information about a Spotify User | No | | playlist | Yes | Get full details about Spotify playlist | Yes | | currentuserplaylists | Yes | Get current user playlists without required getting his profile | Yes | | userplaylists | No | Gets playlists of a user | No | | userplaylist | No | Gets playlist of a user | No | | userplaylisttracks | Yes | Get full details of the tracks of a playlist owned by a user | Yes | | userplaylistcreate | No | Creates a playlist for a user | Yes | | userplaylistchangedetail | No | Changes a playlist's name and/or public/private state | Yes | | userplaylistunfollow | Yes | Unfollows (deletes) a playlist for a user | Yes | | userplaylistaddtrack | No | Adds tracks to a playlist | Yes | | userplaylistreplacetrack | No | Replace all tracks in a playlist | No | | userplaylistrecordertracks | No | Reorder tracks in a playlist | No | | userplaylistremovealloccurrencesoftrack | No | Removes all occurrences of the given tracks from the given playlist | No | | userplaylistremovespecificoccurrenesoftrack | No | Removes all occurrences of the given tracks from the given playlist | No | | userplaylistfollowplaylist | Yes | Add the current authenticated user as a follower of a playlist. | Yes | | userplaylistcheckfollow | 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 | | currentuser | No | Alias for

me
| Yes | | currentuserplayingtrack | Yes | Get information about the current users currently playing track. | Yes | | currentusersavedalbums | Yes | Gets a list of the albums saved in the current authorized user's "Your Music" library | Yes | | currentusersavedtracks | Yes | Gets the user's saved tracks or "Liked Songs" | Yes | | currentuserfollowedartists | Yes | Gets a list of the artists followed by the current authorized user | Yes | | currentusersavedtracksdelete | Yes | Remove one or more tracks from the current user's "Your Music" library. | Yes | | currentusersavedtrackscontain | No | Check if one or more tracks is already saved in the current Spotify userโ€™s โ€œYour Musicโ€ library. | Yes | | currentusersavedtracksadd | Yes | Save one or more tracks to the current user's "Your Music" library. | Yes | | currentusertopartists | No | Get the current user's top artists | Yes | | currentusertoptracks | No | Get the current user's top tracks | Yes | | currentuserrecentlyplayed | Yes | Get the current user's recently played tracks | Yes | | currentusersavedalbumsadd | Yes | Add one or more albums to the current user's "Your Music" library. | Yes | | currentusersavedalbumsdelete | Yes | Remove one or more albums from the current user's "Your Music" library. | Yes | | userfollowartists | Yes | Follow one or more artists | Yes | | userunfollowartists | Yes | Unfollow one or more artists | Yes | | userfollowusers | No | Follow one or more users | No | | userunfollowusers | No | Unfollow one or more users | No | | featuredplaylists | No | Get a list of Spotify featured playlists | Yes | | newreleases | No | Get a list of new album releases featured in Spotify | Yes | | categories | No | Get a list of categories used to tag items in Spotify | Yes | | recommendations | Yes | Get Recommendations Based on Seeds | Yes | | audiofeatures | No | Get audio features for a track | No | | audiosfeatures | No | Get Audio Features for Several Tracks | No | | audioanalysis | Yes | Get Audio Analysis for a Track | Yes | | device | Yes | Get a Userโ€™s Available Devices | Yes | | currentplayback | Yes | Get Information About The Userโ€™s Current Playback | Yes | | currentplaying | No | Get the Userโ€™s Currently Playing Track | No | | transferplayback | Yes | Transfer a Userโ€™s Playback | Yes | | startplayback | Yes | Start/Resume a Userโ€™s Playback | Yes | | pauseplayback | Yes | Pause a Userโ€™s Playback | Yes | | nexttrack | Yes | Skip Userโ€™s Playback To Next Track | Yes | | previoustrack | Yes | Skip Userโ€™s Playback To Previous Track | Yes | | seek_track | Yes | Seek To Position In Currently Playing Track | Yes | | repeat | Yes | Set Repeat Mode On Userโ€™s Playback | Yes | | volume | Yes | Set Volume For Userโ€™s Playback | Yes | | shuffle | Yes | Toggle Shuffle For Userโ€™s Playback | Yes |

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.