Awesome
spotify_player
Table of Contents
Introduction
spotify_player
is a fast, easy to use, and configurable terminal music player.
Features
- Minimalist UI with an intuitive paging and popup system.
- Highly configurable
- Feature parity with the official Spotify application.
- Support remote control with Spotify Connect.
- Support streaming songs directly from the terminal.
- Support lyric for most songs.
- Support cross-platform media control.
- Support image rendering.
- Support desktop notification.
- Support running the application as a daemon
- Offer a wide range of CLI commands
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
- Rust and cargo as the build dependencies
Linux
-
Rust and cargo as the build dependencies
-
install
openssl
,alsa-lib
(streaming
feature),libdbus
(media-control
feature).-
For example, on Debian based systems, run the below command to install application's dependencies:
sudo apt install libssl-dev libasound2-dev libdbus-1-dev
-
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:
alsa-backend
pulseaudio-backend
rodio-backend
portaudio-backend
jackaudio-backend
rodiojack-backend
sdl-backend
gstreamer-backend
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:
- needs to specify
--no-default-features
here becauserodio-backend
is one of the default features. - user will need to install additional dependencies depending on the selected audio backend. More details can be found in the Librespot documentation.
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:
- Not all terminals supported by libsixel are supported by
spotify_player
as it relies on a third-party library for image rendering. A possible list of supported terminals can be found in here. - Images rendered by
sixel
can have a weird scale. It's recommended to tweak thecover_img_scale
config option to get the best result as the scaling works differently with different terminals and fonts.
Examples of image rendering:
- iTerm2:
- Kitty:
- Sixel (
foot
terminal,cover_img_scale=1.8
):
- 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:
-
daemon
feature is not supported on Windows -
daemon
feature requires thestreaming
feature to be enabled and the application to be built with an audio backend -
because of the OS's restrictions,
daemon
feature doesn't work with themedia-control
feature on MacOS, which is enabled by default. In other words, if you want to use thedaemon
feature on MacOS, you must install the application withmedia-control
feature disabled:cargo install spotify_player --no-default-features --features daemon,rodio-backend
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:
get
: Get Spotify data (playlist/album/artist data, user's data, etc)playback
: Interact with the playback (start a playback, play-pause, next, etc)connect
: Connect to a Spotify devicelike
: Like currently playing trackauthenticate
: Authenticate the applicationplaylist
: Playlist editing (new, delete, import, fork, etc)
For more details, run spotify_player -h
or spotify_player {command} -h
, in which {command}
is a CLI command.
Notes
- When using the CLI for the first time, you'll need to run
spotify_player authenticate
to authenticate the application beforehand. - Under the hood, CLI command is handled by sending requests to a
spotify_player
client socket running on portclient_port
, a general application configuration with a default value of8080
. If there is no running application's instance, a new client will be created upon handling the CLI commands, which increases the latency of the command.
Commands
To go to the shortcut help page, press ?
or C-h
(default shortcuts for OpenCommandHelp
command).
Tips:
- you can search in the shortcut help page (and some other pages) using
Search
command RefreshPlayback
can be used to manually update the playback status.RestartIntegratedClient
is useful when user wants to switch to another audio device (headphone, earphone, etc) without restarting the application, as the integrated client will be re-initialized with the new device.
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 |
ToggleFakeTrackRepeatMode | toggle fake track repeat mode | M-r |
Shuffle | toggle the shuffle mode | C-s |
VolumeUp | increase playback volume by 5% | + |
VolumeDown | decrease playback volume by 5% | - |
Mute | toggle playback volume between 0% and previous level | _ |
SeekForward | seek forward by 5s | > |
SeekBackward | seek backward by 5s | < |
Quit | quit the application | C-c , q |
ClosePopup | close a popup | esc |
SelectNextOrScrollDown | select the next item in a list/table or scroll down | j , C-n , down |
SelectPreviousOrScrollUp | select the previous item in a list/table or scroll up | k , C-p , up |
PageSelectNextOrScrollDown | select the next page item in a list/table or scroll a page down | page_down , C-f |
PageSelectPreviousOrScrollUp | select the previous page item in a list/table or scroll a page up | page_up , C-b |
SelectFirstOrScrollToTop | select the first item in a list/table or scroll to the top | g g , home |
SelectLastOrScrollToBottom | select the last item in a list/table or scroll to the bottom | G , end |
ChooseSelected | choose the selected item | enter |
RefreshPlayback | manually refresh the current playback | r |
RestartIntegratedClient | restart the integrated client (streaming feature only) | R |
ShowActionsOnSelectedItem | open a popup showing actions on a selected item | g a , C-space |
ShowActionsOnCurrentTrack | open a popup showing actions on the current track | a |
AddSelectedItemToQueue | add the selected item to queue | Z , C-z |
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 |
Search | open a popup for searching in the current page | / |
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 |
CurrentlyPlayingContextPage | go to the currently playing context page | g space |
TopTrackPage | go to the user top track page | g t |
RecentlyPlayedTrackPage | go to the user recently played track page | g r |
LikedTrackPage | go to the user liked track page | g y |
LyricPage | go to the lyric page of the current track (lyric-finder feature only) | g L , l |
LibraryPage | go to the user library page | g l |
SearchPage | go to the search page | g s |
BrowsePage | go to the browse page | g b |
Queue | go to the queue page | z |
OpenCommandHelp | go to the command help page | ? , C-h |
PreviousPage | go to the previous page | backspace , C-q |
OpenSpotifyLinkFromClipboard | open a Spotify link from clipboard | O |
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 |
SortTrackByAddedDate | sort the track table (if any) by track's added date | s D |
SortTrackByDuration | sort the track table (if any) by track's duration | s d |
ReverseOrder | reverse the order of the track table (if any) | s r |
MovePlaylistItemUp | move playlist item up one position | C-k |
MovePlaylistItemDown | move playlist item down one position | C-j |
CreatePlaylist | create a new playlist | N |
JumpToCurrentTrackInContext | jump to the current track in the context | g 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:
GoToArtist
GoToAlbum
GoToRadio
AddToLibrary
AddToPlaylist
AddToQueue
AddToLiked
DeleteFromLiked
DeleteFromLibrary
DeleteFromPlaylist
ShowActionsOnAlbum
ShowActionsOnArtist
ToggleLiked
CopyLink
Follow
Unfollow
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.