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.

A README for people who want to use the app

Lelonio3640c60659b1
diff --git a/README.md b/README.md
index 93883bf..a59d684 100644
--- a/README.md
+++ b/README.md
@@ -9,220 +9,180 @@
built in Liquid Glass.
</p>
-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 apps
-
-**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
-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
-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.** 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 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 the TTML archive at
- [lossless.wtf](https://lossless.wtf) first — timed to the word, the format
- Apple Music ships — and from Spotify or [LrcLib](https://lrclib.net) for
- everything it does not carry; 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
- beside, so a sideloaded build needs "Unknown sources" turned on in Android
- Auto's developer settings.
-- **Six languages.** English, Italian, Spanish, French, German, Portuguese, and
- a picker that does not depend on the phone's own language.
-
-## Architecture
+<p align="center">
+ <a href="https://github.com/Lelonio/Square/releases/latest"><img src="https://img.shields.io/github/v/release/Lelonio/Square?label=release" alt="Latest release"></a>
+ <a href="https://github.com/Lelonio/Square/releases"><img src="https://img.shields.io/github/downloads/Lelonio/Square/total" alt="Downloads"></a>
+ <img src="https://img.shields.io/badge/Android-8.0%2B-3DDC84" alt="Android 8.0 or later">
+ <a href="LICENSE"><img src="https://img.shields.io/github/license/Lelonio/Square" alt="Licence"></a>
+</p>
-```
-┌───────────────────────────────────────────────────────────┐
-│ 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 │
-└─────────────────┴────────┴──────────────────┴─────────────┘
-```
+<p align="center">
+ <a href="#download"><b>Download</b></a> ·
+ <a href="#features"><b>Features</b></a> ·
+ <a href="#first-launch"><b>First launch</b></a> ·
+ <a href="#faq"><b>FAQ</b></a> ·
+ <a href="docs/DEVELOPMENT.md"><b>Building</b></a>
+</p>
-`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.
+| Player | Lyrics | Effects |
+| :---: | :---: | :---: |
+| ![The player](docs/screenshots/player.png) | ![Synced lyrics](docs/screenshots/lyrics.png) | ![The effects panel](docs/screenshots/effects.png) |
+| **Artist** | **Album** | **Glass settings** |
+| ![An artist's page](docs/screenshots/artist.png) | ![An album](docs/screenshots/album.png) | ![The glass settings](docs/screenshots/glass.png) |
-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.
+## Features
-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.
+### Two sources, one app
-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
-ahead of the audio.
+- **Spotify or YouTube Music**, chosen at first launch and switchable in the
+ settings. Home, search, the library and the player work the same on both.
+- **Spotify**: your own account, with its playlists, library and Connect
+ devices. Needs Premium.
+- **YouTube Music**: the whole catalogue and the music videos, with no account
+ needed. Sign in with Google to bring in your playlists, albums and followed
+ artists.
-## Building
+### Player
-Requirements:
+- The cover or the song's looping canvas video behind the controls.
+- Music videos: switch from the song to its video in place, without losing the
+ queue or the position, and keep watching in picture-in-picture.
+- Radio from any song, and autoplay of similar songs when the queue ends.
+- Crossfade between songs, with an option to skip trailing silence.
+- Sleep timer: after 5 to 60 minutes or at the end of the song, fading out
+ before it stops.
-- Android Studio with SDK platform 35 and **NDK 28.2.13676358**
-- Rust ≥ 1.86 with the Android targets
-- `cargo-ndk`
+### Audio effects
-```bash
-rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
-cargo install cargo-ndk
-sdkmanager --install "ndk;28.2.13676358"
-```
+- Speed and pitch, each on its own, plus reverb.
+- Presets, so "slowed + reverb" is one tap on any song.
+- Karaoke: turn the voice down.
+- Streaming quality that follows the connection, or a fixed one.
-Then:
+### Lyrics
-```bash
-./gradlew :app:assembleDebug
-```
+- Synced lyrics, word by word where they exist and line by line otherwise.
+- Translation into your language, under the original lines.
+
+### Library and discovery
+
+- Playlists, albums, artists and liked songs. Create, rename and delete
+ playlists, add and remove songs, pin favourites, follow artists.
+- A home page of shelves made for you, a **New** tab with releases and charts,
+ and a **Radio** tab of stations, moods and genres.
+- Search, with your recent searches kept (swipe one away to remove it).
+- The music already on your phone, in a Local files shelf.
+
+### Offline
+
+- Download playlists, albums and songs, from either source. A song kept by two
+ playlists is downloaded once.
+- Downloads over Wi-Fi only, and automatic downloads of your liked songs.
+- Offline mode: play only what is on the phone.
+
+### Spotify extras
+
+- A **Connect** device: send playback to Square from any other device, and
+ control your other devices from it.
+- What your friends are listening to.
+- Similar playlists at the end of each playlist.
+- Song credits: performers, writers and producers.
+- What you play is saved to your listening history, as it would be anywhere
+ else you listen.
+- Spotify links can open straight in Square.
+
+### Android Auto
-The `cargoBuild` task cross-compiles the core and copies the `.so` files into
-`app/src/main/jniLibs`. To iterate faster, cut `nativeAbis` in
-`app/build.gradle.kts` down to `arm64-v8a`.
+- Browse playlists and recently played, search by voice, like a song or start a
+ radio from the car.
-### Signing a release build
+### Look and language
-The release build is signed with a real key when `keystore.properties` exists
-beside the project, and with the debug key otherwise. The file and the keystore
-are both ignored by git and must stay that way.
+- Every control, the tab bar, the player, the sheets and the menus are made of
+ one refracting glass. Blur, refraction and tint are adjustable, with a lighter
+ mode for slower phones.
+- Eight languages: English, Italian, Spanish, French, German, Portuguese, Hindi
+ and Turkish, chosen independently of the phone's own.
+
+## Download
+
+Download the APK from the [latest release](https://github.com/Lelonio/Square/releases/latest)
+and install it. Square needs Android 8.0 or later.
+
+Square updates itself: it checks for new releases and installs them from the
+settings. It is not on the Play Store and cannot be; see the
+[disclaimer](#disclaimer).
+
+<details>
+<summary><b>The first minutes after installing are slower</b></summary>
+
+Android takes a while to optimise a freshly installed app, and until it does
+the interface is noticeably slower. To do it straight away, open the app once
+and give it a few seconds, then run this with the phone connected:
```bash
-keytool -genkey -v -keystore square-release.jks -keyalg RSA \
- -keysize 2048 -validity 10000 -alias square
+adb shell cmd package compile -m speed-profile -f dev.lelonio.square
```
-```properties
-# keystore.properties, never commit this
-storeFile=square-release.jks
-storePassword=…
-keyAlias=square
-keyPassword=…
-```
+Run before the app has been opened, the command finds nothing to compile.
+
+</details>
+
+## First launch
+
+Square first asks where the music should come from. You can change it later in
+the settings.
-## Notes for anyone reading the code
-
-**`librespot-core` is patched.** A local copy under `native/vendor/`, wired in
-with `[patch.crates-io]`. Four changes: the advertised OS is pinned to
-`"linux"` so it agrees with the desktop client id, Mercury gained POST and
-header fields so listening events can be posted, the session carries a language
-so artwork comes back in it, and a non-premium account no longer exits the
-process. All four are explained in
-[native/vendor/README.md](native/vendor/README.md).
-
-**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
-`InetAddress.getLoopbackAddress()` answers `::1` and the browser then fails the
-redirect with `ERR_CONNECTION_REFUSED`.
-
-**`MediaSession.Callback` is not optional.** A session never hands a
-controller's `MediaItem`s to the player directly; it asks the app to resolve
-them first, and the default implementation rejects every item without a
-playable URI. Ours carry only a `mediaId`, so without `onAddMediaItems` the call
-vanishes silently.
-
-**Do not rebuild the playlist in `getState()`.** It runs on every
-`invalidateState`, which includes each position update: rebuilding dozens of
-`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.
-The pin lives in `native/Cargo.lock`.
-
-**Token refresh is serialised.** `TokenStore.validAccessToken()` takes a mutex
-before refreshing. Spotify rotates refresh tokens, so without it two parallel
-requests around expiry would each refresh and the loser would save a token that
-is already dead. It is the bug behind the random logouts in most other clients.
-
-## Third-party code
+- **YouTube Music** plays straight away. Signing in with Google, from the
+ settings, is optional.
+- **Spotify** needs a Premium account and a few minutes of guided setup: you
+ sign in, then register a free app of your own in Spotify's developer
+ dashboard and paste its client ID. Search and a few other features go
+ through Spotify's Web API, which limits requests per app, so with your own
+ app the limit is yours alone. The setup walks you through every step.
+
+## FAQ
+
+**Square does not appear in Android Auto.**
+Android Auto only lists apps installed from the Play Store. Turn on "Unknown
+sources" in Android Auto's developer settings and Square shows up.
+
+**Can I use a free Spotify account?**
+No. A free account can sign in, but Spotify only streams to a client like this
+one with Premium. YouTube Music works with no account at all.
+
+**YouTube Music search works, but songs do not play.**
+YouTube changes how its streams are served every so often. Update to the
+latest release, which is usually where the fix is.
+
+## Disclaimer
+
+Square is not affiliated with, endorsed by or connected to Spotify or Google.
+Both sources are used on terms they do not offer: Square re-implements
+Spotify's protocol, which Spotify's Terms of Service forbid, and reads YouTube
+Music through the private endpoints its own web client uses. It cannot be
+published on the Play Store, and you use it at your own risk. There is no
+warranty of any kind; see the licence.
+
+## Credits
| Project | Licence | How it is used |
| --- | --- | --- |
| [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. |
-| [lossless.wtf](https://lossless.wtf) | n/a | Synced TTML lyrics, asked first on both backends. |
-| [LrcLib](https://lrclib.net) | n/a | Synced lyrics for the YouTube Music backend, over its open API. |
+| [lossless.wtf](https://lossless.wtf) | n/a | Synced lyrics timed to the word, asked first on both sources. |
+| [LrcLib](https://lrclib.net) | n/a | Synced lyrics for the YouTube Music source, 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. |
| librespot-java | Apache-2.0 | The listening-event format, re-implemented from its `EventService` rather than copied. |
+## Building from source
+
+Requirements, build steps, signing, the architecture and notes on the code are
+in [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).
+
## Licence
GPL-3.0-or-later. See [LICENSE](LICENSE).
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..8bd8d04
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,141 @@
+# Developing Square
+
+Everything about building Square and finding your way around its code. For
+what the app does and how to install it, see the [README](../README.md).
+
+- [Architecture](#architecture)
+- [Building](#building)
+- [Signing a release build](#signing-a-release-build)
+- [Notes for anyone reading the code](#notes-for-anyone-reading-the-code)
+
+## Architecture
+
+```
+┌───────────────────────────────────────────────────────────┐
+│ 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 │
+└─────────────────┴────────┴──────────────────┴─────────────┘
+```
+
+Spotify plays through [librespot](https://github.com/librespot-org/librespot):
+audio is streamed in-process by a native Rust core, reached over JNI. YouTube
+Music plays through ExoPlayer.
+
+`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
+ahead of the audio.
+
+## Building
+
+Requirements:
+
+- Android Studio with SDK platform 35 and **NDK 28.2.13676358**
+- Rust ≥ 1.86 with the Android targets
+- `cargo-ndk`
+
+```bash
+rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
+cargo install cargo-ndk
+sdkmanager --install "ndk;28.2.13676358"
+```
+
+Then:
+
+```bash
+./gradlew :app:assembleDebug
+```
+
+The `cargoBuild` task cross-compiles the core and copies the `.so` files into
+`app/src/main/jniLibs`. To iterate faster, cut `nativeAbis` in
+`app/build.gradle.kts` down to `arm64-v8a`.
+
+## Signing a release build
+
+The release build is signed with a real key when `keystore.properties` exists
+beside the project, and with the debug key otherwise. The file and the keystore
+are both ignored by git and must stay that way.
+
+```bash
+keytool -genkey -v -keystore square-release.jks -keyalg RSA \
+ -keysize 2048 -validity 10000 -alias square
+```
+
+```properties
+# keystore.properties, never commit this
+storeFile=square-release.jks
+storePassword=…
+keyAlias=square
+keyPassword=…
+```
+
+## Notes for anyone reading the code
+
+**`librespot-core` is patched.** A local copy under `native/vendor/`, wired in
+with `[patch.crates-io]`. Four changes: the advertised OS is pinned to
+`"linux"` so it agrees with the desktop client id, Mercury gained POST and
+header fields so listening events can be posted, the session carries a language
+so artwork comes back in it, and a non-premium account no longer exits the
+process. All four are explained in
+[native/vendor/README.md](../native/vendor/README.md).
+
+**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
+`InetAddress.getLoopbackAddress()` answers `::1` and the browser then fails the
+redirect with `ERR_CONNECTION_REFUSED`.
+
+**`MediaSession.Callback` is not optional.** A session never hands a
+controller's `MediaItem`s to the player directly; it asks the app to resolve
+them first, and the default implementation rejects every item without a
+playable URI. Ours carry only a `mediaId`, so without `onAddMediaItems` the call
+vanishes silently.
+
+**Do not rebuild the playlist in `getState()`.** It runs on every
+`invalidateState`, which includes each position update: rebuilding dozens of
+`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.
+The pin lives in `native/Cargo.lock`.
+
+**Token refresh is serialised.** `TokenStore.validAccessToken()` takes a mutex
+before refreshing. Spotify rotates refresh tokens, so without it two parallel
+requests around expiry would each refresh and the loser would save a token that
+is already dead. It is the bug behind the random logouts in most other clients.
diff --git a/docs/screenshots/album.png b/docs/screenshots/album.png
new file mode 100644
index 0000000..081c6b9
Binary files /dev/null and b/docs/screenshots/album.png differ
diff --git a/docs/screenshots/artist.png b/docs/screenshots/artist.png
new file mode 100644
index 0000000..0892a4d
Binary files /dev/null and b/docs/screenshots/artist.png differ
diff --git a/docs/screenshots/effects.png b/docs/screenshots/effects.png
index f427419..05046cc 100644
Binary files a/docs/screenshots/effects.png and b/docs/screenshots/effects.png differ
diff --git a/docs/screenshots/glass.png b/docs/screenshots/glass.png
new file mode 100644
index 0000000..8365b2b
Binary files /dev/null and b/docs/screenshots/glass.png differ
diff --git a/docs/screenshots/home.png b/docs/screenshots/home.png
deleted file mode 100644
index e2b2a00..0000000
Binary files a/docs/screenshots/home.png and /dev/null differ
diff --git a/docs/screenshots/lyrics.png b/docs/screenshots/lyrics.png
new file mode 100644
index 0000000..4bc6a7a
Binary files /dev/null and b/docs/screenshots/lyrics.png differ
diff --git a/docs/screenshots/player.png b/docs/screenshots/player.png
index b874fcf..9a6fba5 100644
Binary files a/docs/screenshots/player.png and b/docs/screenshots/player.png differ