+
# ncspot
[](https://crates.io/crates/ncspot)
@@ -9,220 +13,339 @@
[](https://snapcraft.io/ncspot)
[](https://snapcraft.io/ncspot)
-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.
+`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.
[](/screenshots/screenshot.png?raw=true)
-## Resource footprint comparison
+## Table of Contents
+
+- [Resource Footprint Comparison](#resource-footprint-comparison)
+- [Installation](#installation)
+ - [On macOs](#on-macos)
+ - [On Windows](#on-windows)
+ - [On Linux](#on-linux)
+- [Build](#build)
+ - [Audio Backends](#audio-backends)
+- [Key Bindings](#build)
+ - [Navigation](#navigation)
+ - [Playback](#playback)
+ - [Context Menus](#context-menus)
+ - [Sharing](#sharing)
+ - [Queue](#queue)
+ - [Library](#library)
+ - [Vim-like Search Bat](#vim-like-search-bar)
+- [Vim-Like Commands](#vim-like-commands)
+- [Configuration](#configuration)
+ - [Custom Keybindings](#custom-keybindings)
+ - [Proxy](#proxy)
+ - [Theming](#theming)
+- [Cover Drawing](#cover-drawing)
+- [Authentication](#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 |
+| 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 |
-## Requirements
+## Installation
### On macOS
-ncspot is available via Homebrew: `brew install ncspot`.
+`ncspot` is available via [Homebrew](https://brew.sh/):
+
+```zsh
+brew install ncspot
+```
+
+### On Windows
+
+`ncspot` is available via [Scoop](https://scoop.sh/):
+
+```powershell
+scoop install ncspot
+```
### On Linux
-* Rust
-* Python 3 (needed for building `rust-xcb` dependency)
-* `libpulse-dev` (or `portaudio-dev`, if you want to use the PortAudio backend)
-* `libncurses-dev` and `libssl-dev`
-* `libdbus-1-dev`
-* `libxcb` + development headers (for clipboard access)
-* A Spotify premium account
-* pkg-config
+Requirements:
+
+- Rust
+- Python 3 (needed for building `rust-xcb` dependency)
+- `libpulse-dev` (or `portaudio-dev`, if you want to use the PortAudio backend)
+- `libncurses-dev` and `libssl-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:
-```
+
+```bash
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:
-```
+
+```bash
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 by:
+You can use `cargo-deb` create in order to build a Debian package from source.
+Install it with:
-```
+```bash
cargo install cargo-deb
```
Then you can build a Debian package with:
-```
+```bash
cargo deb
```
You can find it under `target/debian`.
+## Build
-### On Windows
+Install the latest `ncspot` release using:
-ncspot is available via Scoop: `scoop install ncspot`
+```bash
+cargo install ncspot
+```
-## Usage
+Or build it yourself using:
-* Install the latest ncspot release using `cargo install ncspot`
- * or build it yourself using `cargo build --release`
- * both approaches require a working [Rust installation](https://www.rust-lang.org/tools/install)
-* 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`
+```bash
+cargo build --release
-## Audio backends
+# NB: add these flags on Windows
+cargo build --release --no-default-features --features rodio_backend,cursive/pancurses-backend
+```
-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:
+- Both approaches require a working [Rust installation](https://www.rust-lang.org/tools/install).
+- For debugging, you can pass a debug log filename and log stderr to a file,
+ e.g. :
-* `cargo run --no-default-features --features
- portaudio_backend,cursive/pancurses-backend`
-* `cargo run --no-default-features --features
- rodio_backend,cursive/pancurses-backend`
+ ```bash
+ RUST_BACKTRACE=full cargo run -- -d debug.log 2> stderr.log
+ ```
-### Key Bindings
+### Audio Backends
-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
+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:
+
+```bash
+# 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](#configuration) if you want to set custom bindings.
-* `?` show help screen
-* Navigate through the screens using the F-keys:
- * `F1`: Queue
- * `c` clears the entire queue
- * `d` deletes the currently selected track
- * `Ctrl-s` opens a dialog to save the queue to a playlist
- * `F2`: Search
- * `F3`: Library
- * `d` deletes the currently selected playlist
- * `F8`: Album art (if compiled with the `cover` feature)
-* Tracks and playlists can be played using `Return` and queued using `Space`
-* `.` will play the selected item after the currently playing track
-* `p` will move to the currently playing track in the queue
-* `s` will save, `d` will remove the currently selected track to/from your
- library
-* `o` will open a detail view or context menu for the selected item
- * if the _selected item_ is **not** a track:
- * opens a detail view
- * if the _selected item_ **is** a track:
- * opens a context menu for the _selected item_ presenting 4 options:
- * "Show Artist"
- * "Show Album"
- * "Share"
- * "Add to playlist"
- * "Similar tracks"
-* `Shift-o` will open a context menu for the currently playing track
-* `a` will open the album view for the selected item
-* `Shift-a` will open the artist view for the selected item
-* `m` will open a view with recommendations based on the selected item
-* `Shift-m` will open a view with recommendations based on the currently playing track
-* `Ctrl-v` will open the context menu for a Spotify link in your clipboard
-* `Backspace` closes the current view
-* `Shift-p` toggles playback of a track (play/pause)
-* `Shift-s` stops a track
-* `Shift-u` updates the library cache (tracks, artists, albums, playlists)
-* `<` and `>` play the previous or next track
-* `f` and `b` to seek forward or backward
-* `Shift-f` and `Shift-b` to seek forward or backward in steps of 10s
-* `-` and `+` decrease or increase the volume by 1
-* `[` and `]` decrease of increase the volume by 5
-* `r` to toggle repeat mode
-* `z` to toggle shuffle playback
-* `q` quits ncspot
-* `x` copies a sharable URL of the currently selected item to the system clipboard
-* `Shift-x` copies a sharable URL of the currently playing track to the system clipboard
+### Navigation
-Use `/` to open a Vim-like search bar, you can use `n` and `N` to go for the next/previous
-search occurrence, respectivly.
+| Key | Command |
+| :---------------- | :---------------------------------------------------------------------------- |
+| ? | Show help screen. |
+| F1 | Queue (See [specific commands](#queue)). |
+| F2 | Search. |
+| F3 | Library (See [specific commands](#library)). |
+| F8 | Album Art (if compiled with the `cover` feature). |
+| / | Open a Vim-like search bar (See [specific commands](#vim-like-search-bar)). |
+| : | Open a Vim-like command prompt (See [specific commands](#vim-like-commands)). |
+| Escape | Close Vim-like search bar or command prompt. |
+| Q | Quit `ncspot`. |
-### Commands
+### Playback
-You can also open a Vim style commandprompt using `:`, the following commands
-are supported:
+| 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. |
-* `quit`: Quit ncspot
-* `logout`: Remove any cached credentials from disk and quit ncspot
-* `toggle`: Toggle playback
-* `stop`: Stop playback
-* `previous`/`next`: Play previous/next track
-* `clear`: Clear playlist
-* `share [current | selected]`: Copies a sharable URL of either the selected item or the currernt song to the system clipboard
-* `newplaylist `: Create new playlist with name ``
-* `sort `: Sort a playlist by `` in direction ``
+### Context Menus
- Supported `` are:
- * title
- * album
- * artist
- * duration
- * added
+| 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. |
- Supported `` are:
- * a | asc | ascending
- * d | desc | descending
+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 ` | Copies a sharable URL of the item to the system clipboard. |
+| `newplaylist ` | Create new playlist with name ``. |
+| `sort ` | Sort a playlist by `` in direction ``. |
+
+Supported `` are:
+
+- `selected`: Selected item.
+- `current`: Current song.
+
+Supported `` are:
+
+- `title`
+- `album`
+- `artist`
+- `duration`
+- `added`
+
+Supported `` are:
+
+- `a` | `asc` | `ascending`
+- `d` | `desc` | `descending`
The screens can be opened with `focus `.
+
The `search` command can be supplied with a search term that will be
entered after opening the search view.
-To close the commandprompt at any time, press `esc`.
-
## 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` statement in the command prompt
-`:reload`.
+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:
-* `command_key`: Key to open command line , set to `:` by
- default
-* `initial_screen`: Screen to show after startup
- <`"library"|"search"|"queue"|"cover" (if enabled)`> (default is `"library"`)
-* `use_nerdfont`: Turn nerdfont glyphs on/off
-* `flip_status_indicators`: 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.
-* `theme`: Set a custom color palette (see below)
-* `backend`: Audio backend to use, run `ncspot -h` for a list of devices
-* `backend_device`: Audio device string to configure the backend
-* `audio_cache`: Enable or disable caching of audio files, on by default
-
-* `audio_cache_size`: Maximum size of audio cache in MiB
-* `volnorm`: Enable or disable volume normalization, off by default
-* `volnorm_pregain`: Normalization pregain to apply (if enabled)
-* `default_keybindings`: If disabled, the default keybindings are discarded, off
- by default
-* `notify`: Enable or disable desktop notifications, off by default
-* `bitrate`: The audio bitrate to use for streaming, can be 96, 160, or 320 (default is 320)
-* `album_column`: Show album column for tracks, on by default
-* `gapless`: Allows gapless playback (default is false)
-* `shuffle`: Set default shuffle state
-* `repeat`: Set default repeat mode
+| 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"`[^2] | `"library"` |
+| `use_nerdfont` | Turn nerdfont glyphs on/off | `true`, `false` | `false` |
+| `flip_status_indicators` | Revese play/pause icon meaning[^1] | `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](<(#theming)>) | |
+| `[keybindings]` | Custom keybindings | See [custom keybindings](<(#custom-keybindings)>) | |
+[^1]:
+ 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.
-Keybindings can be configured in `[keybindings]` section in `config.toml`, e.g. as such:
+[^2]: If [enabled](#cover-drawing).
+[^3]: Run `ncspot -h` for a list of devices.
-```
+### Custom Keybindings
+
+Keybindings can be configured in `[keybindings]` section in `config.toml`,
+e.g. as such:
+
+```toml
[keybindings]
"Shift+i" = "seek +10000"
```
-See the help screen by pressing `?` for a list of possible commands.
+### Proxy
-ncspot will respect system proxy settings defined via the `http_proxy`
+`ncspot` will respect system proxy settings defined via the `http_proxy`
environment variable.
### Theming
@@ -230,10 +353,10 @@ environment variable.
[Theme generator](https://ncspot-theme-generator.vaa.red/) by [@vaarad](https://github.com/vaared).
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:
+`ncspot` match Spotify's official client, you can add the following entries to
+the configuration file:
-```
+```toml
[theme]
background = "black"
primary = "light white"
@@ -254,23 +377,30 @@ cmdline_bg = "black"
search_match = "light red"
```
-More examples can be found in pull request
-https://github.com/hrkfdn/ncspot/pull/40.
+More examples can be found in [this pull request](https://github.com/hrkfdn/ncspot/pull/40).
-### Cover Drawing
+## 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](https://github.com/seebye/ueberzug). For more information on installation and terminal compatibility, consult that repository.
+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](https://github.com/seebye/ueberzug). 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:
+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:
-```
+```toml
cover_max_scale = 2
```
-### Authentication
+## Authentication
-`ncspot` prompts for a Spotify username and password on first launch, uses this to generate an OAuth token, and stores it to disk.
+`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 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](#commands) above).
+The `:logout` command can be used to programmatically remove cached credentials
+(see [Commands](#commands) above).
diff --git a/logo.svg b/logo.svg
new file mode 100644
index 0000000..b2d8c57
--- /dev/null
+++ b/logo.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
+