spotui

0.1.20 verified Sat May 09 auth: no python

A terminal user interface for Spotify, allowing browsing and control of playlists, search, and playback. Current version 0.1.20, released on GitHub. Development may be low activity; last release in 2021.

pip install spotui

Common errors

error ModuleNotFoundError: No module named 'spotui' ↓

cause The package is not installed or the environment is incorrect.

fix

Run pip install spotui to install the package.

error spotipy.SpotifyException: The access token expired ↓

cause Spotify API token expired and spotui may not handle refresh automatically.

fix

Re-run the application; it will prompt for re-authentication.

error TypeError: 'NoneType' object is not iterable ↓

cause This can occur if the Spotify API returns an unexpected empty response, e.g., no devices found.

fix

Ensure you have an active Spotify playback device (Spotify app or web player) and try again.

Warnings

gotcha spotui does not export a usable API; it only provides a main() function that starts the terminal interface. Importing the package does nothing by itself. ↓

fix Use `from spotui import main; main()` instead of expecting module-level functions.

breaking The package requires Spotify API credentials via environment variables. Without SPOTIPY_CLIENT_ID, SPOTIPY_CLIENT_SECRET, and SPOTIPY_REDIRECT_URI, the application will crash on startup. ↓

fix Set environment variables before importing spotui. Example in quickstart.

gotcha The TUI may not work on all terminals (requires a color-capable terminal) and has not been tested on Windows. ↓

fix Use a Unix-like terminal such as iTerm2, GNOME Terminal, or Windows Terminal with WSL.

Imports

main
wrong
```
import spotui
```
correct
```
from spotui import main
```
The package does not expose a public API; after import, you must call main() to start the TUI.

Quickstart

Authenticate with Spotify API (requires env vars) and launch the TUI.

import os
os.environ['SPOTIPY_CLIENT_ID'] = os.environ.get('SPOTIPY_CLIENT_ID', 'your_client_id')
os.environ['SPOTIPY_CLIENT_SECRET'] = os.environ.get('SPOTIPY_CLIENT_SECRET', 'your_client_secret')
os.environ['SPOTIPY_REDIRECT_URI'] = os.environ.get('SPOTIPY_REDIRECT_URI', 'http://localhost:8080')

from spotui import main
main()