Skip to content

Unofficial YouTube Music / Spotify Premium client for Android, built in Liquid Glass. Audio effects, Spotify Connect, listening history, 8 languages. Rust core on librespot.

Show the home page Spotify makes for you

Leloniofa0e79dc6139
diff --git a/app/src/main/java/dev/lelonio/square/data/SpotifyHome.kt b/app/src/main/java/dev/lelonio/square/data/SpotifyHome.kt
new file mode 100644
index 0000000..1143d8d
--- /dev/null
+++ b/app/src/main/java/dev/lelonio/square/data/SpotifyHome.kt
@@ -0,0 +1,126 @@
+package dev.lelonio.square.data
+
+import org.json.JSONArray
+import org.json.JSONObject
+
+/**
+ * One row of the personalised home: a title, and the things under it.
+ *
+ * Spotify's own shelves, which is what makes this worth having. The account's
+ * playlists are already readable through the access point; "Made for you", the
+ * daily mixes and the rest are assembled per listener and exist nowhere else.
+ */
+data class HomeShelf(
+ val title: String,
+ val items: List<CatalogPlaylist>,
+)
+
+/**
+ * Turns the gateway's answer into shelves; see native/src/pathfinder.rs.
+ *
+ * Forgiving on purpose. This reads a private interface that changes without
+ * notice, so anything unrecognised is skipped rather than treated as an error:
+ * a home with four rows out of eight is worth more than a page that refuses to
+ * draw because one item had a shape nobody expected.
+ */
+object SpotifyHome {
+
+ /** Sections whose items are one-per-row filler; see the note in [parse]. */
+ private const val BASELINE = "HomeFeedBaselineSectionData"
+
+ fun parse(json: String): List<HomeShelf> = runCatching {
+ val sections = JSONObject(json)
+ .getJSONObject("data")
+ .getJSONObject("home")
+ .getJSONObject("sectionContainer")
+ .getJSONObject("sections")
+ .getJSONArray("items")
+
+ (0 until sections.length()).mapNotNull { index ->
+ shelf(sections.getJSONObject(index))
+ }
+ }.getOrDefault(emptyList())
+
+ private fun shelf(section: JSONObject): HomeShelf? {
+ val data = section.optJSONObject("data") ?: return null
+
+ // The endless feed at the bottom of Spotify's own home: dozens of
+ // sections holding a single item each, several of them titled the same.
+ // A carousel of one tile is not a row, and repeating "Made for you"
+ // eight times down a page is not a home.
+ if (data.optString("__typename") == BASELINE) return null
+
+ val title = data.optJSONObject("title")?.optString("transformedLabel").orEmpty()
+ if (title.isEmpty()) return null
+
+ val items = section.optJSONObject("sectionItems")?.optJSONArray("items")
+ ?: return null
+ val entries = (0 until items.length()).mapNotNull { index ->
+ entry(items.getJSONObject(index))
+ }
+ return if (entries.isEmpty()) null else HomeShelf(title, entries)
+ }
+
+ private fun entry(item: JSONObject): CatalogPlaylist? {
+ val uri = item.optString("uri")
+ if (uri.isEmpty()) return null
+ val content = item.optJSONObject("content") ?: return null
+ val data = content.optJSONObject("data") ?: return null
+
+ return when (data.optString("__typename")) {
+ "Playlist" -> CatalogPlaylist(
+ uri = uri,
+ name = data.optString("name"),
+ artworkUrl = firstImage(data.optJSONObject("images")),
+ )
+
+ "Album" -> CatalogPlaylist(
+ uri = uri,
+ name = data.optString("name"),
+ artworkUrl = sourceUrl(data.optJSONObject("coverArt")),
+ )
+
+ "Artist" -> CatalogPlaylist(
+ uri = uri,
+ name = data.optJSONObject("profile")?.optString("name").orEmpty(),
+ artworkUrl = sourceUrl(
+ data.optJSONObject("visuals")?.optJSONObject("avatarImage"),
+ ),
+ )
+
+ // Podcasts and audiobooks come down the same pipe. This app plays
+ // music, and a tile that cannot be opened is worse than a gap.
+ else -> null
+ }
+ }
+
+ /** The `images { items { sources } }` shape playlists use. */
+ private fun firstImage(images: JSONObject?): String? {
+ val items = images?.optJSONArray("items") ?: return null
+ if (items.length() == 0) return null
+ return sourceUrl(items.optJSONObject(0))
+ }
+
+ /**
+ * The largest picture on offer, or the only one.
+ *
+ * Sizes are not always given: playlist covers arrive with null dimensions
+ * and a single source, album art with three. Sorting by width and taking
+ * the end covers both without a special case.
+ */
+ private fun sourceUrl(holder: JSONObject?): String? {
+ val sources: JSONArray = holder?.optJSONArray("sources") ?: return null
+ var best: String? = null
+ var width = -1
+ for (index in 0 until sources.length()) {
+ val source = sources.optJSONObject(index) ?: continue
+ val url = source.optString("url").takeIf { it.isNotEmpty() } ?: continue
+ val size = source.optInt("width", 0)
+ if (best == null || size > width) {
+ best = url
+ width = size
+ }
+ }
+ return best
+ }
+}
diff --git a/app/src/main/java/dev/lelonio/square/nativecore/NativeBridge.kt b/app/src/main/java/dev/lelonio/square/nativecore/NativeBridge.kt
index f1cd267..509f831 100644
--- a/app/src/main/java/dev/lelonio/square/nativecore/NativeBridge.kt
+++ b/app/src/main/java/dev/lelonio/square/nativecore/NativeBridge.kt
@@ -218,6 +218,17 @@ object NativeBridge {
*/
fun takeOver() = nativeTakeOver()
+ /**
+ * The account's personalised home, as raw JSON from Spotify's gateway.
+ *
+ * A different service from everything else here, and a more fragile one:
+ * the query is sent as a hash of one Spotify already knows, and those
+ * hashes change when its web client is rebuilt. Callers must be able to
+ * carry on with nothing. Blocking.
+ */
+ fun homeFeed(timeZone: String, language: String): String =
+ nativeHomeFeed(timeZone, language)
+
/** This device's own Connect id, which is what says "here" rather than "there". */
fun deviceId(): String = runCatching { nativeDeviceId() }.getOrDefault("")
@@ -324,6 +335,7 @@ object NativeBridge {
private external fun nativePublishContext(positionMs: Int): Boolean
private external fun nativeResumeHere(contextUri: String, trackUri: String, positionMs: Int)
private external fun nativeTakeOver()
+ private external fun nativeHomeFeed(timeZone: String, language: String): String
private external fun nativeDeviceId(): String
private external fun nativeRemoteState(): String
private external fun nativeRemoteDevices(): String
diff --git a/app/src/main/java/dev/lelonio/square/ui/MainViewModel.kt b/app/src/main/java/dev/lelonio/square/ui/MainViewModel.kt
index 167082b..64b5d1c 100644
--- a/app/src/main/java/dev/lelonio/square/ui/MainViewModel.kt
+++ b/app/src/main/java/dev/lelonio/square/ui/MainViewModel.kt
@@ -16,6 +16,8 @@ import dev.lelonio.square.data.AddTracksRequestDto
import dev.lelonio.square.data.RemoveTracksRequestDto
import dev.lelonio.square.data.TrackUriDto
import dev.lelonio.square.data.CatalogPlaylist
+import dev.lelonio.square.data.HomeShelf
+import dev.lelonio.square.data.SpotifyHome
import dev.lelonio.square.data.CatalogTrack
import dev.lelonio.square.data.ContextCacheStore
import dev.lelonio.square.data.SearchItem
@@ -982,6 +984,8 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
_state.value = it
loadProfile()
loadMissingCovers()
+ // Spotify's own shelves, once there is a session to ask with.
+ loadHomeShelves()
}
.onFailure {
android.util.Log.e(TAG, "library load failed: ${chain(it)}", it)
@@ -1100,6 +1104,39 @@ class MainViewModel(app: Application) : AndroidViewModel(app) {
* replaces it only when it has the whole thing, so reopening never takes a
* finished list away and rebuilds it in front of the user.
*/
+ private val _homeShelves = MutableStateFlow<List<HomeShelf>>(emptyList())
+
+ /**
+ * Spotify's own personalised home: the mixes, "made for you", the shelves
+ * that change through the day.
+ *
+ * Empty is a perfectly good answer. It comes from a private gateway whose
+ * queries are addressed by a hash of themselves, and those hashes are
+ * retired whenever Spotify rebuilds its web client, so this page has to be
+ * one the app can do without. Everything below it is read the old way and
+ * does not depend on this at all.
+ */
+ val homeShelves: StateFlow<List<HomeShelf>> = _homeShelves.asStateFlow()
+
+ private fun loadHomeShelves() = viewModelScope.launch {
+ val shelves = withContext(Dispatchers.IO) {
+ runCatching {
+ SpotifyHome.parse(
+ NativeBridge.homeFeed(
+ java.util.TimeZone.getDefault().id,
+ java.util.Locale.getDefault().language,
+ ),
+ )
+ }
+ .onFailure { android.util.Log.i(TAG, "no personalised home: ${describe(it)}") }
+ .getOrDefault(emptyList())
+ }
+ if (shelves.isNotEmpty()) {
+ android.util.Log.i(TAG, "home: ${shelves.size} shelves from the gateway")
+ _homeShelves.value = shelves
+ }
+ }
+
private val _inPlaylists = MutableStateFlow<Set<String>>(emptySet())
/**
diff --git a/app/src/main/java/dev/lelonio/square/ui/SquareApp.kt b/app/src/main/java/dev/lelonio/square/ui/SquareApp.kt
index 1a4e509..c1de930 100644
--- a/app/src/main/java/dev/lelonio/square/ui/SquareApp.kt
+++ b/app/src/main/java/dev/lelonio/square/ui/SquareApp.kt
@@ -233,6 +233,7 @@ fun SquareApp(
val elsewhereActive by dev.lelonio.square.data.RemoteConnect.elsewhereActive
.collectAsStateWithLifecycle()
val inPlaylists by viewModel.inPlaylists.collectAsStateWithLifecycle()
+ val homeShelves by viewModel.homeShelves.collectAsStateWithLifecycle()
val remote = elsewhere?.takeIf { elsewhereActive }
val remoteLabel = stringResource(R.string.playing_on, remote?.deviceName.orEmpty())
val playback = remote?.asPlaybackState(remoteLabel) ?: local
@@ -662,6 +663,7 @@ fun SquareApp(
youtubeMode =
backend == dev.lelonio.square.backend.BackendId.YOUTUBE_MUSIC,
youtubeHome = youtubeHome,
+ shelves = homeShelves,
onPlayTrending = { tracks, index ->
onPlay(tracks, index, null, false, trendingLabel, 0L)
},
diff --git a/app/src/main/java/dev/lelonio/square/ui/home/HomeScreen.kt b/app/src/main/java/dev/lelonio/square/ui/home/HomeScreen.kt
index 0dd8a6a..e243084 100644
--- a/app/src/main/java/dev/lelonio/square/ui/home/HomeScreen.kt
+++ b/app/src/main/java/dev/lelonio/square/ui/home/HomeScreen.kt
@@ -138,6 +138,14 @@ fun HomeScreen(
youtubeMode: Boolean = false,
youtubeHome: MainViewModel.YouTubeHomeState = MainViewModel.YouTubeHomeState(),
onPlayTrending: (List<CatalogTrack>, Int) -> Unit = { _, _ -> },
+ /**
+ * Spotify's own personalised shelves, empty when the gateway said nothing.
+ *
+ * Shown above the rows this app builds itself. They are what the listener
+ * recognises as their home page, and unlike everything below them they
+ * cannot be reconstructed from the account's playlists.
+ */
+ shelves: List<dev.lelonio.square.data.HomeShelf> = emptyList(),
) {
if (youtubeMode) {
YouTubeHome(
@@ -282,15 +290,29 @@ fun HomeScreen(
bottom = contentPadding.calculateBottomPadding(),
),
) {
- // First on the page, and deliberately: what the account is
- // playing this month is the one row that is different every
- // time it is opened.
+ // Spotify's own shelves come first, because they are what the
+ // listener recognises as their home and the only rows here that
+ // this app could not have built itself. What the account has
+ // been playing follows: it is worth having, and it is also the
+ // same answer for weeks at a time.
+ //
// Every feed section keeps its place while it is still being
// fetched. The account's playlists and its recent tracks are
// held on the device and draw at once; everything else is a Web
// API round trip a second or two behind, and without a
// placeholder the page arrived in two halves and shifted under
// whatever was being read.
+ if (filter == Feed.ALL) {
+ shelves.forEach { shelf ->
+ item(contentType = "shelf") { Heading(shelf.title) }
+ item(contentType = "shelf") {
+ Carousel(shelf.items, key = { it.uri }) { entry ->
+ PlaylistTile(entry) { onOpenPlaylist(entry) }
+ }
+ }
+ }
+ }
+
if (showForYou && feed.topTracks.isEmpty() && feed.loading) {
item(contentType = "skeleton") {
SkeletonSection(tileWidth = 152.dp, tileHeight = 152.dp)
diff --git a/native/Cargo.lock b/native/Cargo.lock
index dea94e6..0c1f8f3 100644
--- a/native/Cargo.lock
+++ b/native/Cargo.lock
@@ -2330,6 +2330,7 @@ name = "squarecore"
version = "0.1.0"
dependencies = [
"android_logger",
+ "bytes",
"futures-util",
"http",
"jni",
diff --git a/native/Cargo.toml b/native/Cargo.toml
index 66c95e6..a92b1fc 100644
--- a/native/Cargo.toml
+++ b/native/Cargo.toml
@@ -28,6 +28,8 @@ log = "0.4"
once_cell = "1"
# Same major as librespot-core, so `Method` is the type spclient expects.
http = "1.3"
+# The body type librespot's own HTTP client takes.
+bytes = "1"
serde_json = "1"
futures-util = "0.3"
diff --git a/native/src/ffi.rs b/native/src/ffi.rs
index 8d68bb7..12a0441 100644
--- a/native/src/ffi.rs
+++ b/native/src/ffi.rs
@@ -491,6 +491,21 @@ pub extern "system" fn Java_dev_lelonio_square_nativecore_NativeBridge_nativeTak
guard(&mut env, "TakeOver", engine::take_over);
}
+/// The account's personalised home, as raw JSON from Spotify's gateway.
+#[no_mangle]
+pub extern "system" fn Java_dev_lelonio_square_nativecore_NativeBridge_nativeHomeFeed(
+ mut env: JNIEnv,
+ _class: JClass,
+ time_zone: JString,
+ language: JString,
+) -> jstring {
+ let zone = read_string(&mut env, &time_zone).unwrap_or_default();
+ let language = read_string(&mut env, &language).unwrap_or_default();
+ guard_string(&mut env, "HomeFeed", || {
+ crate::pathfinder::home(&zone, &language)
+ })
+}
+
/// This device's own Connect id.
#[no_mangle]
pub extern "system" fn Java_dev_lelonio_square_nativecore_NativeBridge_nativeDeviceId(
diff --git a/native/src/lib.rs b/native/src/lib.rs
index f98251e..062d734 100644
--- a/native/src/lib.rs
+++ b/native/src/lib.rs
@@ -9,6 +9,7 @@ mod catalog;
mod engine;
mod events;
mod ffi;
+mod pathfinder;
mod remote;
mod sink;
diff --git a/native/src/pathfinder.rs b/native/src/pathfinder.rs
new file mode 100644
index 0000000..be121e0
--- /dev/null
+++ b/native/src/pathfinder.rs
@@ -0,0 +1,171 @@
+//! Spotify's GraphQL gateway, which is where the personalised pages live.
+//!
+//! The access point answers about things that exist: a playlist, an album, the
+//! account's own list of playlists. It does not answer about a person. "Made
+//! for you", the daily mixes, the shelves that change through the day are put
+//! together somewhere else, and the web client reads them from
+//! `api-partner.spotify.com/pathfinder`.
+//!
+//! Two things make this different from every other call in this app, and both
+//! are reasons to keep it at arm's length.
+//!
+//! The queries are persisted: the client does not send GraphQL, it sends a
+//! sha256 of a query Spotify already knows, and those hashes change when the
+//! web client is rebuilt. A hash that has been retired answers with an error
+//! rather than data, so anything reading this has to survive getting nothing
+//! back. The hashes below were read out of a network capture of the web player.
+//!
+//! And it is a different host from the rest, so it needs the tokens spelled out
+//! rather than the access point's own plumbing.
+
+use crate::engine;
+use bytes::Bytes;
+use http::{header::HeaderValue, Method, Request};
+use librespot_core::Session;
+
+const ENDPOINT: &str = "https://api-partner.spotify.com/pathfinder/v2/query";
+
+/// The web player Spotify believes it is talking to.
+///
+/// Sent because the gateway expects a client to say what it is; the values are
+/// the web player's own, since that is the client these queries belong to.
+const APP_PLATFORM: &str = "WebPlayer";
+
+/// The web client's own version string, as captured from it.
+///
+/// Sent because the gateway is choosy about who is asking: with the platform
+/// alone the home query answered `GenericError`, which is what it says to a
+/// caller it does not recognise rather than to one it refuses. Like the query
+/// hashes, this ages: see the note at the top of the file.
+const APP_VERSION: &str = "1.2.97.155.g5dd0dcaf-development";
+
+/// One persisted query, by name and hash. See the note at the top of the file.
+struct Query {
+ name: &'static str,
+ hash: &'static str,
+}
+
+/// The personalised home: the shelves, in the order the account is meant to see
+/// them.
+const HOME: Query = Query {
+ name: "home",
+ hash: "76243c78b0e20ecdbe41b794dec8cbe73f75e585b0a7201b8d2e84578412847a",
+};
+
+/// Runs one persisted query and returns the raw JSON body.
+async fn query(
+ session: &Session,
+ query: &Query,
+ variables: String,
+ language: &str,
+) -> engine::EngineResult<String> {
+ let body = format!(
+ concat!(
+ "{{\"operationName\":\"{}\",\"variables\":{},",
+ "\"extensions\":{{\"persistedQuery\":{{\"version\":1,\"sha256Hash\":\"{}\"}}}}}}"
+ ),
+ query.name, variables, query.hash
+ );
+
+ let token = session
+ .login5()
+ .auth_token()
+ .await
+ .map_err(|e| format!("no access token: {e}"))?;
+
+ let mut request = Request::builder()
+ .method(&Method::POST)
+ .uri(ENDPOINT)
+ .body(Bytes::from(body))
+ .map_err(|e| format!("bad request: {e}"))?;
+
+ {
+ let headers = request.headers_mut();
+ headers.insert(
+ http::header::CONTENT_TYPE,
+ HeaderValue::from_static("application/json;charset=UTF-8"),
+ );
+ headers.insert(
+ http::header::ACCEPT,
+ HeaderValue::from_static("application/json"),
+ );
+ headers.insert("app-platform", HeaderValue::from_static(APP_PLATFORM));
+ // The shelves are titled by the server, and the greeting with them, so
+ // the page arrives in English unless this says otherwise.
+ if let Ok(value) = HeaderValue::from_str(language) {
+ headers.insert(http::header::ACCEPT_LANGUAGE, value);
+ }
+ headers.insert("spotify-app-version", HeaderValue::from_static(APP_VERSION));
+ headers.insert(
+ http::header::ORIGIN,
+ HeaderValue::from_static("https://open.spotify.com"),
+ );
+ headers.insert(
+ http::header::REFERER,
+ HeaderValue::from_static("https://open.spotify.com/"),
+ );
+ headers.insert(
+ http::header::AUTHORIZATION,
+ HeaderValue::from_str(&format!("{} {}", token.token_type, token.access_token))
+ .map_err(|e| format!("bad token: {e}"))?,
+ );
+ // Without this the gateway answers 401 whatever the access token says:
+ // it identifies the client, not the listener.
+ match session.spclient().client_token().await {
+ Ok(client_token) => {
+ if let Ok(value) = HeaderValue::from_str(&client_token) {
+ headers.insert("client-token", value);
+ }
+ }
+ Err(e) => log::warn!("pathfinder without a client token: {e}"),
+ }
+ }
+
+ let response = session
+ .http_client()
+ .request_body(request)
+ .await
+ .map_err(|e| format!("{} failed: {e}", query.name))?;
+
+ String::from_utf8(response.to_vec()).map_err(|e| format!("unreadable answer: {e}"))
+}
+
+/// A stable stand-in for the web client's visitor cookie.
+fn visitor_id() -> String {
+ // Derived from the device id so it does not change between launches, and
+ // means nothing outside this call.
+ let id = engine::with_session(|session| session.device_id().to_string()).unwrap_or_default();
+ let digest: u128 = id
+ .bytes()
+ .fold(0u128, |acc, b| acc.wrapping_mul(31).wrapping_add(b as u128));
+ format!("{digest:032x}")
+}
+
+/// The account's home page, as Spotify's own client receives it.
+pub fn home(time_zone: &str, language: &str) -> engine::EngineResult<String> {
+ let handle = engine::runtime_handle()?;
+ let session = engine::with_session(|session| session.clone())?;
+
+ // The time zone decides what "good evening" and the daily mixes are, and
+ // the gateway wants it named rather than guessed from an offset.
+ let zone = if time_zone.is_empty() {
+ "Europe/Rome".to_string()
+ } else {
+ time_zone.to_string()
+ };
+ let language = if language.is_empty() { "en" } else { language }.to_string();
+ // `sp_t` is the web client's own visitor id, a cookie it sends with every
+ // one of these. Sent here as a fixed value derived from nothing, because
+ // what it identifies is a browser this app does not have; whether the
+ // gateway cares is exactly what this is for.
+ let variables = format!(
+ concat!(
+ "{{\"homeEndUserIntegration\":\"INTEGRATION_WEB_PLAYER\",\"timeZone\":\"{}\",",
+ "\"sp_t\":\"{}\",",
+ "\"facet\":\"\",\"sectionItemsLimit\":10,\"includeEpisodeContentRatingsV2\":true}}"
+ ),
+ zone, visitor_id()
+ );
+
+ handle.block_on(async move { query(&session, &HOME, variables, &language).await })
+}