Skip to content

Latest commit

 

History

History
142 lines (94 loc) · 11.3 KB

spotify.md

File metadata and controls

142 lines (94 loc) · 11.3 KB

Spotify Integration

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 its client_id to 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 shared client_id without registering an app.

Setup

Recommended: bring your own client ID

Register a Spotify Developer app. Set its client_id in ~/.config/cliamp/config.toml:

[spotify]
client_id = "your_client_id_here"
bitrate = 320

To register an app:

  1. Go to developer.spotify.com/dashboard and sign in.
  2. Click Create app.
  3. Enter a name, such as "cliamp", and a description.
  4. Add http://127.0.0.1:19872/login as a Redirect URI.
  5. Select Web API under "Which API/SDKs are you planning to use?".
  6. Click Save.
  7. 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.

Development Mode search page size

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.

Alternative: built-in shared client ID

To use no registered app, omit the client_id line:

[spotify]
bitrate = 320

cliamp uses a built-in client_id. librespot and spotify-player use the same client ID.

Shared rate limit: The built-in client_id is shared by librespot, spotify-player, and cliamp users worldwide. Spotify applies its per-app quota globally. A busy pool can cause 429 Too Many Requests during search or playlist loading. Cliamp retries with backoff. Persistent 429 errors indicate a busy pool. Your own client_id has a separate quota.

Sign in on a remote machine

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
  1. Connect with the command above.
  2. In this SSH session, run cliamp, select Spotify, and press Enter.
  3. 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 Ctrl or Cmd. In other terminals, join the rows when you copy them. cliamp also writes the URL to ~/.config/cliamp/cliamp.log on the remote machine.
  4. 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.

Usage

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.

Controls

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.

Playlists and albums

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.

Add tracks to a playlist

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.

Favorites and Liked Songs

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.

Podcasts

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.

Troubleshooting

  • "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 press Enter again to retry. To clear stored credentials, run cliamp 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 Unauthorized or revokes the refresh token, cliamp asks for a new sign-in. The provider list and playback both show the prompt. Press Enter on 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.log shows failed 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, another client_id or another bitrate does 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.
  • 403 when 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, including rate-limited on /v1/me: Spotify accepted the credentials and throttled the app, so re-authenticating does not help. With the built-in client_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, honoring Retry-After. If Retry-After is longer than 1 minute, cliamp shows the error at once and does not wait. A Retry-After of hours (for example 86400) means the app has no quota left for that window: register a developer app and set client_id in [spotify]. Your app has a separate quota.
  • 400 "Invalid limit" on Ctrl+F: Development Mode apps limit /v1/search to 10 results per request. Cliamp pages results automatically. This error means the limit is now less than 10. Open an issue.

Requirements

  • 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