Files
musyz-mobile/README.md
T
yuriy.pandClaude Opus 5.5 81fce4a335 Fall back to LRCLIB for lyrics Yandex doesn't have
When Yandex answers "no lyrics" for a track, the lyrics tab now asks
LRCLIB (lrclib.net), an open lyrics database that needs no key. The
exact match by title, artist, album and length comes first; when that
is plain text, or missing, search picks a synced copy of the same
recording (within 3 s of its length). Speech and instrumentals get none.

- LRCLIB's /get answers 503 "ServerOverloaded" now and then: busy
  answers are retried twice, briefly, and a busy /get falls through to
  search.
- LRCLIB errors never map to Unauthorized, so they can't sign the user
  out of Yandex.
- Lyrics from LRCLIB carry a "Lyrics from LRCLIB" credit at the end of
  the list, and the empty state no longer blames Yandex alone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-19 12:04:50 +06:00

112 lines
5.7 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Musyx Mobile
An Android TV player for Yandex Music, written in Kotlin with Jetpack Compose for TV and
Media3. It is the TV companion to the desktop [Musyx](../musyx) (Rust, iced), and follows the
same design.
Musyx is an unofficial client. It talks to the same undocumented API the official apps use,
and it isn't affiliated with or endorsed by Yandex.
## What it does
Everything the desktop app does, laid out for a remote: device-code sign-in with a QR for
your phone (or a pasted token), Home (My Wave, recently played, personal playlists, the
chart, new releases, genres), My Wave with its mood, character and language settings and
other stations, search with suggestions and paged results, Collection (liked tracks,
albums, artists, playlists, clips), album, artist, playlist, genre and podcast pages, and a
Now Playing screen with the queue and synced lyrics (from [LRCLIB](https://lrclib.net) when
Yandex has none). Tracks can be liked, disliked, queued
next or last, added to playlists, and used to start similar tracks; your own playlists can
be created, renamed, made public or private, reordered and deleted. Playback runs in a media
session, so it keeps going in the background and answers the remote's media keys. While
music plays, the TV's own screen saver is replaced by one that drifts through the artist's
photos and the cover with the artist, song, album and year (after the system's screen saver
delay; paused for ten minutes or with nothing queued, the system's saver returns). Streaming
quality goes up to FLAC (decrypted on the fly), and the interface is in English or Russian.
Hold select on a track row or a clip for its menu; the heart and the "more" button sit to
the right of each row.
## Stack
- Kotlin, Jetpack Compose with `androidx.tv:tv-material` for the D-pad UI.
- Media3 (ExoPlayer and `MediaSessionService`) for playback, background audio, the Now
Playing card and remote controls.
- OkHttp and kotlinx.serialization for the Yandex Music API.
- Android Keystore for the OAuth token.
- Coil for covers (memory and disk cache) and ZXing for the sign-in QR.
## Build and run
You need JDK 17 or newer (Android Studio's bundled JBR works) and the Android SDK with
platform 37. Point Gradle at the SDK with `sdk.dir` in `local.properties` (Android Studio
writes it) or `ANDROID_HOME`. The Gradle wrapper fetches everything else.
```bash
./gradlew assembleDebug
```
The APK lands in `app/build/outputs/apk/debug/app-debug.apk`. `./gradlew testDebugUnitTest`
runs the JVM tests (the queue and player rules, API parsing and request signing, lyrics,
decryption and theme parity, mostly ported from the desktop tests), and `./gradlew lint` runs Android
Lint, with the report in `app/build/reports/lint-results-debug.html`.
To run it, start an Android TV or Google TV emulator (Device Manager in Android Studio, TV
category) or connect a TV with ADB debugging on, then:
```bash
./gradlew installDebug
```
```bash
adb shell am start -n it.panov.musyx.tv/.MainActivity
```
The app shows up in the TV launcher under its banner. It also installs on phones and
tablets, since neither Leanback nor a touchscreen is required.
### Generated resources
The icons, banner and fonts in `app/src/main/res` come from `assets/`. Regenerate them after
changing the sources:
- `python3 tool/svg_to_vector.py` turns `assets/icons/*.svg` into `res/drawable/ic_<name>.xml`.
The drawables are white masks; code tints them with theme tokens.
- `python3 tool/make_tv_assets.py` draws the 320×180 TV banner (`drawable-xhdpi/banner.png`)
and scales `assets/icon/musyx.png` into the launcher mipmaps. It needs Pillow.
- `python3 tool/make_icon.py assets/icon/musyx.png` redraws the icon itself.
- The fonts are copied by hand from `assets/fonts` to `res/font` (lower-case names).
## Layout
- `app/`: the Android TV app (`it.panov.musyx.tv`), under `app/src/main/java/it/panov/musyx/tv`:
- `api/`: the Yandex Music client, ported from `reference/ym-api` with the `yamuse` wire
details inlined (`Transport.kt` headers and errors, `Auth.kt` device flow, `Signing.kt`).
- `player/`: `PlayerCore` (queue, repeat, waves, reports; a pure port of the desktop
player), `ExoEngine` (one ExoPlayer, with `AesCtrDataSource` for encrypted FLAC),
`PlaybackController` (runs the core's effects) and `PlaybackService` (the media session).
- `state/`: `AppState`, the port of the desktop `app.rs` and `app/edit.rs`, plus search,
sign-in and navigation state.
- `data/`: settings and the Keystore-encrypted credentials.
- `ui/`: the shell (drawer, mini player, dialogs, toasts), `screens/` and `components/`.
The theme is `ui/theme/Theme.kt`, a 1:1 port of `DESIGN.md`.
- `gradle/libs.versions.toml`: dependency versions.
- `DESIGN.md`: design tokens (colour, type, space, components), shared with the desktop app.
- `design/mockup.html`: the approved desktop mockup.
- `assets/fonts`: Onest and Unbounded (OFL). They go to `res/font` in the app.
- `assets/icons`: Lucide icons (ISC). They become vector drawables in the app.
- `assets/icon/musyx.png`: the app icon, drawn by `tool/make_icon.py`.
- `tool/`: scripts that generate the icon, banner and vector drawables.
- `reference/`: a read-only snapshot of the desktop sources at musyx `44f4a1f`, to port from.
Nothing here is built.
- `reference/ym-api`: the API client. It is the spec for the Kotlin client: endpoints,
device-flow sign-in and token refresh, `/get-file-info` signing, and the AES-CTR
decryption of lossless streams. `tests/live.rs` covers the live calls.
- `reference/musyx`: the desktop app. The queue and My Wave logic (`player/`), screens,
settings, and the Russian strings (`i18n/ru.rs`, for `values-ru/strings.xml`).
## Licences
Musyx Mobile is MIT. Onest and Unbounded are OFL (`assets/fonts`), and Lucide icons are ISC
(`assets/icons/LICENSE.txt`).