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
- Resource Footprint Comparison
- Installation
- Build
- Key Bindings
- Vim-Like Commands
- Configuration
- 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
(orportaudio-dev
, if you want to use the PortAudio backend)libncurses-dev
andlibssl-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 sharable URL of the currently selected item to the system clipboard. |
Shift+X | Copy a sharable 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 occurence. |
N | Next search occurence. |
Vim-Like Commands
You can open a Vim-style command prompt using :, and close it at any time with Escape.
The following commands are supported:
Command | Action |
---|---|
quit |
Quit ncspot . |
logout |
Remove any cached credentials from disk and quit ncspot . |
toggle |
Toggle playback. |
stop |
Stop playback. |
previous |
Play previous track. |
next |
Play next track. |
clear |
Clear playlist. |
share <item> |
Copies a sharable 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> . |
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 <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
The screens can be opened with focus <queue|search|library>
.
The search
command can be supplied with a search term that will be
entered after opening the search view.
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 |
Revese 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 (if enabled) | Number | 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 |
false |
shuffle |
Set default shuffle state | true , false |
false |
repeat |
Set default repeat mode | off , track , playlist |
off |
[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
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.
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 Commands above).