User Documentation

Installation Instructions

On macOS

ncspot is available via Homebrew:

brew install ncspot

On Windows

ncspot is available via Scoop:

scoop install ncspot

or via winget:

winget install hrkfdn.ncspot

On Linux

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

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 or a compatible implementation (e.g. ueberzugpp) (if built with the cover feature)

On BSD's

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

From crates.io

ncspot can be installed with cargo. The cargo documentation recommends against installing software with it. If another option is available from the ones above, it should be preferred. If no recent version is available for your OS, you can use the following command to install ncspot from crates.io.

# The --locked option is important and the compilation process might fail without it
cargo install --locked ncspot

Key Bindings

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.

Navigation

Playback

Context Menus

When pressing <kbd>O</kbd>:

• 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"

Sharing

(if built with the share_clipboard feature)

Queue

Library

Vim-Like Search Bar

Vim-Like Commands

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

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

Remote control (IPC)

Apart from MPRIS, ncspot will also create a domain socket on UNIX platforms (Linux, macOS, *BSD). The socket will be created in the platform's runtime directory. Run ncspot info to show the location of this directory on your platform. Applications or scripts can connect to this socket to send commands or be notified of the currently playing track, i.e. with netcat:

% nc -U $NCSPOT_CACHE_DIRECTORY/ncspot.sock
play
{"mode":{"Playing":{"secs_since_epoch":1672249086,"nanos_since_epoch":547517730}},"playable":{"type":"Track","id":"2wcrQZ7ZJolYEfIaPP9yL4","uri":"spotify:track:2wcrQZ7ZJolYEfIaPP9yL4","title":"Hit Me Where It Hurts","track_number":4,"disc_number":1,"duration":184132,"artists":["Caroline Polachek"],"artist_ids":["4Ge8xMJNwt6EEXOzVXju9a"],"album":"Pang","album_id":"4ClyeVlAKJJViIyfVW0yQD","album_artists":["Caroline Polachek"],"cover_url":"https://i.scdn.co/image/ab67616d0000b2737d983e7bf67c2806218c2759","url":"https://open.spotify.com/track/2wcrQZ7ZJolYEfIaPP9yL4","added_at":"2022-12-19T22:41:05Z","list_index":0}}
playpause
{"mode":{"Paused":{"secs":25,"nanos":575000000}},"playable":{"type":"Track","id":"2wcrQZ7ZJolYEfIaPP9yL4","uri":"spotify:track:2wcrQZ7ZJolYEfIaPP9yL4","title":"Hit Me Where It Hurts","track_number":4,"disc_number":1,"duration":184132,"artists":["Caroline Polachek"],"artist_ids":["4Ge8xMJNwt6EEXOzVXju9a"],"album":"Pang","album_id":"4ClyeVlAKJJViIyfVW0yQD","album_artists":["Caroline Polachek"],"cover_url":"https://i.scdn.co/image/ab67616d0000b2737d983e7bf67c2806218c2759","url":"https://open.spotify.com/track/2wcrQZ7ZJolYEfIaPP9yL4","added_at":"2022-12-19T22:41:05Z","list_index":0}}

Each time the playback status changes (i.e. after sending the play/playpause command or simply by playing the queue), the current status will be published as a JSON structure.

Possible use cases for this could be:

• Controlling a detached ncspot session (in tmux for example)
• Displaying the currently playing track in your favorite application/status bar (see below)
• Setting up routines, i.e. to play specific songs/playlists when ncspot starts

Extracting info on currently playing song

Using netcat and the domain socket, you can query the currently playing track and other relevant information. Note that not all netcat versions are suitable, as they typically tend to keep the connection to the socket open. OpenBSD's netcat offers a work-around: by using the -W flag, it will close after a specific number of packets have been received.

% nc -W 1 -U $NCSPOT_CACHE_DIRECTORY/ncspot.sock
{"mode":{"Playing":{"secs_since_epoch":1675188934,"nanos_since_epoch":50913345}},"playable":{"type":"Track","id":"5Cp6a1h2VnuOtsh1Nqxfv6","uri":"spotify:track:5Cp6a1h2VnuOtsh1Nqxfv6","title":"New Track","track_number":1,"disc_number":1,"duration":498358,"artists":["Francis Bebey"],"artist_ids":["0mdmrbu5UZ32uRcRp2z6mr"],"album":"African Electronic Music (1975-1982)","album_id":"7w99Aae1tYSTSb1OiDnxYY","album_artists":["Francis Bebey"],"cover_url":"https://i.scdn.co/image/ab67616d0000b2736ab57cedf27177fae1eaed87","url":"https://open.spotify.com/track/5Cp6a1h2VnuOtsh1Nqxfv6","added_at":"2020-12-22T09:57:17Z","list_index":0}}

This results in a single output in JSON format, which can e.g. be parsed using jq. For example, you can get the currently playing artist and title in your terminal as follows:

% nc -W 1 -U $NCSPOT_CACHE_DIRECTORY/ncspot.sock | jq '.playable.title'
"PUMPIN' JUMPIN'"

% nc -W 1 -U $NCSPOT_CACHE_DIRECTORY/ncspot.sock | jq '.playable.artists[0]'
"Hideki Naganuma"

Configuration

Configuration is saved to the config.toml file in the platform's standard configuration directory. Run ncspot info to show the location of this directory on your platform. 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.

Custom Keybindings

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"

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"

Proxy

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

# In sh-like shells
http_proxy="http://foo.bar:4444" ncspot

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 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, %artist, %title, %album, %saved, %duration. %artists will show all contributing artists, while %artist only shows the first listed artist.

Default configuration:

statusbar_format = "%artists - %title"

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

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"

Notification Formatting

ncspot also supports customizing the way notifications are displayed (which appear when compiled with the notify feature and notify = true). The title and body of the notification can be set, with title and body, or the default will be used. The formatting options are the same as those for track formatting (%artists, %title, etc)

Default configuration:

[notification_format]
title = "%title"
body = "%artists"

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 <kbd>F8</kbd> by default) using Überzug. The original project has been abandoned, therefore using a compatible implementation such as Überzug++ is recommended. 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

Authentication

ncspot uses OAuth2 for authentication. When launched for the first time, a link will be generated that can be opened in any browser. After logging in on the displayed page, you can start to use ncspot. The OAuth2 flow is the only supported one, as username/password authentication has been removed by Spotify.

The credentials are stored in librespot/credentials.json in the user's cache directory. Run ncspot info to show the location of this directory.

The logout command can be used to remove cached credentials. See Vim-Like Commands.