ncspot

A cross-platform ncurses Spotify client written in Rust, inspired by ncmpc and vim.

tui

v1.1.1

ncspot is a cross-platform terminal Spotify client written in Rust. It uses ncurses for rendering and draws heavy inspiration from keyboard-driven music players like ncmpc and text editors like Vim. If you spend most of your time in the terminal and would rather control Spotify from there than switch to the Electron app, ncspot is the tool for you.

Features

Vim-style keybindings — navigate libraries, playlists, and search results entirely from the keyboard
Low resource usage — a fraction of the CPU and memory footprint of the official Spotify desktop app
Full playback control — play, pause, skip, seek, shuffle, repeat, volume control
Library browsing — access your saved tracks, albums, artists, and playlists
Search — search Spotify's full catalogue directly from the terminal
Queue management — add tracks to a play queue and reorder them
Cover art — optionally display album art using terminal image protocols (Kitty, Überzug, etc.)
MPRIS support — integrates with media key bindings and desktop notifications on Linux via MPRIS D-Bus
Cross-platform — runs on Linux, macOS, and Windows

Requirements

A Spotify Premium account is required. ncspot uses the Spotify Connect API and playback happens through the official Spotify client or via librespot (the open-source Spotify client library embedded in ncspot).

Installation

cargo install ncspot

Or via your system package manager:

# Arch Linux
pacman -S ncspot

# macOS
brew install ncspot

# Nix
nix-env -iA nixpkgs.ncspot

# Void Linux
xbps-install ncspot

On Linux, you may need to install audio backend dependencies:

# PulseAudio backend (default)
apt install libpulse-dev

# ALSA backend
apt install libasound2-dev

Usage

# Launch ncspot
ncspot

On first launch, you will be prompted to log in with your Spotify credentials. Your session token is stored in the system keychain.

Keybindings

Key	Action
`q`	Quit
`Space`	Play / pause
`Return`	Play selected item
`n` / `p`	Next / previous track
`+` / `-`	Volume up / down
`s`	Toggle shuffle
`r`	Toggle repeat
`/`	Open search
`a`	Go to artist of current track
`A`	Go to album of current track
`Shift+a`	Add current track to queue
`d`	Open queue
`1`–`9`	Switch between views (queue, search, library…)
`o`	Open context menu for selected item
`F1`	Help
Arrow keys / `hjkl`	Navigate lists

All keybindings are configurable.

Configuration

ncspot reads from ~/.config/ncspot/config.toml:

# Audio backend: "pulseaudio", "alsa", "portaudio", "rodio"
backend = "pulseaudio"

# Default volume (0–100)
volnorm = false

# Gapless playback
gapless = true

# Use the system keychain for credentials
use_nerdfont = true

# Custom keybindings
[keybindings]
"," = "seek -5000"
"." = "seek +5000"

# Theme
[theme]
background   = "default"
primary      = "default"
secondary    = "light black"
title        = "light white"
playing      = "light green"
playing_bg   = "default"
highlight    = "light white"
highlight_bg = "dark blue"
error        = "light red"
error_bg     = "default"
statusbar    = "default"
statusbar_bg = "default"
cmdline      = "default"
cmdline_bg   = "default"
search_match = "light red"

MPRIS Integration

On Linux, ncspot exposes an MPRIS D-Bus interface, which means:

Media keys on your keyboard (play/pause, next, previous) control ncspot automatically
Desktop environments show the currently playing track in their media overlay
Tools like playerctl can control ncspot from scripts:

playerctl --player=ncspot play-pause
playerctl --player=ncspot next
playerctl --player=ncspot metadata title