Use Cliamp to stream your Spotify library through its audio pipeline. EQ, the visualizer, and other effects apply. You need a Spotify Premium account.
Windows: Every Windows source build needs CGO enabled and the MSYS2 MinGW64 toolchain because the Spotify provider is compiled in even when it is not configured. See Building from source in the README. Pre-built Windows binaries from Releases include Spotify support.
Quick start: Run
cliamp setup, select Spotify, and follow the prompts. Register a Spotify Developer app and enter itsclient_idto get a private Web API rate-limit quota, including for search. Cliamp authorizes playback separately with the built-in Spotify identity. You can instead use the built-in sharedclient_idwithout registering an app.
Register a Spotify Developer app. Set its client_id in ~/.config/cliamp/config.toml:
[spotify]
client_id = "your_client_id_here"
bitrate = 320To register an app:
- Go to developer.spotify.com/dashboard and sign in.
- Click Create app.
- Enter a name, such as "cliamp", and a description.
- Add
http://127.0.0.1:19872/loginas a Redirect URI. - Select Web API under "Which API/SDKs are you planning to use?".
- Click Save.
- Open the app Settings and copy the Client ID.
bitrate is optional. If omitted, cliamp uses 320. Supported values are 96, 160, and 320. Values less than or equal to zero use 320. cliamp rounds other positive values to the nearest supported bitrate.
Run cliamp, select Spotify, and press Enter to sign in. With your own client_id, the browser completes two authorization steps in one tab: one for Web API access and one for playback. The built-in client path needs one step. cliamp stores credentials in ~/.config/cliamp/spotify_credentials.json. Later launches refresh them without a message.
Spotify introduced the current Development Mode restrictions for new apps on February 11, 2026. It migrated existing Development Mode apps on March 9, 2026. Extended Quota Mode apps are not affected. See the Spotify February 2026 migration guide for the full timeline.
Search remains available in Development Mode, but /v1/search accepts at most 10 results per request. A larger request returns 400 "Invalid limit". This does not mean search is blocked. Cliamp uses offset to page results in groups of 10. Ctrl+F asks for 20 results of each kind — albums, tracks, and episodes — so a Development Mode app fetches them as two pages of 10.
Other Development Mode changes remove endpoints such as /v1/browse/new-releases. They restrict playlist items to playlists the user owns or collaborates on. /v1/search remains available and does not require Extended Quota Mode.
To use no registered app, omit the client_id line:
[spotify]
bitrate = 320cliamp uses a built-in client_id. librespot and spotify-player use the same client ID.
Shared rate limit: The built-in
client_idis shared by librespot, spotify-player, and cliamp users worldwide. Spotify applies its per-app quota globally. A busy pool can cause429 Too Many Requestsduring search or playlist loading. Cliamp retries with backoff. Persistent 429 errors indicate a busy pool. Your ownclient_idhas a separate quota.
The sign-in callback listens on 127.0.0.1:19872 of the machine that runs cliamp. When cliamp runs on a remote machine over SSH, the browser on your computer cannot reach this callback. To sign in, forward the port from your computer to the remote machine:
ssh -L 19872:127.0.0.1:19872 user@remote-host- Connect with the command above.
- In this SSH session, run
cliamp, select Spotify, and pressEnter. - Open the sign-in URL from the provider panel in the browser on your computer. The panel wraps a long URL over several rows. In a terminal that supports OSC 8 hyperlinks, click any row of the URL to open the full URL. Some terminals need a modifier key, such as
CtrlorCmd. In other terminals, join the rows when you copy them. cliamp also writes the URL to~/.config/cliamp/cliamp.logon the remote machine. - Approve the sign-in. Spotify sends the browser to
http://127.0.0.1:19872/login, and SSH forwards this request to cliamp on the remote machine.
cliamp stores the credentials on the remote machine. You need the forwarded port again only for a new sign-in.
After authentication, Spotify appears in the provider list. Press Esc/b to open the provider browser and select Spotify.
The provider panel lists your Spotify playlists and saved albums. Use the arrow keys to select one and press Enter to load it. Tracks stream through the cliamp audio pipeline. EQ, the visualizer, mono, and other effects work as they do for local files.
Cliamp opens each Spotify stream in the background and shows Buffering... until audio starts. The UI stays responsive while it waits. If the connection drops mid-track, cliamp plays silence, reconnects, and resumes at the same position. After 5 failed attempts, it moves to the next track.
When focused on the provider panel:
| Key | Action |
|---|---|
Up Down / j k |
Navigate playlists |
Enter |
Load the selected playlist. On the sign-in prompt, sign in. |
Ctrl+R |
Reload playlists and tracks from Spotify |
Tab |
Return to playback controls, starting at Source when visible (navigation) |
Esc / b |
Open provider browser |
After you load a playlist, Cliamp returns to the standard playlist view. Use the usual controls for seek, volume, EQ, shuffle, repeat, queue, search, and lyrics.
Large playlists fill in as they load. Cliamp shows the first tracks, appends the remaining pages in the background, and stays usable while the list arrives.
The provider lists both playlists and saved albums in the Spotify library. Playlists include those you created and saved, or followed. If a public playlist is missing, open Spotify and click Save first.
Spotify lets apps read the tracks of only the playlists that you own or collaborate on. A followed playlist can fail to open with 403. To play it, add its tracks to your own playlist in Spotify.
Saved albums appear under a Saved albums section, labelled Artist - Album and sorted alphabetically by artist. These are the albums in Your Library. To add one, open the album in Spotify and click Save. Selecting a saved album loads all of its tracks in disc and track order.
In the Ctrl+F results, select a track and press p. The picker lists only the playlists that you own or collaborate on. Select + New Playlist... to create a private playlist. If the add fails, the error shows on the picker.
Press f on a Spotify track to toggle its favorite ♥. cliamp saves the favorite
locally and also saves the track to Liked Songs. Press f again to remove
the favorite and remove the track from Liked Songs. The key works in the
playlist, the Local playlists, and Ctrl+F results.
cliamp calls PUT and DELETE /v1/me/library with the user-library-modify
scope, which cliamp requests at sign-in. The local favorite is the source of
truth. If Spotify rejects the call, the local favorite stays and the status bar
shows a warning. To fix a scope error, run cliamp spotify reset and sign in
again. A like that you add in the Spotify app does not appear as a favorite in
cliamp. Episodes stay local favorites only.
Podcast episodes work as tracks. Press Ctrl+F to search Spotify. Matching episodes, such as "Joe Rogan", appear with songs. Press Enter to play. Playlists can load and play both songs and episodes.
- "OAuth failed": Ensure the Spotify dashboard redirect URI is exactly
http://127.0.0.1:19872/login, without a trailing slash. The temporary callback server listens only on this local address and does not accept connections from the network. On a remote machine, see Sign in on a remote machine. - Two authorization steps: This is expected with your own
client_id. After you approve Web API access, the same browser tab redirects to create a playback credential with the required Spotify built-in identity. - Playlist not showing: Save or follow the playlist in Spotify. The provider lists only library playlists.
- Playback issues: Spotify integration needs a Premium account. Free accounts cannot stream.
- Re-authenticate: When cliamp asks you to sign in, select Spotify and press
Enter. If the sign-in fails, the prompt stays, so pressEnteragain to retry. To clear stored credentials, runcliamp spotify reset. This is the same as deleting~/.config/cliamp/spotify_credentials.json. - Expired or revoked authorization: When Spotify rejects the access token with
401 Unauthorizedor revokes the refresh token, cliamp asks for a new sign-in. The provider list and playback both show the prompt. PressEnteron the prompt to sign in again. You do not need to restart cliamp. Spotify refused the audio key for this track: Spotify accepted the sign-in but refused the audio key of the track.cliamp.logshowsfailed retrieving aes key with code 1. On some accounts, Spotify refuses the key for every track while the official Spotify apps still play. A new sign-in,cliamp spotify reset, anotherclient_idor anotherbitratedoes not fix it. cliamp shows the error and does not ask you to sign in. Other players based on librespot get the same refusal. go-librespot#279 tracks the problem.403when you open a followed playlist: Spotify lets apps read only the playlists that you own or collaborate on. Add the tracks to your own playlist in Spotify, then open that playlist.429 Too Many Requests, includingrate-limited on /v1/me: Spotify accepted the credentials and throttled the app, so re-authenticating does not help. With the built-inclient_id, the quota is shared with librespot- and spotify-player-based clients worldwide, and a busy pool limits every client that uses it. Cliamp retries with exponential backoff, honoringRetry-After. IfRetry-Afteris longer than 1 minute, cliamp shows the error at once and does not wait. ARetry-Afterof hours (for example86400) means the app has no quota left for that window: register a developer app and setclient_idin[spotify]. Your app has a separate quota.400 "Invalid limit"on Ctrl+F: Development Mode apps limit/v1/searchto 10 results per request. Cliamp pages results automatically. This error means the limit is now less than 10. Open an issue.
- Spotify Premium account
- No additional system dependencies beyond cliamp itself
- A registered app at developer.spotify.com/dashboard is optional: cliamp has a built-in fallback
client_id