spotify-player

Table of Contents

• Introduction
• Examples
  • Demo
• Installation
  • Requirements
• Spotify Connect
• Streaming
• Commands
  • Actions
  • Search Page
• Mouse support
• Configurations
• Caches
  • Logging
• Roadmap

Introduction

• spotify-player is a fast, easy to use, and configurable terminal music player.
• spotify-player is designed to be a player, not a fully-fledged Spotify clone, so it does not aim to support all 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 awesome libraries such as tui-rs, rspotify, librespot, and many more. It's highly inspired by spotify-tui and ncspot.
• spotify-player can be used as either a remote player to control another Spotify client or a local player with an integrated Spotify client. If you are familiar with other Spotify terminal applications, spotify-player can be viewed as a combination of spotify-tui (remote player) and ncspot (local player).
• On startup, the application will connect to a running Spotify client. If there is no such client, user will need to use Spotify connect to connect to an available client.

Examples

Demo

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

Playlist

Artist

Album

Search

Installation

Requirements

A Spotify Premium account is required.

To build and run the application, besides Rust and cargo as the build requirements, Linux users will also need to install additional dependencies such as openssl and alsa-lib.

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

Spotify Connect

To enable full 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.

If 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 Spotify's official client:

Streaming

spotify-player supports streaming. It 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.

spotify-player uses 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 can be found in the Librespot documentation.

The streaming feature can be disabled by running (to use the application as a remote player only)

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

Commands

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

List of supported commands:

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

Actions

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

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.

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 file, 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

spotify-player uses RUST_LOG environment variable to define the application's logging level (default to be INFO). The application stores logs inside the $APP_CACHE_FOLDER/spotify-player.log file.

Roadmap

• 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