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.

Say in the README that there are two backends now

Lelonioc4eab3e8172b
diff --git a/README.md b/README.md
index 1a67dd5..f032772 100644
--- a/README.md
+++ b/README.md
@@ -5,26 +5,37 @@
<h1 align="center">Square</h1>
<p align="center">
- An unofficial Android client for Spotify Premium, built in Liquid Glass.
+ An unofficial Android music client for Spotify Premium and YouTube Music,
+ built in Liquid Glass.
</p>
-Built on [librespot](https://github.com/librespot-org/librespot). The official
-app is not needed and is not used: audio is streamed in-process by a native Rust
-core.
+One app over two catalogues. Spotify plays through
+[librespot](https://github.com/librespot-org/librespot), so the official app is
+not needed and is not used: audio is streamed in-process by a native Rust core.
+YouTube Music plays through its own endpoints, where search and playback need no
+account at all. Which one the music comes from is the first question a fresh
+install asks, and it can be changed later in the settings.
| Player | Effects | Home |
| --- | --- | --- |
| ![The player](docs/screenshots/player.png) | ![The effects panel](docs/screenshots/effects.png) | ![The home page](docs/screenshots/home.png) |
-## Why use this instead of the official app
+## Why use this instead of the official apps
-**It is built in Liquid Glass.** Every control — the tab bar, the player, the
-sheets, the menus — is drawn on one refracting material that bends the artwork
+**It is one app for both.** The same player, the same library, the same
+effects, over Spotify or over YouTube Music. Spotify is your own account, with
+its playlists, its Connect devices and its listening history, and it needs a
+login and a little setup. YouTube Music is the whole catalogue, searchable and
+playable the moment the app opens, with signing in optional and worth it only
+for your own playlists.
+
+**It is built in Liquid Glass.** Every control, the tab bar, the player, the
+sheets and the menus, is drawn on one refracting material that bends the artwork
and the canvas video behind it. Nothing on Spotify for Android looks like this,
and it is the reason the app exists.
**It can bend the music.** Speed and pitch move independently, there is a real
-reverb on the output, and the three save as presets — so "slowed + reverb" is a
+reverb on the output, and the three save as presets, so "slowed + reverb" is a
single tap on any track in the catalogue rather than a file someone else made.
**It is fast.** A skip is sound in about a third of a second, because the engine
@@ -32,24 +43,34 @@ fetches the next track while the current one plays and the app never waits on it
to move. The playing list is cached rather than rebuilt, so scrolling stays at
the screen's own frame rate.
-> **Read this before you install it.** Square re-implements Spotify's protocol,
-> which their Terms of Service forbid. It cannot go on the Play Store, it needs
-> a Premium account, and using it is at your own risk. There is no warranty of
-> any kind — see the licence.
+> **Read this before you install it.** Both backends talk to services on terms
+> they do not offer: Square re-implements Spotify's protocol, which their Terms
+> of Service forbid, and reads YouTube Music through the private endpoints its
+> own web client uses. It cannot go on the Play Store, the Spotify side needs a
+> Premium account, and using it is at your own risk. There is no warranty of any
+> kind. See the licence.
## What it does
-- **Plays your library.** Playlists, albums, artists, liked songs, search, all
- through Spotify's own access point rather than the public Web API.
-- **Is a Connect device.** Square appears in the device list of every other
- Spotify client, and playback can be handed to and taken from it.
-- **Records what you listen to.** Listens are reported to the account, filed
- under the playlist or album they happened in, so Square can be used *instead*
- of the official client rather than beside it.
-- **Lyrics, canvas, artwork.** Synced lyrics where Spotify has them, the looping
- canvas video on the player, and the covers of the generated playlists in the
- app's own language.
-- **Audio effects.** Speed and pitch independently, plus reverb, with presets —
+- **Plays two catalogues.** Spotify or YouTube Music, chosen at first launch and
+ changeable in the settings. Home, search, the library and the player all go
+ through whichever one is selected.
+- **Plays your library.** Playlists, albums, artists, liked songs, search. On
+ Spotify through its own access point rather than the public Web API; on
+ YouTube Music anonymously, with an optional Google sign-in that adds the
+ account's own playlists and home shelves.
+- **Is a Connect device** *(Spotify)*. Square appears in the device list of
+ every other Spotify client, and playback can be handed to and taken from it.
+- **Records what you listen to** *(Spotify)*. Listens are reported to the
+ account, filed under the playlist or album they happened in, so Square can be
+ used *instead* of the official client rather than beside it.
+- **Lyrics, canvas, artwork.** Synced lyrics, from Spotify where it has them
+ and from [LrcLib](https://lrclib.net) for the YouTube side; the looping
+ Spotify canvas video on the player; and the covers of the generated playlists
+ in the app's own language.
+- **Watches the video** *(YouTube Music)*. One tap on the player swaps the audio
+ stream for the real video, in place, without losing the queue or the position.
+- **Audio effects.** Speed and pitch independently, plus reverb, with presets:
the "slowed + reverb" edit, done properly, on any track.
- **Android Auto.** Playlists and recently played are browsable in the car, and
voice search plays from the catalogue. Auto only lists apps it was installed
@@ -61,26 +82,42 @@ the screen's own frame rate.
## Architecture
```
-┌─────────────────────────────────────────┐
-│ Compose UI │
-├─────────────────────────────────────────┤
-│ MediaController ──► MediaSession │ notification, lock screen, Bluetooth
-├─────────────────────────────────────────┤
-│ PlaybackService │ foreground service, owns the engine
-│ └─ LibrespotPlayer : SimpleBasePlayer │ adapts the engine to Media3
-├──────────────────┬──────────────────────┤
-│ Web API (HTTPS) │ JNI ──► libsquarecore│
-│ search, top │ librespot │
-│ tracks, devices │ + AudioTrack │
-└──────────────────┴──────────────────────┘
+┌───────────────────────────────────────────────────────────┐
+│ Compose UI │
+├───────────────────────────────────────────────────────────┤
+│ MediaController ──► MediaSession │ notification, lock screen, Bluetooth
+├───────────────────────────────────────────────────────────┤
+│ PlaybackService │ foreground service, owns the player
+├───────────────────────────────────────────────────────────┤
+│ MusicBackend selected once, swapped on change │
+├──────────────────────────┬────────────────────────────────┤
+│ SpotifyBackend │ YouTubeBackend │
+│ LibrespotPlayer │ ExoPlayer │
+│ : SimpleBasePlayer │ + YouTubeStreamResolver │
+├─────────────────┬────────┼──────────────────┬─────────────┤
+│ Web API (HTTPS) │ JNI ──►│ NewPipeExtractor │ innertube │
+│ search, top │ libsq… │ search, streams │ the account │
+│ tracks, devices │ libre… │ anonymous │ library │
+└─────────────────┴────────┴──────────────────┴─────────────┘
```
-The catalogue comes from the access point (`native/src/catalog.rs`), not from
-`api.spotify.com`: the Web API meters requests per application, and there is no
-streaming endpoint there at all. The Web API is used only where the access point
-has nothing to offer — search, the account's top tracks, the Connect device
-list, editing playlists — and that is why Square asks you to register an
-application of your own.
+`MusicBackend` is the seam: every catalogue read and the `Player` itself come
+from it, so no screen has to know which service is answering. A backend that
+cannot do something, as YouTube Music has no Connect device list, returns the
+empty value rather than throwing, and that is what keeps one UI usable on both.
+
+On the YouTube side the split is by what needs an account, not by preference.
+Search, trending and stream URLs are public and go through NewPipeExtractor,
+which is why the app works before anyone signs in and for anyone who never does.
+The library is the account's own, so it goes through the vendored
+[`innertube/`](innertube/) module with the session cookie attached.
+
+On the Spotify side the catalogue comes from the access point
+(`native/src/catalog.rs`), not from `api.spotify.com`: the Web API meters
+requests per application, and there is no streaming endpoint there at all. The
+Web API is used only where the access point has nothing to offer: search, the
+account's top tracks, the Connect device list and editing playlists. That is why
+Square asks you to register an application of your own.
The player keeps no copy of the engine's state: `LibrespotPlayer` reports only
what the engine has confirmed by event. That is why the seek bar never runs
@@ -122,7 +159,7 @@ keytool -genkey -v -keystore square-release.jks -keyalg RSA \
```
```properties
-# keystore.properties — never commit this
+# keystore.properties, never commit this
storeFile=square-release.jks
storePassword=…
keyAlias=square
@@ -141,7 +178,7 @@ process. All four are explained in
**OAuth uses the keymaster client id on a fixed port.** The redirect has to be
exactly `http://127.0.0.1:5588/login`, the only one registered for that id, and
-the socket must be bound to the IPv4 loopback explicitly — on Android
+the socket must be bound to the IPv4 loopback explicitly: on Android
`InetAddress.getLoopbackAddress()` answers `::1` and the browser then fails the
redirect with `ERR_CONNECTION_REFUSED`.
@@ -156,8 +193,13 @@ vanishes silently.
`MediaItemData` twice a second makes enough garbage to be heard as stuttering.
The list is cached and dropped only when the queue actually changes.
+**Keep NewPipeExtractor current.** YouTube breaks extraction deliberately and
+often, and a version a few months stale does not fail loudly: v0.24.6 still
+searched fine while every stream answered "The page needs to be reloaded". If
+YouTube playback stops working and search does not, bump that version first.
+
**`vergen` is pinned to 9.0.6.** `librespot-core` 0.8.0's build script does not
-compile against 9.1.0 — a semver-compatible bump that changed the `Add` trait.
+compile against 9.1.0, a semver-compatible bump that changed the `Add` trait.
The pin lives in `native/Cargo.lock`.
**Token refresh is serialised.** `TokenStore.validAccessToken()` takes a mutex
@@ -169,7 +211,10 @@ is already dead. It is the bug behind the random logouts in most other clients.
| Project | Licence | How it is used |
| --- | --- | --- |
-| [librespot](https://github.com/librespot-org/librespot) | MIT | The engine. `librespot-core` is vendored with local patches. |
+| [librespot](https://github.com/librespot-org/librespot) | MIT | The Spotify engine. `librespot-core` is vendored with local patches. |
+| [Metrolist](https://github.com/mostafaalagamy/Metrolist) | GPL-3.0 | Its InnerTube client, vendored as [`innertube/`](innertube/), because it is published nowhere else. Powers the signed-in YouTube Music library. |
+| [NewPipeExtractor](https://github.com/TeamNewPipe/NewPipeExtractor) | GPL-3.0 | Anonymous YouTube Music search and stream URLs. |
+| [LrcLib](https://lrclib.net) | n/a | Synced lyrics for the YouTube Music backend, over its open API. |
| [Bungee](https://github.com/kupix/bungee) | MPL-2.0 | Time stretching, fetched at build time. |
| [AndroidLiquidGlass](https://github.com/Kyant0/AndroidLiquidGlass) | Apache-2.0 | The glass material; the catalog components are copied with their notice. |
| [Phosphor Icons](https://phosphoricons.com) | MIT | Every icon in the app. |
diff --git a/docs/social-preview.png b/docs/social-preview.png
index ab8af9b..cf99cb7 100644
Binary files a/docs/social-preview.png and b/docs/social-preview.png differ
diff --git a/tools/social-preview.py b/tools/social-preview.py
new file mode 100644
index 0000000..f59c11b
--- /dev/null
+++ b/tools/social-preview.py
@@ -0,0 +1,90 @@
+"""Repaints the left panel of docs/social-preview.png with new copy.
+
+The wordmark is not typeset: it is the same drawing the app puts in its own
+header (`ui/components/Wordmark.kt`) — polylines on a 6x10 grid, orthogonal
+segments only, square caps and miter joins. Kept as a port rather than a font
+so the two cannot drift.
+"""
+
+from PIL import Image, ImageDraw, ImageFont
+
+BG = (16, 16, 18)
+INK = (247, 248, 250) # theme Ink
+SUB = (150, 150, 158)
+FOOT = (110, 110, 118)
+
+SRC = "docs/social-preview.png"
+OUT = "docs/social-preview.png"
+PANEL = 833 # where the phone screenshot starts
+
+HELV = "/System/Library/Fonts/HelveticaNeue.ttc"
+
+# S Q U A R E, straight from GLYPHS in Wordmark.kt.
+GLYPHS = [
+ [[(6, 0), (0, 0), (0, 5), (6, 5), (6, 10), (0, 10)]],
+ [[(0, 0), (6, 0), (6, 10), (0, 10), (0, 0)], [(4, 8), (4, 12)]],
+ [[(0, 0), (0, 10), (6, 10), (6, 0)]],
+ [[(0, 10), (0, 0), (6, 0), (6, 10)], [(0, 6), (6, 6)]],
+ [[(0, 10), (0, 0), (6, 0), (6, 5), (0, 5)], [(3, 5), (3, 10)]],
+ [[(6, 0), (0, 0), (0, 10), (6, 10)], [(0, 5), (4, 5)]],
+]
+ADVANCE = 9.5 # units between glyph origins
+BOX = 12.0 # units of the wordmark's own height
+
+
+def draw_wordmark(im, x, y, height, color, scale=4):
+ """Draws the wordmark with its top-left at (x, y), `height` units tall.
+
+ Every segment is axis-aligned, so a segment is drawn as its bounding box
+ grown by half a stroke on all sides: that gives the square caps at the ends
+ of a polyline and fills the right-angle miter at every join, which is what
+ Compose's Stroke(cap=Square, join=Miter) produces.
+ """
+ unit = height / BOX * scale
+ stroke = unit * 1.15
+ half = stroke / 2
+
+ w = int(ADVANCE * len(GLYPHS) * unit + stroke)
+ h = int(BOX * unit + stroke)
+ layer = Image.new("L", (w, h), 0)
+ d = ImageDraw.Draw(layer)
+
+ for i, glyph in enumerate(GLYPHS):
+ origin = i * ADVANCE * unit + half
+ for line in glyph:
+ for (ax, ay), (bx, by) in zip(line, line[1:]):
+ x0, x1 = sorted((origin + ax * unit, origin + bx * unit))
+ y0, y1 = sorted((ay * unit + half, by * unit + half))
+ d.rectangle([x0 - half, y0 - half, x1 + half, y1 + half], fill=255)
+
+ mask = layer.resize((w // scale, h // scale), Image.LANCZOS)
+ im.paste(Image.new("RGB", mask.size, color), (int(x), int(y)), mask)
+
+
+im = Image.open(SRC).convert("RGB")
+d = ImageDraw.Draw(im)
+d.rectangle([0, 0, PANEL - 1, im.height], fill=BG)
+
+# The icon, same place and size as before.
+icon = Image.open("docs/square.png").convert("RGBA").resize((130, 130), Image.LANCZOS)
+im.paste(icon, (85, 97), icon)
+
+# Cap height 54, matching the Helvetica wordmark this replaces.
+draw_wordmark(im, 85, 272, height=54 / 10 * BOX, color=INK)
+
+f_sub = ImageFont.truetype(HELV, 31, index=0)
+f_foot = ImageFont.truetype(HELV, 23, index=0)
+
+d.text((85, 372), "Spotify and YouTube Music", font=f_sub, fill=SUB)
+d.text((85, 416), "on Android, in Liquid Glass.", font=f_sub, fill=SUB)
+
+x = 85
+for i, part in enumerate(["Two sources", "Audio effects", "Video mode"]):
+ if i:
+ d.text((x, 500), "·", font=f_foot, fill=FOOT)
+ x += d.textlength("·", font=f_foot) + 22
+ d.text((x, 500), part, font=f_foot, fill=FOOT)
+ x += d.textlength(part, font=f_foot) + 22
+
+im.save(OUT)
+print("wrote", OUT, im.size)