Unofficial YouTube Music / Spotify Premium client for Android, built in Liquid Glass. Audio effects, Spotify Connect, listening history, 8 languages. Rust core on librespot.
Kotlin alternativeandroidandroid-applicationclientglassmorphisminnertubelibrespotliquid-glassspotifyspotify-connectspotifyapiyoutube-musicyoutube-playerytdlnis
A README for people who want to use the app
Lelonio3640c60659b1
diff --git a/README.md b/README.mdindex 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 |-| --- | --- | --- |-|  |  |  |--## 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 |+| :---: | :---: | :---: |+|  |  |  |+| **Artist** | **Album** | **Glass settings** |+|  |  |  |-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).+## LicenceGPL-3.0-or-later. See [LICENSE](LICENSE).diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.mdnew file mode 100644index 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.pngnew file mode 100644index 0000000..081c6b9Binary files /dev/null and b/docs/screenshots/album.png differdiff --git a/docs/screenshots/artist.png b/docs/screenshots/artist.pngnew file mode 100644index 0000000..0892a4dBinary files /dev/null and b/docs/screenshots/artist.png differdiff --git a/docs/screenshots/effects.png b/docs/screenshots/effects.pngindex f427419..05046cc 100644Binary files a/docs/screenshots/effects.png and b/docs/screenshots/effects.png differdiff --git a/docs/screenshots/glass.png b/docs/screenshots/glass.pngnew file mode 100644index 0000000..8365b2bBinary files /dev/null and b/docs/screenshots/glass.png differdiff --git a/docs/screenshots/home.png b/docs/screenshots/home.pngdeleted file mode 100644index e2b2a00..0000000Binary files a/docs/screenshots/home.png and /dev/null differdiff --git a/docs/screenshots/lyrics.png b/docs/screenshots/lyrics.pngnew file mode 100644index 0000000..4bc6a7aBinary files /dev/null and b/docs/screenshots/lyrics.png differdiff --git a/docs/screenshots/player.png b/docs/screenshots/player.pngindex b874fcf..9a6fba5 100644Binary files a/docs/screenshots/player.png and b/docs/screenshots/player.png differ