Top Related Projects
Cross-platform ncurses Spotify client written in Rust, inspired by ncmpc and the likes.
A spotify daemon
Open Source Spotify client library
The web version of Tidal running in electron with hifi support thanks to widevine.
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
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.
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.
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.
The web version of Tidal running in electron with hifi support thanks to widevine.
Pros of tidal-hifi
- Focuses on high-fidelity audio streaming from Tidal
- Offers a desktop application for Tidal streaming
- Supports lossless audio formats like FLAC
Cons of tidal-hifi
- Limited to Tidal streaming service only
- May have fewer features compared to spotify-tui
- Potentially smaller user base and community support
Code Comparison
spotify-tui (Rust):
pub fn play(&self) -> Result<()> {
self.spotify.play()?;
Ok(())
}
tidal-hifi (JavaScript):
async play() {
await this.player.play();
}
Both projects implement play functionality, but spotify-tui uses Rust while tidal-hifi uses JavaScript. The spotify-tui implementation handles errors explicitly, while tidal-hifi uses async/await for asynchronous operations.
spotify-tui is a terminal-based Spotify client written in Rust, offering a lightweight and efficient interface for Spotify users. It provides a wide range of features for controlling Spotify playback and managing playlists.
tidal-hifi, on the other hand, is an unofficial desktop client for Tidal, focusing on high-fidelity audio streaming. It caters specifically to Tidal users who prioritize audio quality and want a dedicated desktop application for the service.
The choice between these two projects depends on the user's preferred streaming service (Spotify vs. Tidal) and their priorities regarding audio quality and interface preferences.
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 CopilotREADME
Spotify TUI
A Spotify client for the terminal written in Rust.
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 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 unzipcd
tospotify-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
andClient Secret
- You now can see your
- 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):
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
Cross-platform ncurses Spotify client written in Rust, inspired by ncmpc and the likes.
A spotify daemon
Open Source Spotify client library
The web version of Tidal running in electron with hifi support thanks to widevine.
Command-line tool to customize Spotify client. Supports Windows, MacOS, and Linux.
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