spotify-player

Table of Contents

• Introduction
• Examples
  • Demo
• Installation
• Features
  • Spotify Connect
  • Streaming
  • Lyric
  • Media Control
  • Image
  • Mouse support
• Commands
• Configurations
• Caches
  • Logging
• Acknowledgement

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, allow to easily customize application's shortcuts or theme/color scheme.
• 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.

Examples

Demo

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

Playlist page

Artist page

Album page

Search page

Lyric page

Command help popup

Recommendation page

Installation

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
• openssl, alsa-lib (streaming feature), libdbus (media-control feature) system libraries.
  • On Debian based systems, run the below command to install application's dependencies:

    sudo apt install libssl-dev libasound2-dev libdbus-1-dev
    

  • On Fedora based systems, run the below command to install application's dependencies:

    sudo yum install openssl-devel alsa-lib-devel dbus-devel
    

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.

Cargo

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

AUR

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

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.

An example of using Spotify connect to interact with the Spotify's official application:

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 because rodio-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 --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 --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.

Examples of image rendering:

• iTerm2:

• Kitty:

• Others:

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.

Commands

To open a shortcut help popup, 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-n, down
SelectPreviousOrScrollUp	select the previous item in a list/table or scroll up	k, C-p, up
ChooseSelected	choose the selected item	enter
RefreshPlayback	manually refresh the current playback	r
RestartIntegratedClient	restart the integrated librespot 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
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
PreviousPage	go to the previous page	backspace, C-q
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.

Tips:

• 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.

Actions

A list of actions is available for each type of Spotify item (track, album, artist, or playlist). For example, the list of available actions on a track is [BrowseAlbum, BrowseArtist, BrowseRecommandations, AddToPlaylist, DeleteFromCurrentPlaylist, AddToLikedTracks, DeleteFromLikedTracks].

To get the list of actions on an item, call the ShowActionsOnCurrentTrack command or ShowActionsOnSelectedItem command, then press enter (default binding for ChooseSelected command) to initiate the selected action.

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.

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.