Native Android client for Spotify, built with Jetpack Compose
api-spotify
Spotify implementation of the Myspoti API (:api), on top of the official Web Player.
Modules
| Module | Role |
|---|---|
:api |
Pure Kotlin contract the UI sees: models and interfaces, no Android, no Spotify details |
:api-spotify |
This module: SpotifyApi implements :api |
:host-cdp |
Desktop host (Chrome over CDP) and the live integration tests |
Reads go straight to Spotify over HTTP (SpotifyHttp: the page's web token plus a client
token minted here). Playback, library writes, folders, Connect and Jam go through the page's
own services via the bridge. SpotifyApi.raw reaches all 179 GraphQL operations
(gql-ops.json, variables in gql-schema.json) and the 89 page services for anything not typed.
Coverage
All of these are exercised by host-cdp live tests against a free account:
| Domain | Methods |
|---|---|
| Player | play (any context), pause, resume, seek, next, previous, repeat, shuffle, queue add/remove/clear, volume, speed (podcasts only) |
| Search | all, tracks, artists, albums, playlists, shows, episodes, audiobooks, users, genres, suggestions, recent, clear recent |
| Catalog | track, album, album tracks, artist, top tracks, discography, related artists, appears on, similar albums |
| Library | contains/add/remove, library list with filters, sort and folders, liked songs, pin/unpin, create/rename/delete folders, move to folder |
| Playlists | playlist, tracks (paged, with row uids), sorted tracks (client side, ascending or descending), mine, editable, create, rename, description, public, collaborative, delete, follow/unfollow, add/remove/move tracks, recommended songs |
| Home | feed with filters, categories, category pages |
| Podcasts | show, episodes, episode, audiobook, chapters, saved episodes, save or unsave an episode |
| Users | me, public profile, top artists/tracks, follow/unfollow/is following, history |
| Track extras | lyrics (line and word sync, colours), canvas, credits, radio for a track or artist, taste-profile exclusion, don't play this artist |
| Devices | list, transfer, pull here |
| Jam | availability, session, start, join, leave, end, invite link, remove member, queue-only, participant volume |
Added without a live check (same mechanism as a verified neighbour, see the notes in
feature-inventory.md): don't play this artist (artistban),
save or unsave an episode (listenlater), public and collaborative (PlaylistAPI.updateDetails,
read back with getMetadata). The full feature list, with what needs a capture, is in that file.
Limits seen on the Web Player with a free account:
- Jam: Spotify answers
RESTRICTED, sostartfails; join and the rest are wired but unverified. - Private session: not supported by the Web Player (
isSupported: false). - Friend activity: not implemented by the Web Player;
friendActivity()returns an empty list. - Device transfer: needs a second Connect device to verify.
Tools (tools/): refresh_gql_ops.py (operation hashes from the public bundles),
extract_gql_variables.py (variables from captures), infer_gql_variables.py,
build_gql_schema.py (required variables and types from the server), capability_report.py.
Player bridge
src/main/resources/bridge/player-bridge.js runs inside the
official Web Player page (open.spotify.com), which keeps doing the playback with the
browser's Widevine CDM. The bridge finds the page's service registry through React's
context tree and calls its PlayerAPI, PlaybackAPI, LibraryAPI and TokenProvider.
It patches nothing in the page.
The same file runs in the Android WebView and in desktop Chrome over CDP.
Channels
| Direction | Android | Desktop (CDP) |
|---|---|---|
| Host → page | evaluateJavascript("Myspoti.call(id, method, args)") |
Runtime.evaluate, same call |
| Page → host | MyspotiHost.postMessage(json) (web message listener, open.spotify.com only) |
Runtime.addBinding("__mspHostPost") |
Myspoti.call also returns a Promise, but hosts should rely on the result message:
Android's evaluateJavascript does not wait for Promises.
Messages (page → host)
type |
Fields |
|---|---|
ready |
version |
state |
state: see below, or null when no playback session exists |
queue |
queue: {current, queued[], nextUp[]} of tracks |
result |
id, ok, value or error |
error |
error (boot failure) |
state: {track, contextUri, isPaused, isBuffering, positionMs, timestamp, durationMs, shuffle, repeat (0 off, 1 context, 2 track), speed, restrictions, playbackId}.
positionMs is the position at timestamp (epoch ms). Extrapolate it while playing.
track: {kind ("track", "episode" or "ad"), uri, uid, name, advertiser, durationMs, artists[{uri, name}], album{uri, name}, image, explicit, mediaType, provider}. An ad has kind: "ad", a spotify:ad: uri, an advertiser,
and restrictions that forbid skip and seek.
Methods
| Method | Args | Returns |
|---|---|---|
bridge.version |
1 |
|
player.state |
state or null |
|
player.queue |
queue | |
player.play |
contextUri, optional trackUri, trackUid, index, positionMs |
|
player.pause / player.resume |
||
player.seek |
positionMs |
|
player.next / player.previous |
||
player.setShuffle |
on |
|
player.setRepeat |
mode (0, 1, 2) |
|
queue.add |
uris[] |
|
queue.remove |
items[{uri, uid}] |
|
queue.clear |
||
volume.get / volume.set |
level (0 to 1) |
number |
library.contains |
uris[] |
boolean[] |
library.add / library.remove |
uris[] (tracks, albums, artists) |
|
token.get |
{accessToken, expiresAtMs} for the HTTP API |
Notes:
player.previousnear the start of a track goes back. Later, it restarts the track.queue.addlands within about a second, and aqueuemessage follows.- A command can be refused by
restrictions, for example while the next track loads. The error message says so.
Tests
Kotlin live tests: ./gradlew :host-cdp:test -Pcdp=http://localhost:9222.
The older Python harness bridge-tests/run_bridge_tests.py drives a logged-in Web Player in
desktop Google Chrome (Widevine included) over CDP. Each test restores what it changes.
google-chrome --user-data-dir="$HOME/.myspoti-chrome" --remote-debugging-port=9222
python run_bridge_tests.py # all tests
python run_bridge_tests.py -k queue # some tests (comma-separated)
Not covered yet: ads on free accounts, Connect (other devices), podcasts.