DOCSEARCHbyAlgolia
Submit Docs

ncspot Documentation

repository·main·Indexed 27 days ago

https://github.com/hrkfdn/ncspot

ncspot is a lightweight, ncurses-based Spotify client written in Rust using librespot. It provides a terminal-based music experience with Vim-like keybindings, IPC socket support, and a small resource footprint. It supports tracks, albums, playlists, genres, and searching across multiple platforms including Linux, macOS, Windows, and *BSD. A Spotify Premium account is required for use.

Tokens
5.6K
Snippets
15
Records
51
Agent score
92%

What's inside ncspot

  1. Overview of ncspot features

    main

    ncspot is an ncurses Spotify client written in Rust using librespot. It is designed to be a lightweight, resource-friendly alternative to the official Spotify client, inspired by MPD clients like ncmpc.

    Key Features:

    • Support for tracks, albums, playlists, genres, and searching.
    • Small resource footprint.
    • Multi-platform support (including *BSDs).
    • Vim-like keybindings enabled by default.
    • IPC socket support for remote control.

    Requirement: ncspot requires a Spotify Premium account to function.

  2. Compare ncspot resource footprint

    main
    When running on Linux, ncspot has a significantly lower memory footprint compared to the official Spotify client. During playback, ncspot uses approximately 46.2 MiB of total memory, whereas Spotify uses approximately 1000.0 MiB. Measurements were taken using ps_mem.

  3. Configure a proxy for ncspot

    main

    ncspot respects the system proxy settings via the http_proxy environment variable. You can launch ncspot with a specific proxy by setting this variable in your shell.

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

  4. Navigate ncspot using key bindings

    main

    Use the following keyboard shortcuts to navigate the ncspot interface:

    KeyCommand
    <kbd>?</kbd>Show help screen
    <kbd>F1</kbd>Queue
    <kbd>F2</kbd>Search
    <kbd>F3</kbd>Library
    <kbd>F8</kbd>Album Art (requires cover feature)
    <kbd>/</kbd>Open Vim-like search bar
    <kbd>:</kbd>Open Vim-like command prompt
    <kbd>Escape</kbd>Close search bar, command prompt, or Search screen
    <kbd>Q</kbd>Quit ncspot
    <kbd>g</kbd>Go to the top of the current view
    <kbd>G</kbd>Go to the bottom of the current view

  5. Control playback in ncspot

    main

    Use these key bindings to manage audio playback:

    KeyCommand
    <kbd>Return</kbd>Play track or playlist
    <kbd>Space</kbd>Queue track or playlist
    <kbd>.</kbd>Play selected item after currently playing track
    <kbd>P</kbd>Move to currently playing track in queue
    <kbd>S</kbd>Save currently playing item to library
    <kbd>D</kbd>Remove currently playing item from library
    <kbd>Shift</kbd>+<kbd>P</kbd>Toggle playback (Play/Pause)
    <kbd>Shift</kbd>+<kbd>S</kbd>Stop playback
    <kbd>Shift</kbd>+<kbd>U</kbd>Update library cache
    <kbd><</kbd>Play previous track
    <kbd>></kbd>Play next track
    <kbd>F</kbd>Seek forward 1s
    <kbd>Shift</kbd>+<kbd>F</kbd>Seek forward 10s
    <kbd>B</kbd>Seek backward 1s
    <kbd>Shift</kbd>+<kbd>B</kbd>Seek backward 10s
    <kbd>-</kbd>Decrease volume 1%
    <kbd>+</kbd>Increase volume 1%
    <kbd>[</kbd>Decrease volume 5%
    <kbd>]</kbd>Increase volume 5%
    <kbd>R</kbd>Toggle Repeat mode
    <kbd>Z</kbd>Toggle Shuffle state

  6. Control ncspot via Remote Control (IPC) socket

    main

    On UNIX platforms (Linux, macOS, *BSD), ncspot creates a domain socket in the platform's runtime directory. You can connect to this socket using tools like netcat to send commands or receive JSON notifications about the currently playing track.

    To find the location of your socket, run: ncspot info

    Common commands to send via the socket include:

    • play
    • playpause

    Each time the playback status changes, ncspot publishes a JSON structure containing the current mode (e.g., Playing, Paused) and playable metadata (e.g., title, artists, album, uri).

    % nc -U $NCSPOT_CACHE_DIRECTORY/ncspot.sock
play

  7. Use context menus and item views

    main

    Access detailed information and context-specific actions using these keys:

    KeyCommand
    <kbd>O</kbd>Open detail view (if not a track) or context menu (if a track) for selected item
    <kbd>Shift</kbd>+<kbd>O</kbd>Open context menu for currently playing track
    <kbd>A</kbd>Open album view for selected item
    <kbd>Shift</kbd>+<kbd>A</kbd>Open artist view for selected item
    <kbd>M</kbd>Open recommendations view for selected item
    <kbd>Shift</kbd>+<kbd>M</kbd>Open recommendations view for currently playing track
    <kbd>Ctrl</kbd>+<kbd>V</kbd>Open context menu for Spotify link in clipboard (requires share_clipboard feature)
    <kbd>Backspace</kbd>Close current view

  8. Install ncspot

    main

    ncspot is available across multiple platforms via various package managers:

    • macOS: Homebrew
    • Windows: Scoop, WinGet
    • Linux: Native packages, Flathub, and Snapcraft
    • BSD: Supported via detailed platform-specific instructions.

  9. Authenticate with Spotify via OAuth2

    main

    ncspot uses OAuth2 for authentication. On the first launch, a link will be generated for you to open in a browser. After logging in, credentials are saved to librespot/credentials.json in your cache directory (run ncspot info to find the path).

    To remove cached credentials, use the logout command.

  11. Install Prerequisites for Development

    main

    To develop or build ncspot from source, you need a working Rust installation and Python 3 (required for the rust-xcb dependency).

    On Linux, you must also install pkgconf (or pkg-config) and the development headers for runtime dependencies. Use the commands corresponding to your distribution:

  12. Install ncspot from crates.io via Cargo

    main

    If no recent version is available for your OS via other package managers, you can install ncspot from crates.io using cargo.

    Important: You must use the --locked flag to ensure the compilation process succeeds by using the exact dependency versions specified in the crate.

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