✍️ I write about building tools like this at dubeykartikay.com.
A terminal Spotify client.
Requirements
- A Spotify Premium account.
- A working system keyring.
- The patched
lazyspotify-librespotdaemon (only if you are installing from source or running an unpackaged build) - On Linux, one of
wl-clipboard,xclip, orxselif you want clipboard support on the auth screen.
Install
Homebrew
brew tap dubeyKartikay/lazyspotify brew install lazyspotify
Arch Linux
GitHub Releases
Download the latest package from GitHub Releases.
- macOS: signed
.zip - Ubuntu/Debian:
.deb - Fedora/RHEL:
.rpm - Arch:
.tar.gz
Example package installs:
sudo dpkg -i lazyspotify-*.deb sudo dnf install ./lazyspotify-*.rpm
Build From Source
Build the app:
git clone https://github.com/dubeyKartikay/lazyspotify.git
cd lazyspotify
make buildThen build the patched daemon from dubeyKartikay/go-librespot and point librespot.daemon.cmd at that binary in your config.
If you build lazyspotify yourself and do not compile in a packaged daemon path, librespot.daemon.cmd is required.
Demos
Play A Track From Playlist > Track
Player Controls
Library Navigation
Search
Set Up Your Spotify Client ID
lazyspotify requires your own Spotify app client ID.
- Open the Spotify Developer Dashboard.
- Create a new app with:
- App name:
lazyspotify - App description:
terminal based spotify client - Website:
https://github.com/dubeyKartikay/lazyspotify - Redirect URIs:
http://127.0.0.1:8287/callback - APIs used:
Web API,Web Playback SDK
- App name:
- Copy the app's Client ID.
- Put the Client ID in
config.ymlor export it as an environment variable. See Configuration.
Minimal config:
auth: client_id: your_spotify_app_client_id
Environment override:
export AUTH_CLIENT_ID=your_spotify_app_client_idIf you change auth.host, auth.port, or auth.redirect-endpoint, update the Spotify app Redirect URI to match exactly.
Configuration
Config file locations:
- macOS:
~/Library/Application Support/lazyspotify/config.yml - Linux:
~/.config/lazyspotify/config.yml
If the file is missing, lazyspotify creates config.yml with:
auth: client_id: your_spotify_app_client_id
Then replace your_spotify_app_client_id with your Spotify app Client ID.
Minimal config for package installs:
auth: client_id: your_spotify_app_client_id
Minimal config for source or manual installs:
auth: client_id: your_spotify_app_client_id librespot: daemon: cmd: - /absolute/path/to/lazyspotify-librespot
The generated daemon config is written automatically under the librespot/ subdirectory inside the app config directory. You usually do not need to edit it manually.
Auth Settings
| Key | Required | Default | Notes |
|---|---|---|---|
log_level |
No | ERROR |
App log level for lazyspotify. |
auth.client_id |
Yes | none | Your Spotify app client ID. |
auth.host |
No | 127.0.0.1 |
Host used for the local OAuth callback server. |
auth.port |
No | 8287 |
Port used for the local OAuth callback server. |
auth.redirect-endpoint |
No | /callback |
Callback path for Spotify OAuth. |
auth.timeout |
No | 30 |
Auth server shutdown timeout in seconds. |
auth.keyring.service |
No | spotify |
Keyring service name for stored tokens. |
auth.keyring.key |
No | token-v2 |
Keyring key for stored tokens. |
Librespot Settings
| Key | Required | Default | Notes |
|---|---|---|---|
librespot.host |
No | 127.0.0.1 |
Host for the local playback API server. |
librespot.port |
No | 4040 |
Port for the local playback API server. |
librespot.timeout |
No | 180 |
Playback API timeout in seconds. |
librespot.retry-delay |
No | 100 |
Retry delay in milliseconds. |
librespot.max-retries |
No | 3 |
Retry count for daemon calls. |
librespot.seek-step-ms |
No | 5000 |
Seek step size in milliseconds. |
librespot.volume-step |
No | 20 |
Volume step percentage (0-100) used for volume controls. |
librespot.daemon.cmd |
Sometimes | none | Required for source/manual installs unless a packaged daemon path was compiled into the binary. |
librespot.daemon.log_level |
No | ERROR |
Log level written into the generated librespot daemon config. |
librespot.daemon.zeroconf_enabled |
No | false |
Enables zeroconf in the daemon config. |
Environment variables can override config values by replacing . and - with _. Examples: LOG_LEVEL, AUTH_CLIENT_ID, LIBRESPOT_DAEMON_LOG_LEVEL.
Run
Start the app with:
If you built from source:
Print build metadata: