ncspot

ncspot is a ncurses Spotify client written in Rust using librespot. It is heavily inspired by ncurses MPD clients, such as ncmpc. My motivation was to provide a simple and resource friendly alternative to the official client as well as to support platforms that currently don't have a Spotify client, such as the *BSDs.

Table of Contents

• ncspot
  • Table of Contents
  • Resource Footprint Comparison
  • Installation
    • On macOS
    • On Windows
    • On Linux
      • Building a Debian Package
  • Build
    • Audio Backends
  • Key Bindings
    • Navigation
    • Playback
    • Context Menus
    • Sharing
    • Queue
    • Library
    • Vim-Like Search Bar
  • Vim-Like Commands
  • Configuration
    • Custom Keybindings
    • Proxy
    • Theming
    • Track Formatting
  • Cover Drawing
  • Authentication

Resource Footprint Comparison

Measured using ps_mem on Linux during playback:

Client	Private Memory	Shared Memory	Total
ncspot	22.1 MiB	24.1 MiB	46.2 MiB
Spotify	407.3 MiB	592.7 MiB	1000.0 MiB

Installation

On macOS

ncspot is available via Homebrew:

brew install ncspot

On Windows

ncspot is available via Scoop:

scoop install ncspot

On Linux

Requirements:

• Rust
• Python 3 (needed for building rust-xcb dependency)
• libpulse-dev (or portaudio-dev, if you want to use the PortAudio backend)
• libncurses-dev and libssl-dev
• libdbus-1-dev
• libxcb + development headers (for clipboard access)
• pkg-config
• A Spotify premium account

On Debian based systems you need following packages for development headers:

sudo apt install libncursesw5-dev libdbus-1-dev libpulse-dev libssl-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev

For Fedora, these dependencies are required:

dnf install pulseaudio-libs-devel libxcb-devel openssl-devel ncurses-devel dbus-devel

Building a Debian Package

You can use cargo-deb create in order to build a Debian package from source. Install it with:

cargo install cargo-deb

Then you can build a Debian package with:

cargo deb

You can find it under target/debian.

Build

Install the latest ncspot release using:

cargo install ncspot

Or build it yourself using:

cargo build --release

# NB: add these flags on Windows
cargo build --release --no-default-features --features rodio_backend,cursive/pancurses-backend

• Both approaches require a working Rust installation.

• For debugging, you can pass a debug log filename and log stderr to a file, e.g. :

  RUST_BACKTRACE=full cargo run -- -d debug.log 2> stderr.log

Audio Backends

By default ncspot is built using the PulseAudio backend. To make it use the PortAudio backend (e.g. for *BSD or macOS) or Rodio backend (e.g. for Windows), you need to recompile ncspot with the respective features:

# PortAudio (BSD/macOS)
cargo run --no-default-features --features portaudio_backend,cursive/pancurses-backend

# Rodio (Windows)
cargo run --no-default-features --features rodio_backend,cursive/pancurses-backend

Key Bindings

The keybindings listed below are configured by default. Additionally, if you run ncspot with MPRIS support, you may be able to use media keys to control playback depending on your desktop environment settings. Have a look at the configuration section if you want to set custom bindings.

Navigation

Key	Command
?	Show help screen.
F1	Queue (See specific commands).
F2	Search.
F3	Library (See specific commands).
F8	Album Art (if compiled with the cover feature).
/	Open a Vim-like search bar (See specific commands).
:	Open a Vim-like command prompt (See specific commands).
Escape	Close Vim-like search bar or command prompt.
Q	Quit ncspot.

Playback

Key	Command
Return	Play track or playlist.
Space	Queue track or playlist.
.	Play the selected item after the currently playing track.
P	Move to the currently playing track in the queue.
S	Save the currently playing track to your library.
D	Remove the currently playing track from your library.
Shift+P	Toggle playback (i.e. Play/Pause).
Shift+S	Stop playback.
Shift+U	Update the library cache (tracks, artists, albums, playlists).
<	Play the previous track.
>	Play the next track.
F	Seek forward.
Shift+F	Seek forward with a 10-second step.
B	Seek backwards.
Shift+B	Seek backwards with a 10-second step.
-	Decrease volume by 1.
+	Increase volume by 1.
[	Decrease volume by 5.
]	Increase volume by 5.
R	Toggle Repeat mode.
Z	Toggle Shuffle state.

Context Menus

Key	Command
O	Open a detail view or context for the selected item.
Shift+O	Open a context menu for the currently playing track.
A	Open the album view for the selected item.
Shift+A	Open the artist view for the selected item.
M	Open the recommendations view for the selected item.
Shift+M	Open the recommendations view for the currently playing track.
Ctrl+V	Open the context menu for a Spotify link in your clipboard.
Backspace	Close the current view.

When pressing O:

• If the selected item is not a track, it opens a detail view.
• If the selected item is a track, it opens a context menu with:
  • "Show Artist"
  • "Show Album"
  • "Share"
  • "Add to playlist"
  • "Similar tracks"

Sharing

Key	Command
X	Copy a shareable URL of the currently selected item to the system clipboard.
Shift+X	Copy a shareable URL of the currently playing track to the system clipboard.

Queue

Key	Command
C	Clear the entire queue.
D	Delete the currently selected track.
Ctrl+S	Delete the currently selected track.

Library

Key	Command
D	Delete the currently selected playlist.

Vim-Like Search Bar

Key	Command
n	Previous search occurrence.
N	Next search occurrence.

Vim-Like Commands

You can open a Vim-style command prompt using :, and close it at any time with Escape.

The following is an abridged list of commonly-used commands. For the full list, see source code.

Command	Action
help	Show current key bindings.
quit Aliases: q, x	Quit ncspot.
logout	Remove any cached credentials from disk and quit ncspot.
playpause Aliases: pause, toggleplay, toggleplayback	Toggle playback.
stop	Stop playback.
seek [+|-]<time>	Seek to the specified position, or seek relative to current position by prepending +/-. Supports mixing time units (e.g. seek 1m42s). Default unit is millisecond.
repeat [repeat_mode] Aliases: loop	Set repeat mode. Omit repeat_mode argument to step through the available modes.
shuffle [on|off]	Enable or disable shuffle. Omit argument to toggle.
previous	Play previous track.
next	Play next track.
focus <queue|search|library>	Switch to a screen.
search <keyword>	Search a song.
clear	Clear playlist.
share <item>	Copies a shareable URL of the item to the system clipboard.
newplaylist <name>	Create new playlist with name name.
sort <sort_key> [sort_direction]	Sort a playlist by sort_key in direction sort_direction. Default direction is ascending.
exec <cmd>	Executes a command in the system shell. Be aware that command output is printed to the terminal, so redirection to /dev/null e.g. by appending 2> /dev/null may be necessary.

• Supported repeat_mode are:
  • list | playlist | queue
  • track | once | single
  • none | off
• Supported item are:
  • selected: Selected item.
  • current: Current song.
• Supported sort_key are:
  • title
  • album
  • artist
  • duration
  • added
• Supported sort_direction are:
  • a | asc | ascending
  • d | desc | descending

Configuration

Configuration is saved to ~/.config/ncspot/config.toml (or %AppData%\ncspot\config.toml on Windows). To reload the configuration during runtime use the command prompt by typing :reload.

Possible configuration values are:

Name	Description	Possible values	Default
command_key	Key to open command line	Single character	:
initial_screen	Screen to show after startup	"library", "search", "queue", "cover"1	"library"
use_nerdfont	Turn nerdfont glyphs on/off	true, false	false
flip_status_indicators	Reverse play/pause icon meaning2	true, false	false
backend	Audio backend to use	String 3
backend_device	Audio device to configure the backend	String
audio_cache	Enable caching of audio files	true, false	true
audio_cache_size	Maximum size of audio cache in MiB	Number
volnorm	Enable volume normalization	true, false	false
volnorm_pregain	Normalization pregain to apply in dB (if enabled)	Number	0.0
default_keybindings	Enable default keybindings	true, false	false
notify	Enable desktop notifications	true, false	false
bitrate	Audio bitrate to use for streaming	96, 160, 320	320
album_column	Show album column for tracks	true, false	true
gapless	Enable gapless playback	true, false	true
shuffle	Set default shuffle state	true, false	false
repeat	Set default repeat mode	off, track, playlist	off
playback_state	Set default playback state	"Stopped", "Paused", "Playing", "Default"	"Paused"
library_tabs	Tabs to show in library screen	Array of tracks, albums, artists, playlists, podcasts	All tabs
[track_format]	Set active fields shown in Library/Queue views	See track formatting
[theme]	Custom theme	See custom theme
[keybindings]	Custom keybindings	See custom keybindings

Custom Keybindings

Keybindings can be configured in [keybindings] section in config.toml, e.g. as such:

[keybindings]
"Shift+i" = "seek +10000"

Proxy

ncspot will respect system proxy settings defined via the http_proxy environment variable.

Theming

Theme generator by @vaarad.

The color palette can be modified in the configuration. For instance, to have ncspot match Spotify's official client, you can add the following entries to the configuration file:

[theme]
background = "black"
primary = "light white"
secondary = "light black"
title = "green"
playing = "green"
playing_selected = "light green"
playing_bg = "black"
highlight = "light white"
highlight_bg = "#484848"
error = "light white"
error_bg = "red"
statusbar = "black"
statusbar_progress = "green"
statusbar_bg = "green"
cmdline = "light white"
cmdline_bg = "black"
search_match = "light red"

More examples can be found in this pull request.

Track Formatting

It's possible to customize which fields are shown in Queue/Library views. If you don't define center for example, the default value will be used. Available options for tracks: %artists, %title, %album, %saved, %duration Default configuration:

[track_format]
left = "%artists - %title"
center = "%album"
right = "%saved %duration"

Examples: (Click to show/hide)

Example 1 - Show only album name and track name after it:

[track_format]
left = "%album"
center = "%title"
right = ""

Example 2 - Show track title before artists, and don't show album at all:

[track_format]
left = "%title - %artists"
center = ""

Example 3 - Show everything as default, but hide saved status and track length:

[track_format]
right = ""

Example 4 - Show everything as default, except show title before artists:

[track_format]
left = "%title - %artists"

Example 5 - Show saved status and duration first, followed by track title and artists, with the album last:

[track_format]
left = "|%saved| %duration | %title - %artists"
center = ""
right = "%album"

Cover Drawing

When compiled with the cover feature, ncspot can draw the album art of the current track in a dedicated view (:focus cover or F8 by default) using Überzug. For more information on installation and terminal compatibility, consult that repository.

To allow scaling the album art up beyond its resolution (640x640 for Spotify covers), use the config key cover_max_scale. This is especially useful for HiDPI displays:

cover_max_scale = 2

Authentication

ncspot prompts for a Spotify username and password on first launch, uses this to generate an OAuth token, and stores it to disk.

The credentials are stored in ~/.cache/ncspot/librespot/credentials.json (unless the base path has been changed with the --basepath option).

The :logout command can be used to programmatically remove cached credentials (see Vim-Like Commands above).

Footnotes

1. If enabled. ↩

2. By default the statusbar will show a play icon when a track is playing and a pause icon when playback is stopped. If this setting is enabled, the behavior is reversed. ↩

3. Run ncspot -h for a list of devices. ↩