Home

Awesome

sptui

Go Report Card

<img src="assets/demo.gif" width="500">

Overview

sptui is a Spotify TUI player, written in Go and leveraging the charmbracelet/bubbletea library.

Installation

Visit the GitHub Releases page for sptui and download the appropriate binary for your operating system.

If you are on NetBSD, a package is available from the official repositories. To install, simply run:

pkgin install sptui

Usage

Connecting to Spotify’s API

To use sptui, you need to connect it to Spotify's API. Follow these steps:

  1. Go to the Spotify Dashboard.
  2. Create a new app to obtain your Client ID and Client Secret.
  3. In Edit Settings, add http://localhost:21112/callback to the Redirect URIs. Don’t forget to save your changes.
  4. Set your Client ID as an environment variable SPOTIFY_ID.
  5. Run sptui. You will see an official Spotify URL for authentication.
# Replace your_client_id with the actual Client ID you obtained from Spotify.
SPOTIFY_ID=your_client_id sptui
  1. Open the provided URL in a web browser and log in to your Spotify account to grant the necessary permissions. After granting permission, you might be redirected to a blank page. This is normal and indicates that the authentication process is complete.

Once authenticated, you are ready to use sptui!

API Token Storage

Once authenticated, your Spotify API token will be stored at ${HOME}/.config/sptui/spotify_token.json. Ensure this file is kept secure as it contains sensitive information.

Key Bindings

Here are the key bindings for sptui:

KeyAction
h j k lNavigate (left, down, up, right)
escReturn to the previous screen
qQuit sptui
:playPlay current selection
:pausePause playback
:nextNext track
:prevPrevious track
:deviceSelect a device