spotify-tui

Spotify for the terminal written in Rust 🚀

17,300

518

17,300

298

View on GitHub

Top Related Projects

ncspot

4,927

Cross-platform ncurses Spotify client written in Rust, inspired by ncmpc and the likes.

cli

18,087

Command-line tool to customize Spotify client. Supports Windows, MacOS, and Linux.

Quick Overview

Spotify TUI is a terminal-based Spotify client written in Rust. It provides a text-based user interface for controlling Spotify playback, managing playlists, and browsing music, all from within the command line.

Pros

Lightweight and fast, consuming minimal system resources
Customizable interface with various color schemes and layouts
Keyboard-driven navigation for efficient music management
Works well on remote servers or systems without graphical interfaces

Cons

Requires Spotify Premium account for full functionality
Limited visual representation compared to graphical Spotify clients
May have a steeper learning curve for users unfamiliar with terminal interfaces
Dependent on the Spotify API, which can sometimes lead to rate limiting or temporary issues

Getting Started

Install Rust and Cargo (Rust's package manager)
Install spotify-tui:
```
cargo install spotify-tui
```
Set up Spotify API credentials:
- Create a Spotify Developer account
- Create a new application to get Client ID and Client Secret
- Set environment variables:
```
export SPOTIFY_CLIENT_ID="your_client_id"
export SPOTIFY_CLIENT_SECRET="your_client_secret"
```
Run spotify-tui:
```
spt
```
Follow the authentication process to link your Spotify account

Once set up, you can use keyboard shortcuts to navigate the interface, search for music, manage playlists, and control playback. Refer to the project's documentation for a full list of commands and features.

Competitor Comparisons

ncspot

4,927

Cross-platform ncurses Spotify client written in Rust, inspired by ncmpc and the likes.

Pros of ncspot

Written in Rust, potentially offering better performance and memory safety
Supports offline mode for playing downloaded tracks
Includes a built-in equalizer for audio adjustment

Cons of ncspot

Less extensive feature set compared to spotify-tui
Smaller community and fewer contributors
Limited customization options for the user interface

Code Comparison

spotify-tui (TypeScript):

pub fn play_track(&mut self, track_id: &str) -> Result<(), Error> {
    self.spotify.start_playback(None, None, Some(&[track_id]), None, None)?;
    Ok(())
}

ncspot (Rust):

pub fn play_track(&mut self, track_id: &str) -> Result<(), SpotifyError> {
    self.spotify.start_playback(None, None, Some(&[track_id]), None)?;
    Ok(())
}

Both projects implement similar functionality for playing tracks, with ncspot's implementation being slightly more concise due to Rust's language features.

spotify-tui is a feature-rich, customizable Spotify client for the terminal, written in Rust. It offers a wide range of functionalities and a highly interactive user interface. ncspot, also written in Rust, provides a more streamlined experience with some unique features like offline mode and an equalizer. While spotify-tui may be more suitable for users seeking extensive customization and features, ncspot could be preferable for those prioritizing performance and specific audio-related capabilities.

spotifyd

9,785

A spotify daemon

Pros of spotifyd

Acts as a Spotify client, allowing playback without a web browser or official app
Lightweight and runs as a daemon, consuming fewer system resources
Supports remote control via MPRIS, enabling integration with various music players and tools

Cons of spotifyd

Limited to audio playback functionality, lacking a user interface for browsing and managing playlists
Requires separate tools or scripts for controlling playback and managing Spotify content
May require more technical setup and configuration compared to full-featured Spotify clients

Code Comparison

spotify-tui (Rust):

pub fn play(&self) -> Result<()> {
    self.spotify.start_playback(None, None, None, None, None)
}

spotifyd (Rust):

fn play(&self) -> Result<()> {
    self.player.play()
}

Both projects are written in Rust and provide similar play functionality. However, spotify-tui interacts with the Spotify API directly, while spotifyd controls local playback through its own player implementation.

spotify-tui offers a feature-rich terminal user interface for browsing and controlling Spotify, making it more suitable for users who want a complete Spotify experience in the terminal. spotifyd, on the other hand, focuses on providing a lightweight Spotify playback daemon, which can be controlled through external tools or scripts, making it ideal for users who prefer a modular approach or want to integrate Spotify playback into other applications or workflows.

librespot

4,702

Open Source Spotify client library

Pros of librespot

Provides a full Spotify client library, allowing for more comprehensive integration and control
Supports audio playback directly, enabling standalone Spotify playback applications
Written in Rust, offering potential performance benefits and memory safety

Cons of librespot

More complex to set up and use, requiring deeper technical knowledge
Lacks a built-in user interface, necessitating additional development for UI components
May have potential legal concerns due to reverse-engineering the Spotify protocol

Code Comparison

spotify-tui (Rust):

pub fn new(config: Config, spotify_client: SpotifyClient) -> App {
    App {
        library: Library::default(),
        playlists: Vec::new(),
        // ...
    }
}

librespot (Rust):

pub struct Session {
    country: String,
    device_id: String,
    // ...
}

impl Session {
    pub fn connect(
        config: SessionConfig,
        credentials: Credentials,
        // ...
    ) -> Result<(Session, SessionEvent), Error> {
        // ...
    }
}

The code snippets show that spotify-tui focuses on the application structure and user interface, while librespot deals with low-level session management and Spotify protocol implementation.

cli

18,087

Command-line tool to customize Spotify client. Supports Windows, MacOS, and Linux.

Pros of spicetify

Offers extensive customization options for the official Spotify client
Supports custom themes and extensions
Allows for modifying the Spotify app's CSS and JavaScript

Cons of spicetify

Requires the official Spotify desktop client to be installed
May break with Spotify updates, requiring frequent maintenance
More complex setup process compared to spotify-tui

Code Comparison

spotify-tui (Rust):

pub fn play_track(spotify: &Spotify, track_id: &str) -> Result<()> {
    let track_uri = format!("spotify:track:{}", track_id);
    spotify.start_playback(None, None, Some(vec![track_uri]), None, None)
}

spicetify (JavaScript):

function playTrack(uri) {
    Spicetify.Player.playUri(uri);
}

Summary

spotify-tui is a terminal-based Spotify client written in Rust, offering a lightweight and fast interface for controlling Spotify playback. It's ideal for users who prefer command-line interfaces and minimal resource usage.

spicetify, on the other hand, is a powerful customization tool for the official Spotify desktop client. It allows users to modify the appearance and functionality of the Spotify app through custom themes, extensions, and CSS/JS modifications.

While spotify-tui provides a standalone TUI experience, spicetify enhances the existing Spotify client, offering more extensive customization options at the cost of increased complexity and dependence on the official app.

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Spotify TUI

A Spotify client for the terminal written in Rust.

Demo

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

Spotify TUI
- Installation
  - Homebrew
  - Snap
  - AUR
  - Nix
  - Void Linux
  - Fedora/CentOS
  - Cargo
    - Note on Linux
  - Windows
    - Scoop installer
  - Manual
- Connecting to Spotifyâs API
- Usage
Configuration

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 the same command again.

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

Download the latest binary for your OS.
cd to the file you just downloaded and unzip
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:

Go to the Spotify dashboard
Click Create an app
- You now can see your Client ID and Client Secret
Now click Edit Settings
Add http://localhost:8888/callback to the Redirect URIs
Scroll down and click Save
You are now ready to authenticate with Spotify!
Go back to the terminal
Run spt
Enter your Client ID
Enter your Client Secret
Press enter to confirm the default port (8888) or enter a custom port
You will be redirected to an official Spotify webpage to ask you for permissions.
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. (for snap ${HOME}/snap/spt/current/.config/spotify-tui/client.yml)

Usage

The binary is named spt.

Running spt 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 spt --help to learn more.

Here are some example to get you excited.

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

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

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

spt 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
spt search "An even cooler song" --tracks --format "%t from %b" --limit 30

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_progress_text: Cyan # song length and time played/left indicator in 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
  # Disables the responsive layout that makes the search bar smaller on bigger
  # screens and enforces a wide search bar
  enforce_wide_search_bar: false
  # 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.
  # These icons require a patched nerd font.
  liked_icon: â¥
  shuffle_icon: ð
  repeat_track_icon: ð
  repeat_context_icon: ð
  playing_icon: â¶
  paused_icon: â¸
  # Sets the window title to "spt - Spotify TUI" via ANSI escape code.
  set_window_title: 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: "ctrl-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.

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

Libraries used

Development

Install OpenSSL
Install Rust
Install xorg-dev (required for clipboard support)
Clone or fork this repo and cd to it
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} ð»	_MCO ð	_{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!

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	Yes	Transfer a Userâs Playback	Yes
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

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

Top Related Projects

Quick Overview

Pros

Cons

Getting Started

Competitor Comparisons

Pros of ncspot

Cons of ncspot

Code Comparison

Pros of spotifyd

Cons of spotifyd

Code Comparison

Pros of librespot

Cons of librespot

Code Comparison

Pros of spicetify

Cons of spicetify

Code Comparison

Summary

Convert designs to code with AI

README

Spotify TUI

Installation

Homebrew

Snap

AUR

Nix

Void Linux

Fedora/CentOS

Cargo

Note on Linux

Windows 10

Scoop installer

Manual

Connecting to Spotifyâs API

Usage

Configuration

Limitations

Using with spotifyd

Libraries used

Development

Windows Subsystem for Linux

Contributors

Roadmap

High-level requirements yet to be implemented

Top Related Projects

Convert designs to code with AI

Connecting to Spotifyâs API