Rust-Spotify tui: Spotify TUI — A Spotify client for the terminal written in Rust.

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

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 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
  # controls whether to show a loading indicator in the top right of the UI whenever communicating with Spotify API
  show_loading_indicator: true

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

?

(´⌣`ʃƪ)

?

Artem Polishchuk

?

Chris Sosnin

?

Ben Buhse

?

Sean Li

?

TimotheeGerber

? ?

Ferdinand Ratajczak

?

Sheel Choksi

?

Michael Hellwig

?

Oliver Daniel

?

Drew Fisher

?

ncoder-1

?

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 albums Yes
artist_top_tracks Yes Get Spotify catalog information about an artist's top 10 tracks by country. Yes
artist_related_artists 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
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 Get full details about Spotify 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 Yes 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 Yes 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 Yes 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 Yes Gets a list of the artists followed by the current authorized user Yes
current_user_saved_tracks_delete Yes 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 Yes Get the current user's recently played tracks Yes
current_user_saved_albums_add Yes Add one or more albums to the current user's "Your Music" library. Yes
current_user_saved_albums_delete Yes Remove one or more albums from the current user's "Your Music" library. Yes
user_follow_artists Yes Follow one or more artists Yes
user_unfollow_artists Yes 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 categories used to tag items in Spotify Yes
recommendations Yes Get Recommendations Based on Seeds Yes
audio_features No Get audio features for a track No
audios_features No Get Audio Features for Several Tracks No
audio_analysis Yes Get Audio Analysis for a Track Yes
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 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

Comments

  • Bump anyhow from 1.0.43 to 1.0.52
    Bump anyhow from 1.0.43 to 1.0.52

    Jan 1, 2022

    Bumps anyhow from 1.0.43 to 1.0.52.

    Release notes

    Sourced from anyhow's releases.

    1.0.52

    • Reduce overhead of backtrace capture in the case that backtraces are not enabled (#212)

    1.0.51

    • Show doc for Ok fn

    1.0.50

    1.0.49

    • Add a function anyhow::Ok(v) equivalent to Ok::<_, anyhow::Error>(v) (#192)

    1.0.48

    • Include a Debug rendering of lhs and rhs in ensure! messages (#193, #194, #195, #196, #197, #198)

      Example:

      ensure!(flags.len() <= 40);
      
      ensure!(kind == Kind::File);
      

      Before:

      Condition failed: `flags.len() <= 40`
      Condition failed: `kind == Kind::File`
      

      After:

      Condition failed: `flags.len() <= 40` (99 vs 40)
      Condition failed: `kind == Kind::File` (Symlink vs File)
      

    1.0.47

    • Fixes for implicit format args support

    1.0.46

    ... (truncated)

    Commits
    • f871e2f Release 1.0.52
    • 94e2089 Change test suite atomic from SeqCst to Relaxed
    • 42badfd Merge pull request #213 from dtolnay/fixme
    • 5498d85 Annotate expressions that are rendered poorly by core::stringify
    • 6e17bdb Merge pull request #212 from dtolnay/relaxed
    • 6b3630c Change Backtrace::enabled atomic from SeqCst to Relaxed
    • a3f7160 Ignore return_self_not_must_use clippy lint
    • 4d2586b Track raw pointers in miri CI run
    • d40fd32 Merge pull request #211 from dtolnay/ensuretest
    • 2a72017 Update ensure tests to nightly-2021-12-10
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    Reply
  • Bump serde_json from 1.0.67 to 1.0.74
    Bump serde_json from 1.0.67 to 1.0.74

    Jan 1, 2022

    Bumps serde_json from 1.0.67 to 1.0.74.

    Release notes

    Sourced from serde_json's releases.

    v1.0.74

    • Allow creating RawValues from references to unsized values (#841, thanks @​EFanZh)

    v1.0.73

    • Update itoa dependency to 1.0

    v1.0.72

    v1.0.71

    v1.0.70

    v1.0.69

    v1.0.68

    • Preserve negative sign of -0 when deserializing to f32 or f64 (#799, #801)
    Commits
    • 58d40de Release 1.0.74
    • ef7794f Detect warnings in CI
    • 6de3d39 Merge pull request 841 from EFanZh/unsized-value-to-raw-value
    • 012f567 Allow creating RawValues from references to unsized values
    • 18a88da Avoid evaluating $c more than once in overflow macro
    • 5d2cbcd Eliminate lib module
    • 31198f5 Switch to $(,)? in tri macro
    • 51df12e Unconditionally import from alloc
    • 95f67a0 Ignore return_self_not_must_use clippy lint
    • 296f718 Release 1.0.73
    • Additional commits viewable in compare view

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    Reply
  • Bump serde from 1.0.128 to 1.0.132
    Bump serde from 1.0.128 to 1.0.132

    Jan 1, 2022

    Bumps serde from 1.0.128 to 1.0.132.

    Release notes

    Sourced from serde's releases.

    v1.0.132

    • Enable Serialize and Deserialize impls for std::sync::atomic::{AtomicI64, AtomicU64} on riscv64 arch (#2141, thanks @​Avimitin)

    v1.0.131

    • Avoid unused_results being triggered in generated code for adjacently tagged enum (#2116, thanks @​tyranron)

    v1.0.130

    • Provide MapAccess and SeqAccess impl for reference to a dynamically sized existing impl (#2081)

    v1.0.129

    • Support deserialization of remote structs that used packed repr (#2078, #2079, #2080)
    Commits

    Dependabot compatibility score

    Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.


    Dependabot commands and options

    You can trigger Dependabot actions by commenting on this PR:

    • @dependabot rebase will rebase this PR
    • @dependabot recreate will recreate this PR, overwriting any edits that have been made to it
    • @dependabot merge will merge this PR after your CI passes on it
    • @dependabot squash and merge will squash and merge this PR after your CI passes on it
    • @dependabot cancel merge will cancel a previously requested merge and block automerging
    • @dependabot reopen will reopen this PR if it is closed
    • @dependabot close will close this PR and stop Dependabot recreating it. You can achieve the same result by closing it manually
    • @dependabot ignore this major version will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this minor version will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself)
    • @dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
    dependencies 
    Reply
  • Error when trying to open the Darknet Diaries podcast page
    Error when trying to open the Darknet Diaries podcast page

    Jan 4, 2022

    when I try to open the podcast called Darknet Diaries with release 0.25 I get the following error:

    image

    It is consistently happening. I have not seen the problem with any other podcast or playlists.

    My guess is that one of the names has some strange unicode char in it but the TUI should probably support that as well.

    Reply
  • The key binding
    The key binding "submit" does not work.

    Jan 4, 2022

    When loading the config, "submit" is enabled, but it doesn't actually work.

    https://github.com/Rigellute/spotify-tui/blob/451be07710315633471fa96e1f0f75c5fd24b547/src/user_config.rs#L170

    I want to set the key binding "submit" to ctrl-j .

    Reply
  • added support for RTL texts (hebrew & arabic)
    added support for RTL texts (hebrew & arabic)

    Jan 10, 2022

    Fixing #518

                                                                                                                                                                                                           
    Reply
  • thread '<unnamed>' panicked at 'called `Result::unwrap()`
    thread '' panicked at 'called `Result::unwrap()`

    Oct 15, 2019

    thread '' panicked at 'called Result::unwrap() on an Err value: Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/libcore/result.rs:999:5 note: run with RUST_BACKTRACE=1 environment variable to display a backtrace.

    Reply
  • Provide a cli arg based interface
    Provide a cli arg based interface

    May 3, 2020

    I want to trigger commands that goes through spotify-tui but doesn't open the UI. For starters support for search/play/pause through command line would be really good to have.

    spt -s --search "a man of wire" // returns top n results spt -p --play "song name" // based on closest match, start playing this song spt -t --toggle // toggle play pause

    Reply
  • Enable github workflow for snaps.
    Enable github workflow for snaps.

    Feb 13, 2020

    Please add secrets to repo before accepting pull request. See email. If you have any question please fee free to contact me via email.

    Reply
  • Extremely slow
    Extremely slow

    Jan 10, 2020

    The app barely responds for me. I'll type ? and it will take a minute or more before anything happens. It seems to work, e.g. connect to Spotify and has all my music, but it is delayed heavily with every action. I'm not sure if this is known, it might be the same bug as #92 but for me it was never "unfrozen".

    I got spotifyd and spotify-tui from the AUR.

    Versions: Operating System: Arch Linux Kernel: Linux 5.4.8-arch1-1 spotifyd 0.2.20 spotify-tui 0.11.0

    help wanted 
    Reply
  • no device is found
    no device is found

    Feb 24, 2020

    installed spotifyd and spt. run spotifyd

     ps -ef | grep spotify
    jose     11868     1  0 12:40 ?        00:00:00 spotifyd
    jose     11885 11656  0 12:40 pts/4    00:00:00 grep --color=auto --exclude-dir=.bzr --exclude-dir=CVS --exclude-dir=.git --exclude-dir=.hg --exclude-dir=.svn spotify
    

    run spt (installed via snap)

    2020-02-24_12-42

    Reply
  • Exceeded API request limit
    Exceeded API request limit

    Apr 5, 2021

    I keep getting

    Error: Exceeded API request limit - please wait x seconds 
    

    when interacting with the tui or through spt pb. Am I doing something wrong?

    Reply