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
  • Table of Contents
  • Resource Footprint Comparison
  • Installation
    • On macOS
    • On Windows
    • On Linux
  • Build
    • Prerequisites
    • Compiling
      • Building a Debian Package
    • Audio Backends
    • Other Features
  • 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

Measured using ps_mem on Linux during playback:

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 (or portaudio, if built using the PortAudio backend)
• libxcb (if built with the clipboard feature)
• ueberzug (if built with the cover feature)

• A working Rust installation
• Python 3 (needed for building rust-xcb dependency)

On Linux, you also need:

• pkgconf (or pkg-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

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:

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.

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:
  • "Artist(s)" (let's you show or (un)follow a track's artist(s))
  • "Show Album"
  • "Share" (if built with the share_clipboard feature)
  • "Add to playlist"
  • "Similar tracks"

(if built with the share_clipboard feature)

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

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:

1. If built with the cover feature.
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.
4. 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.

[keybindings]
# Bind "Shift+i" to "Seek forward 10 seconds"
"Shift+i" = "seek +10s"

# 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

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.

It's possible to customize how tracks are shown in Queue/Library views and the statusbar, whereas statusbar_format will hold the statusbar formatting and [track_format] the formatting for tracks in list 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:

statusbar_format = "%artists - %title"

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

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

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

[track_format]
right = ""

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

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