lockstep-jukebox/README.md

lockstep-jukebox

Gradle project containing jukebox, an Android library that implements the data layer for a music player: it syncs playlist and track metadata from the Lockstep Spotify wrapper API (https://api.lockstep.at) into a local SQLite database (via Room), so the app can read playlists and tracks offline after sync.

Repository layout:

• jukebox/ — Android library (Java, Retrofit, Gson, Room).
• docs/playlists.md — HTTP contract for GET /playlists and GET /playlists/{id}.
• schema/playlist_cache.sql — reference schema for the on-device cache tables.

The library does not handle Spotify login, audio playback, or full Spotify API modeling—only what’s needed to cache the metadata described in the docs.

Main entry points

Entry	Role
Jukebox.playlistRepository(Context, Interceptor)	Convenience factory. Builds DefaultPlaylistRepository with default base URL https://api.lockstep.at/. Optional overload passes a custom baseUrl. You supply an Interceptor so session cookies, Authorization, or other headers stay in the host app.
DefaultPlaylistRepository.create(...)	Same wiring as Jukebox; use when you prefer a static factory on the concrete type.
PlaylistRepository	Primary API surface after construction: syncInitial() (full refresh), syncDelta(retainRemovedPlaylists) (incremental sync using snapshot_id), observePlaylists() / getPlaylists(), observeTracks(playlistId) / getTracks(playlistId). Sync methods block and perform I/O—call them off the main thread. Observation returns LiveData for lifecycle-friendly UI updates.
LockstepPlaylistClient	Interface implemented by PlaylistRemoteClient. Lets tests or advanced setups swap the network backend without changing SyncCoordinator.

Errors from the API’s { "ok": false, "error": "..." } shape are thrown as LockstepApiException. Network failures use IOException.

Building

From the repo root (with ANDROID_HOME / local.properties sdk.dir set):

./gradlew :jukebox:assembleDebug
./gradlew :jukebox:testDebugUnitTest

On Windows, use gradlew.bat instead of ./gradlew.