spotty-cli 0.0.8

Synchronized lyrics in your terminal for the currently playing Spotify track

spotty

Synchronized lyrics in your terminal for the currently playing Spotify track.

• Line-by-line sync using LRC timestamps from lrclib.net
• Falls back to plain lyrics via lyrics.ovh if no synced lyrics found
• Smooth display — progress interpolated between API polls (no jumping)
• Auto-refreshes when track changes
• Shows lyrics source (lrclib or lyrics.ovh) as a dim footer
• Handles instrumental sections, multi-artist tracks, featured artists
• Live offset calibration: press [ / ] during playback to shift lyrics 100ms earlier/later; persisted per-track

Requirements

• Python 3.11+
• A Spotify Developer App

Installation

pip install spotty-cli

Or from source:

git clone https://github.com/Arideno/spotty
cd spotty
pip install -e .

Setup

1. Create a Spotify App

1. Go to Spotify Developer Dashboard
2. Click Create app
3. Set Redirect URI to http://127.0.0.1:8888/callback
4. Copy your Client ID

2. Configure credentials

spotty init

You will be prompted for:

Spotify Client ID: <paste your client ID>
Redirect URI [http://127.0.0.1:8888/callback]: <Enter to keep default>

Config is saved to ~/.config/spotty/config.json.

On first run after init, a browser window opens for Spotify authorization. Tokens are saved to ~/.config/spotty/tokens.json and refreshed automatically.

Usage

# Synchronized mode (default) — live updating display
spotty

# Plain lyrics — print and exit
spotty --plain

# Adjust timing if lyrics feel early or late
spotty --offset 300    # shift 300ms later
spotty --offset -200   # shift 200ms earlier

# Bypass cache for one run
spotty --no-cache

# During synchronized playback, adjust timing live
#   [   shift lyrics 100ms earlier
#   ]   shift lyrics 100ms later
# Offset is saved per-track and shown in the progress bar (+200ms or dim [ / ] hint)

# Version
spotty --version

# Help
spotty --help

Options

Option	Default	Description
--plain	off	Show plain (non-synced) lyrics and exit
--offset MS	0	Shift lyrics by MS milliseconds. Positive = later, negative = earlier
--no-cache	off	Bypass the lyrics cache for this run
--version	—	Show version and exit
--help	—	Show help and exit

Configuration

Credentials are stored in ~/.config/spotty/config.json after running spotty init.

Key	Required	Default	Description
client_id	Yes	—	Spotify app client ID
redirect_uri	No	http://127.0.0.1:8888/callback	OAuth callback URI — must match your Spotify app settings
cache_dir	No	~/.cache/spotty	Override lyrics cache directory
cache_enabled	No	true	Set to false to permanently disable the lyrics cache

To update any value, re-run spotty init.

File locations

File	Purpose
~/.config/spotty/config.json	Credentials (also accepts optional cache_dir)
~/.config/spotty/tokens.json	OAuth tokens (auto-managed)
~/.cache/spotty/lyrics.db	SQLite lyrics cache and per-track offset calibrations (auto-managed, 30-day TTL)

Delete tokens.json to force re-authentication.

How it works

1. Auth — OAuth2 PKCE flow, no client secret needed in the token exchange
2. Now playing — polls GET /me/player/currently-playing every 500ms
3. Lyrics — checks SQLite cache first (~/.cache/spotty/lyrics.db, 30-day TTL); on miss fetches from lrclib.net and lyrics.ovh in parallel, then stores the result. Per-track offset calibrations are loaded from the same cache on each track change and written back on each [/] press.
4. Display — interpolates playback position between polls using the local clock for smooth highlighting

Development

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run directly
python -m spotty.cli

Contributing

1. Fork the repo
2. Create a branch: git checkout -b my-feature
3. Make changes and add tests
4. Run pytest — all tests must pass
5. Open a pull request

License

MIT — see LICENSE