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.
Note that ncspot
offers features that are legally incompatible with free Spotify
accounts. See feature comparison
and Spotify user guidelines.
You must have an existing premium Spotify subscription to use ncspot
.
- ncspot
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 |
ncspot
is available via Homebrew:
brew install ncspot
ncspot
is available via Scoop:
scoop install ncspot
Your distribution may have packaged ncspot
in its package repository.
If so, simply install using your distribution's package manager - it
is by far the easiest way. If not, you can build from source instead.
See Build.
In case your package manager does not perform dependency resolution, here are the runtime dependencies:
dbus
,libncurses
,libssl
libpulse
(orportaudio
, if built using the PortAudio backend)libxcb
(if built with theclipboard
feature)ueberzug
(if built with thecover
feature)
- A working Rust installation
- Python 3 (needed for building
rust-xcb
dependency)
On Linux, you also need:
pkgconf
(orpkg-config
)- Development headers for the aforementioned runtime dependencies
- Debian and derivatives:
sudo apt install libdbus-1-dev libncursesw5-dev libpulse-dev libssl-dev libxcb1-dev libxcb-render0-dev libxcb-shape0-dev libxcb-xfixes0-dev
- Fedora:
sudo dnf install dbus-devel libxcb-devel ncurses-devel openssl-devel pulseaudio-libs-devel
- Arch and derivatives:
# headers are included in the base packages sudo pacman -S dbus libpulse libxcb ncurses openssl
- Debian and derivatives:
Compile and install the latest release with cargo-install
:
cargo install ncspot
Or clone and build locally:
git clone https://github.com/hrkfdn/ncspot
cargo build --release
You may need to manually set the audio backend on non-Linux OSes. See Audio Backends.
For debugging, you can pass a debug log filename and pipe stderr
to a file:
RUST_BACKTRACE=full cargo run -- -d debug.log 2> stderr.log
You can also use cargo-deb
to build a Debian package
cargo install cargo-deb
cargo deb
You can find the package under target/debian
.
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 compile ncspot
with the respective features:
# PortAudio (BSD/macOS)
cargo build --release --no-default-features --features portaudio_backend,pancurses-backend
# Rodio (Windows)
cargo build --release --no-default-features --features rodio_backend,pancurses-backend
Here are some auxiliary features you may wish to enable:
Feature | Default | Description |
---|---|---|
cover |
off | Add a screen to show the album art. See Cover Drawing. |
mpris |
on | Control ncspot via dbus. See Arch Wiki: MPRIS. |
notify |
on | Send a notification to show what's playing. |
share_clipboard |
on | Ability to copy the URL of a song/playlist/etc. to system clipboard. |
Consult Cargo.toml for the full list of supported features.
The keybindings listed below are configured by default. Additionally, if you
built 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.
Key | Command |
---|---|
? | Show help screen. |
F1 | Queue (See specific commands). |
F2 | Search. |
F3 | Library (See specific commands). |
F8 | Album Art (if built 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 . |
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 by 1 second. |
Shift+F | Seek forward by 10 seconds. |
B | Seek backward by 1 second. |
Shift+B | Seek backward by 10 seconds. |
- | Decrease volume by 1%. |
+ | Increase volume by 1%. |
[ | Decrease volume by 5%. |
] | Increase volume by 5%. |
R | Toggle Repeat mode. |
Z | Toggle Shuffle state. |
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 (if built with the share_clipboard feature). |
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" (if built with the
share_clipboard
feature) - "Add to playlist"
- "Similar tracks"
(if built with the share_clipboard
feature)
Key | Command |
---|---|
X | Copy the URL to the currently selected item to the system clipboard. |
Shift+X | Copy the URL to the currently playing track to the system clipboard. |
Key | Command |
---|---|
C | Clear the entire queue. |
D | Delete the currently selected track. |
Ctrl+S | Delete the currently selected track. |
Key | Command |
---|---|
D | Delete the currently selected playlist. |
Key | Command |
---|---|
n | Previous search occurrence. |
N | Next search occurrence. |
You can open a Vim-style command prompt using :, and close it at any time with Escape.
The following is an abridged list of the more useful commands. For the full list, see source code.
Note: <FOO> - mandatory arg; [BAR] - optional arg
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 + /- .* TIME is anything accepted by parse_duration * Default unit is ms for backward compatibility. |
repeat [REPEAT_MODE]Alias: loop |
Set repeat mode. Omit argument to step through the available modes. * Valid values for REPEAT_MODE: list (aliases: playlist , queue ), track (aliases: once , single ), none (alias: off ) |
shuffle [on |off ] |
Enable or disable shuffle. Omit argument to toggle. |
previous |
Play the previous track. |
next |
Play the next track. |
focus <SCREEN> |
Switch to a different view. * Valid values for SCREEN: queue , search , library , cover (if built with the cover feature) |
search <SEARCH> |
Search for a song/artist/album/etc. |
clear |
Clear the queue. |
share <ITEM> |
Copy a shareable URL of the item to the system clipboard. Requires the share_clipboard feature.* Valid values for ITEM: selected , current |
newplaylist <NAME> |
Create a new playlist. |
sort <SORT_KEY> [SORT_DIRECTION] |
Sort a playlist. * Valid values for SORT_KEY: title , album , artist , duration , added * Valid values for SORT_DIRECTION: ascending (default; aliases: a , asc ), descending (aliases: d , desc ) |
exec <CMD> |
Execute a command in the system shell. * Command output is printed to the terminal, so redirection ( 2> /dev/null ) may be necessary. |
noop |
Do nothing. Useful for disabling default keybindings. See custom keybindings. |
reload |
Reload the configuration from disk. See Configuration. |
Configuration is saved to ~/.config/ncspot/config.toml
(or
%AppData%\ncspot\config.toml
on Windows). To reload the configuration during
runtime use the reload
command.
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 meaning[2] | 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 [4] |
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 |
cover_max_scale [1] |
Set maximum scaling ratio for cover art | Number | 1.0 |
[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 |
- If built with the
cover
feature. - 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.
- Run
ncspot -h
for a list of devices. - If built with the
notify
feature.
Keybindings can be configured in [keybindings]
section in config.toml
.
Each key-value pair specifies one keybinding, where the key is a string in the format of:
[MODIFIER+]<CHAR|NAMED_KEY>
where:
MODIFIER: Shift|Alt|Ctrl
CHAR: Any printable character
NAMED_KEY: Enter|Space|Tab|Backspace|Esc|Left|Right|Up|Down
|Ins|Del|Home|End|PageUp|PageDown|PauseBreak|NumpadCenter
|F0|F1|F2|F3|F4|F5|F6|F7|F8|F9|F10|F11|F12
For implementation see commands::CommandManager::parse_key.
Its value is a string that can be parsed as a command. See Vim-Like Commands.
Examples: (Click to show/hide)
[keybindings]
# Bind "Shift+i" to "Seek forward 10 seconds"
"Shift+i" = "seek +10s"
To disable a default keybinding, set its command to noop
:
# Use "Shift+q" to quit instead of the default "q"
[keybindings]
"Shift+q" = "quit"
"q" = "noop"
ncspot
will respect system proxy settings defined via the http_proxy
environment variable.
# In sh-like shells
http_proxy="http://foo.bar:4444" ncspot
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.
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"
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 up the album art beyond its native resolution (640x640 for
Spotify covers), use the config key cover_max_scale
. This is especially useful
for HiDPI displays:
cover_max_scale = 2
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 remove cached credentials. See
Vim-Like Commands.