Home

Awesome

spotify_player

Table of Contents

Introduction

spotify_player is a fast, easy to use, and configurable terminal music player.

Features

Examples

A demo of spotify_player v0.5.0-pre-release on youtube or on asciicast:

Checkout examples/README.md for more examples.

Installation

By default, the application's installed binary is spotify_player.

Requirements

A Spotify Premium account is required.

Dependencies

Windows and MacOS
Linux

Binaries

Application's prebuilt binaries can be found in the Releases Page.

Note: to run the application, Linux systems need to install additional dependencies as specified in the Dependencies section.

Homebrew

Run brew install spotify_player to install the application.

Scoop

Run scoop install spotify-player to install the application.

Cargo

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

AUR

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

Alternatively, run yay -S spotify-player-full-pipe to install an AUR package compiled with full feature support and Pulseaudio/Pipewire instead of rodio.

Void Linux

Run xbps-install -S spotify-player to install the application.

FreeBSD

Run pkg install spotify-player to install the spotify_player binary from FreeBSD ports.

NetBSD

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

Docker

Note: streaming feature is disabled when using the 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 application's cache data 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

Features

Spotify Connect

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

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

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.

Streaming

spotify_player supports streaming, which needs to be built/installed with streaming feature (enabled by default) and with an audio backend (rodio-backend by default). The streaming feature allows to spotify_player to play music directly from terminal.

The application uses librespot library to create an integrated Spotify client while running. The integrated client will register a Spotify speaker device under the spotify-player name, which is accessible on the Spotify connect device list.

Audio backend

spotify_player uses rodio as the default audio backend. List of available audio backends:

User can change the audio backend when building/installing the application by specifying the --features option. For example, to install spotify_player with pulseaudio-backend, run

cargo install spotify_player --no-default-features --features pulseaudio-backend

Note:

The streaming feature can be also disabled upon installing by running

cargo install spotify_player --no-default-features

Lyric

To enable lyric support, spotify_player needs to be built/installed with lyric-finder feature (disabled by default). To install the application with lyric-finder feature included run:

cargo install spotify_player --features lyric-finder

User can view lyric of the currently playing track by calling the LyricPage command to go the lyric page. To do this, spotify_player needs to be built with a lyric-finder feature.

Under the hood, spotify_player retrieves the song's lyric using Genius.com.

Media Control

To enable media control support, spotify_player needs to be built/installed with media-control feature (enabled by default) and set the enable_media_control config option to true in the general configuration file.

Media control support is implemented using MPRIS DBus on Linux and OS window event listener on Windows and MacOS.

Image

To enable image rendering support, spotify_player needs to be built/installed with image feature (disabled by default). To install the application with image feature included, run:

cargo install spotify_player --features image

spotify_player supports rendering image in a full resolution if the application is run on either Kitty or iTerm2. Otherwise, the image will be displayed as block characters.

spotify_player also supports rendering images with sixel behind sixel feature flag, which also enables image feature:

cargo install spotify_player --features sixel

Notes:

Examples of image rendering:

iTerm2

kitty

sixel

others

Notify

To enable desktop notification support, spotify_player needs to be built/installed with notify feature (disabled by default). To install the application with notify feature included, run:

cargo install spotify_player --features notify

Note: the notification support in MacOS and Windows are quite restricted compared to Linux.

Mouse support

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

Daemon

To enable a daemon support, spotify_player needs to be built/installed with daemon feature (disabled by default). To install the application with daemon feature included, run:

cargo install spotify_player --features daemon

You can run the application as a daemon by specifying the -d or --daemon option: spotify_player -d.

Notes:

Fuzzy search

To enable fuzzy search support, spotify_player needs to be built/installed with fzf feature (disabled by default).

CLI Commands

spotify_player offers several CLI commands to interact with Spotify:

For more details, run spotify_player -h or spotify_player {command} -h, in which {command} is a CLI command.

Notes

Commands

To go to the shortcut help page, press ? or C-h (default shortcuts for OpenCommandHelp command).

Tips:

List of supported commands:

CommandDescriptionDefault shortcuts
NextTracknext trackn
PreviousTrackprevious trackp
ResumePauseresume/pause based on the current playbackspace
PlayRandomplay a random track in the current context.
Repeatcycle the repeat modeC-r
ToggleFakeTrackRepeatModetoggle fake track repeat modeM-r
Shuffletoggle the shuffle modeC-s
VolumeUpincrease playback volume by 5%+
VolumeDowndecrease playback volume by 5%-
Mutetoggle playback volume between 0% and previous level_
SeekForwardseek forward by 5s>
SeekBackwardseek backward by 5s<
Quitquit the applicationC-c, q
ClosePopupclose a popupesc
SelectNextOrScrollDownselect the next item in a list/table or scroll downj, C-n, down
SelectPreviousOrScrollUpselect the previous item in a list/table or scroll upk, C-p, up
PageSelectNextOrScrollDownselect the next page item in a list/table or scroll a page downpage_down, C-f
PageSelectPreviousOrScrollUpselect the previous page item in a list/table or scroll a page uppage_up, C-b
SelectFirstOrScrollToTopselect the first item in a list/table or scroll to the topg g, home
SelectLastOrScrollToBottomselect the last item in a list/table or scroll to the bottomG, end
ChooseSelectedchoose the selected itementer
RefreshPlaybackmanually refresh the current playbackr
RestartIntegratedClientrestart the integrated client (streaming feature only)R
ShowActionsOnSelectedItemopen a popup showing actions on a selected itemg a, C-space
ShowActionsOnCurrentTrackopen a popup showing actions on the current tracka
AddSelectedItemToQueueadd the selected item to queueZ, C-z
FocusNextWindowfocus the next focusable window (if any)tab
FocusPreviousWindowfocus the previous focusable window (if any)backtab
SwitchThemeopen a popup for switching themeT
SwitchDeviceopen a popup for switching deviceD
Searchopen a popup for searching in the current page/
BrowseUserPlaylistsopen a popup for browsing user's playlistsu p
BrowseUserFollowedArtistsopen a popup for browsing user's followed artistsu a
BrowseUserSavedAlbumsopen a popup for browsing user's saved albumsu A
CurrentlyPlayingContextPagego to the currently playing context pageg space
TopTrackPagego to the user top track pageg t
RecentlyPlayedTrackPagego to the user recently played track pageg r
LikedTrackPagego to the user liked track pageg y
LyricPagego to the lyric page of the current track (lyric-finder feature only)g L, l
LibraryPagego to the user library pageg l
SearchPagego to the search pageg s
BrowsePagego to the browse pageg b
Queuego to the queue pagez
OpenCommandHelpgo to the command help page?, C-h
PreviousPagego to the previous pagebackspace, C-q
OpenSpotifyLinkFromClipboardopen a Spotify link from clipboardO
SortTrackByTitlesort the track table (if any) by track's titles t
SortTrackByArtistssort the track table (if any) by track's artistss a
SortTrackByAlbumsort the track table (if any) by track's albums A
SortTrackByAddedDatesort the track table (if any) by track's added dates D
SortTrackByDurationsort the track table (if any) by track's durations d
ReverseOrderreverse the order of the track table (if any)s r
MovePlaylistItemUpmove playlist item up one positionC-k
MovePlaylistItemDownmove playlist item down one positionC-j
CreatePlaylistcreate a new playlistN
JumpToCurrentTrackInContextjump to the current track in the contextg c

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

Actions

A general list of actions is available; however, not all Spotify items (track, album, artist, or playlist) implement each action. To get the list of available actions on an item, call the ShowActionsOnCurrentTrack command or the ShowActionsOnSelectedItem command, then press enter (default binding for the ChooseSelected command) to initiate the selected action. Some actions may not appear in the popup but can be bound to a shortcut.

List of available actions:

These actions can also be bound to a shortcut. To add new shortcuts, please refer to the actions section in the configuration documentation.

Search Page

When first entering the search page, the application focuses on the search input. User can then 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.

Configurations

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.

If an application configuration file is not found, one will be created with default values.

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

Caches

By default, spotify_player will look into $HOME/.cache/spotify-player for application's cache files, which include log files, Spotify's authorization credentials, audio cache files, etc. This can be changed by either specifying -C <FOLDER_PATH> or --cache-folder <FOLDER_PATH> option.

Logging

The application stores logs inside the $APP_CACHE_FOLDER/spotify-player-*.log file. For debugging or submitting an issue, user can also refer to the backtrace file in $APP_CACHE_FOLDER/spotify-player-*.backtrace, which includes the application's backtrace in case of panics/unexpected errors.

spotify_player uses RUST_LOG environment variable to define the application's logging level. RUST_LOG is default to be spotify_player=INFO, which only shows the application's logs.

Acknowledgement

spotify_player is written in Rust and is built on top of awesome libraries such as tui-rs, rspotify, librespot, and many more. It's highly inspired by spotify-tui and ncspot.