lirik

Spotify lyrics in your terminal. Shows synced lyrics from LRCLIB with real-time progress tracking.

Directly inspired by great sptlrx.

Install

cargo binstall lirik
# or
cargo install lirik

Or download a binary from releases.

Setup

1. Create an app at Spotify Developer Dashboard
2. Set the redirect URI to http://127.0.0.1:8888/callback
3. Run lirik config to create ~/.config/lirik/config.toml:

client_id = ""
client_secret = ""
redirect_uri = "http://127.0.0.1:8888/callback"
poll_interval_secs = 5
lyrics_offset_ms = 0

Fill in your client_id and client_secret. Alternatively, export env vars (these override config):

export RSPOTIFY_CLIENT_ID=<your-client-id>
export RSPOTIFY_CLIENT_SECRET=<your-client-secret>
export RSPOTIFY_REDIRECT_URI=http://127.0.0.1:8888/callback

4. Run lirik auth login to authenticate with Spotify (opens browser)

Usage

lirik                   interactive TUI with synced lyrics (default)
lirik -j                full JSON output
lirik -p                print all lyrics
lirik -pc               print from current line to end
lirik -pr               print all lyrics in reverse
lirik -pcr              print from current line to end, reversed
lirik -w                stream lyrics line by line as they play
lirik -wj               stream as JSON (ndjson)

Options

Short flags combine: -pcr = --plain --current --reverse

Playback

TUI keybindings

Commands

Web UI

Start with --web to enable the web interface:

lirik --web          # default port 3000
lirik --web 8080     # custom port

Or set web_port in config to always enable it. The web UI shows synced lyrics with playback controls (play/pause, next, previous).

Architecture

lirik runs a background daemon that polls Spotify every few seconds and caches the current track + lyrics. All client commands connect to the daemon over a unix socket (/tmp/lirik.sock) for instant responses.

The daemon starts automatically on first use. No manual setup needed.

Daemon polls Spotify for playback state, fetches lyrics from LRCLIB on track change, and serves everything over the socket.

Client connects to the daemon, reads cached state, and estimates progress client-side from the baseline + elapsed wall time.

JSON output

lirik -j returns:

{
  "artist": "Artist Name",
  "track": "Track Name",
  "progress_ms": 123456,
  "progress": "2:03",
  "duration_ms": 234567,
  "duration": "3:54",
  "is_playing": true,
  "lyric": "current lyric line",
  "lyrics": {
    "synced": true,
    "lines": [
      {"time_ms": 12340, "text": "first line"},
      {"time_ms": 15670, "text": "second line"}
    ]
  }
}

Watch mode

lirik -w streams one line at a time:

Artist - Track
first lyric line
second lyric line
                        <- empty line on pause
Artist - Track
next lyric line

lirik -wj streams ndjson:

{"event":"track","artist":"Artist","track":"Track"}
{"time_ms":12340,"text":"first line"}
{"time_ms":15670,"text":"second line"}

Config

~/.config/lirik/config.toml:

Env vars (RSPOTIFY_CLIENT_ID, RSPOTIFY_CLIENT_SECRET, RSPOTIFY_REDIRECT_URI) override config values.

License

MIT