#spotify #tui #player

app spotify_player

A command driven spotify player

5 releases (3 breaking)

new 0.4.0 Oct 24, 2021
0.3.0 Oct 9, 2021
0.2.0 Sep 8, 2021
0.1.1 Aug 18, 2021
0.1.0 Aug 15, 2021

#73 in Unix APIs

31 downloads per month

MIT license



Table of Contents


  • spotify-player is a fast, easy to use, and configurable Spotify player.
  • spotify-player is designed to be a player, not a fully-fledged Spotify clone, so it does not aim to support all possible Spotify features. Its main goal is to provide a quick and intuitive way to control music using commands.
  • spotify-player is built on top of tui, rspotify, and librespot libraries. It's inspired by spotify-tui and ncspot.
  • spotify-player can be used as either a remote player to control a running Spotify client or a local player with an integrated Spotify client. On startup, the application will connect to the currently running Spotify client. If not exist such client, user will need to use Spotify connect to connect to an available client.


User will need to have a Spotify Premium account to use all application's supported features.

Spotify Connect

To enable Spotify connect support, user will need to register a Spotify application and specify their own client_id in the application's general configuration file as described in the configuration documentation.

More details on registering a Spotify application can be found in the Spotify documentation.

Note: when using the default value for client_id, spotify-player can still be used as a remote player but it requires to have a running Spotify client before starting the application.

When spotify_player runs with your own client_id, press D (default shortcut for SwitchDevice command) to get the list of available devices then press enter (default shortcut for ChooseSelected command) to connect to the selected device.


spotify-player supports streaming by using librespot library to create an integrated Spotify client while running. User will need to use their own client_id to connect to the integrated client as described in the Spotify Connect section. By default, the integrated client will create a Spotify device under spotify-player name.

Note: using an integrated client can result in a slow startup time to connect to the player and retrieve the playback data. I'm still investigating on how to improve the startup time.

The integrated client will use rodio as the default audio backend. List of available backends:

  • alsa-backend
  • pulseaudio-backend
  • rodio-backend
  • portaudio-backend
  • jackaudio-backend
  • rodiojack-backend
  • sdl-backend
  • gstreamer-backend

User can change the audio backend when building the application by specifying the --features option. For example, to build spotify-player with pulseaudio-backend, run

cargo build --release --no-default-features --features pulseaudio-backend

Note: user will need additional dependencies depending on the selected audio backend. More details on compiling can be found in the Librespot documentation.

User can also disable the streaming feature by running

cargo build --release --no-default-features



Run cargo install spotify_player to install the application from crates.io.


Run yay -S spotify-player to install the application as an AUR package.


Using the package manager, run pkgin install spotify-player to install from the official repositories.

Building from source,

cd /usr/pkgsrc/audio/spotify-player
make install


Note: streaming feature is disabled when using docker image.

You can download the binary image of the latest build from the master branch by running

docker pull aome510/spotify_player:latest

then run

docker run --rm -it aome510/spotify_player:latest

to run the application.

You can also use your local config folder to configure the application or your local cache folder to store the authorization token when running the docker image:

docker run --rm \
-v $APP_CONFIG_FOLDER:/app/config/ \
-v $APP_CACHE_FOLDER:/app/cache/ \
-it aome510/spotify_player:latest



A demo of spotify-player v0.1.0:



Playlist context example


Artist context example


Album context example


Search page example


To open a command shortcut help popup when running the application, press ? or C-h (default shortcuts for OpenCommandHelp command).

List of supported commands:

Command Description Default shortcuts
NextTrack next track n
PreviousTrack previous track p
ResumePause resume/pause based on the current playback space
PlayRandom play a random track in the current context .
Repeat cycle the repeat mode C-r
Shuffle toggle the shuffle mode C-s
VolumeUp increase playback volume by 5% +
VolumeDown decrease playback volume by 5% -
Quit quit the application C-c, q
OpenCommandHelp open a command help popup ?, C-h
ClosePopup close a popup esc
SelectNextOrScrollDown select the next item in a list/table or scroll down j, C-j, down
SelectPreviousOrScrollUp select the previous item in a list/table or scroll up k, C-k, up
ChooseSelected choose the selected item enter
RefreshPlayback manually refresh the current playback r
ShowActionsOnSelectedItem show actions on a selected item g a, C-space
ShowActionsOnCurrentTrack show actions on the currently playing track a
FocusNextWindow focus the next focusable window (if any) tab
FocusPreviousWindow focus the previous focusable window (if any) backtab
SwitchTheme open a popup for switching theme T
SwitchDevice open a popup for switching device D
SearchContext open a popup for searching the current context /
BrowseUserPlaylists open a popup for browsing user's playlists u p
BrowseUserFollowedArtists open a popup for browsing user's followed artists u a
BrowseUserSavedAlbums open a popup for browsing user's saved albums u A
BrowsePlayingContext browse the current playing context g space
SearchPage go to the search page g s
PreviousPage go to the previous page backspace, C-p
SortTrackByTitle sort the track table (if any) by track's title s t
SortTrackByArtists sort the track table (if any) by track's artists s a
SortTrackByAlbum sort the track table (if any) by track's album s A
SortTrackByDuration sort the track table (if any) by track's duration s d
SortTrackByAddedDate sort the track table (if any) by track's added date s D
ReverseOrder reverse the order of the track table (if any) s r

To add new shortcuts or modify the default shortcuts, please refer to the keymaps section in the configuration documentation.


There will be a list of possible actions depending on the type of the corresponding Spotify item (track, album, artist, or playlist). For example, the list of available actions on a track is [BrowseAlbum, BrowseArtist, BrowseRecommandations, AddTrackToPlaylist, SaveToLibrary].

To get the list of actions on an item, call the ShowActionsOnCurrentTrack command or ShowActionsOnSelectedItem command.

Search Page

When first entering the search page, the application places a focus on the search input. User can input text, delete one character backward using backspace, or search the text using enter.

To move the focus from the search input to the other windows such as track results, album results, etc, use FocusNextWindow or FocusPreviousWindow.

Mouse support

Currently, the only use case of mouse is to seek to a position of the current playback by left-clicking to such position in the playback's progress bar.


By default, spotify-player will look into $HOME/.config/spotify-player for application's configuration files. This can be changed by either specifying -c <FOLDER_PATH> or --config-folder <FOLDER_PATH> option.

Please refer to the configuration documentation for more details on the configuration options.


  • integrate Spotify's search APIs
  • integrate Spotify's recommendation API
  • add supports for add track to playlist, save album, follow artist, and related commands.
  • integrate Spotify's recently played API
  • handle networking error when running
  • add a (optional?) integrated spotify client (possibly use librespot)
    • implement a custom connection logic to replace librespot's spirc.
  • add mpris (dbus) support


~558K SLoC