NTify-SpotAPI

A Java reimplementation of Spotify's internal desktop-client protocol (spclient) and its GraphQL/Pathfinder API

What this is

Spotify's official clients talk to backend services that were never publicly documented. This library reimplements enough of that protocol — playlists, collection/library, playback resumption, browse/home feeds, concerts, artist pages, user profiles — for a third-party Java application to act as a real Spotify client without going through the public, more limited Web API.

Everything here was reverse-engineered from real traffic and the real client binary, not from any leaked or purchased source code.

A note on AI use

Large parts of this reverse-engineering effort were done with AI assistance (via Claude Code). AI was used only as a tool to speed up the reverse-engineering process itself — decoding captured protobuf/JSON traffic, cross-referencing proto dumps, searching the disassembled client binary, and generating the resulting Java request/response classes from schemas that were already confirmed against real captured bytes. Every endpoint and message shape in this library was verified against actual wire traffic or the real client binary before being committed; AI was not used to guess at undocumented behavior without that verification step.

Features

• Playlists — create, follow/unfollow, modify content (add/remove/move tracks & episodes), rename/describe/change visibility, cover images, permissions, revision-based optimistic-concurrency writes, recommendations (Smart Shuffle)
• Rootlist — the user's top-level library listing of playlists and folders
• Collection — Liked Songs, followed artists, followed shows
• Playback resumption ("herodotus") — cross-device "continue where you left off" state: list current states, list/create resume-point revisions, batched writes
• Track — lyrics (with color palette)
• Feed — Browse tab (with category drill-down), Home tab, Live Events / concerts feed and concert details, full-text search (tracks, albums, artists, playlists, podcasts, episodes, audiobooks, users, genres, and a blended top-results section)
• Artist — discovered-on playlists, related artists, header image (Pathfinder GraphQL)
• User — public profile, followers/following
• Library — Your Library listing (playlists/albums/artists, folders), saved tracks, batch "is this saved" lookups
• Extended metadata — decorated entity metadata lookups

All of this is backed by two transports depending on the endpoint's era:

• Classic spclient protobuf/JSON services (RequestBuilder)
• Spotify's newer Pathfinder GraphQL surface, both the POST persisted-query form (GraphQLRequestBuilder, api-partner.spotify.com/pathfinder/v2/query) and the older GET/query-string persisted-query form (PathfinderGetRequestBuilder, pathfinder/v1/query)

Requirements

• Java 8 (the library targets Java 8 bytecode — avoid Java 9+ APIs when contributing)
• Maven

Building

mvn compile

src/main/proto/*.proto is compiled automatically via the protobuf-maven-plugin into com.spotify.* packages under src/main/java — generated sources are committed to the repo, not gitignored, so there's no separate codegen step to run.

Using the library

Everything starts from a SpotAPI instance, built with a valid access token, client token, and a few identifying headers:

SpotAPI api = new SpotAPI.Builder()
        .setToken(accessToken)
        .setClientToken(clientToken)
        .setAppPlatform("Linux")
        .setUserAgent("Spotify/128200428 Linux/Unknown")
        .setHttpClient(new OkHttpClient())
        .setSpotifyClientHost("gew4-spclient.spotify.com:443")
        .setUserInfo(new UserInfo(username, country, catalogue))
        .build();

// Fetch the current user's rootlist
Playlist4ApiProto.SelectedListContent rootlist = api.playlist().rootlist().execute();

// Like a track
api.collection().write()
        .addUris("spotify:track:1Lhwn4PqeGpM4LTVUowW76")
        .execute();

// Fetch the Home feed
HomeResponse home = api.feed().home().execute();

This library does not perform authentication itself — you need to obtain a genuine access token and client token yourself (e.g. via a real login flow) and supply them to the builder. See src/test/spotify-token.py for one way this project does that during its own test runs (via librespot's Python bindings).

Running the tests

The test suite (src/test/java/*Tests.java) is a set of live integration tests — it makes real requests against Spotify's actual backend using a real account's credentials. There is no mocking.

mvn test

Requirements to run it:

• A working Python virtualenv at .venv with librespot/librespot_player installed (used by spotify-token.py to perform a real OAuth login and mint an access token + client token)
• Network access to Spotify's servers
• Optionally, a proxy on 127.0.0.1:8082 (e.g. mitmproxy) — if reachable, traffic is automatically routed through it with certificate validation disabled, for inspecting requests live

Because these are live tests against a real account, running the full suite is not side-effect-free: it creates/modifies playlists, writes resume points, and adds/removes items from your library/collection as part of exercising the write paths.

Run a single test class or method with:

mvn test -Dtest=FeedTests
mvn test -Dtest=FeedTests#browse

Project layout

• src/main/java/com/spotifyxp/spotapi/ — the library itself. SpotAPI is the central client object; request classes live under requests/, grouped by domain (requests/playlist/, requests/feed/, requests/library/, etc.), and extend RequestBuilder<T, SELF> (or GraphQLRequestBuilder/PathfinderGetRequestBuilder for the two Pathfinder GraphQL transports)
• src/main/proto/ — the proto files actually compiled into the library's generated Java sources
• protos/, protosNew/, SpotifyNewProtos/ — loose reference dumps of Spotify proto schemas collected during reverse engineering, not all of them wired into the build
• src/test/ — the live JUnit 5 test suite described above