terminal-lyrics

Real-time, karaoke-style lyrics for your Spotify in the terminal.

♫ Blinding Lights — The Weeknd
────────────────────────────────
  I've been on my own for long enough
  Maybe you can show me how to love
► I've been running out of time
  Oh, I've been running

Requirements

• Node.js 18+
• A Spotify account
• A Spotify Developer App

Installation

npm install -g terminal-lyrics
# or run without installing:
npx terminal-lyrics

First-Run Setup

On first run, terminal-lyrics will launch a setup wizard:

Welcome to terminal-lyrics! Let's get you set up.

? Spotify CLIENT_ID: ___
? Spotify CLIENT_SECRET: ___
? Musixmatch API key (optional — Enter to skip): ___

After entering your credentials, your browser will open for Spotify authorization. Once authorized, the app starts immediately.

Getting Spotify Credentials

1. Go to developer.spotify.com/dashboard
2. Create a new app
3. Add http://127.0.0.1:8888/callback to the Redirect URIs
4. Copy your Client ID and Client Secret

Getting a Musixmatch API Key (Optional)

Musixmatch provides a fallback for songs not found on lrclib.net.

1. Sign up at developer.musixmatch.com
2. Create an app and copy your API key

If you skip this step, terminal-lyrics will only use lrclib.net (free, no key required).

Config Location

Your credentials are stored at ~/.config/terminal-lyrics/config.json.

To reset your setup, delete this file and run terminal-lyrics again.

Lyrics Sources

| Source | Priority | Key Required | |--------|----------|--------------| | lrclib.net | Primary | No | | Musixmatch | Fallback | Yes (optional) |

Troubleshooting

Browser doesn't open for OAuth? Copy the URL printed to the terminal and open it manually.

Port 8888 in use? Stop the process using port 8888 and try again.

Lyrics not found? The song may not be in lrclib.net's database. Add a Musixmatch key for better coverage.

License

MIT