While a track plays, the window keeps the screen on so the system saver never starts. After the system's screen saver delay without input, the app shows its own: the album cover and the artist's photos (from brief-info's allCovers) crossfade and slowly zoom, under the artist, song, album and year and a thin progress line. The caption switches sides with each photo so nothing stays still on the panel. The key that wakes the saver does nothing else; media and volume keys still act. Paused for ten minutes, with nothing queued, or with a dialog open, the app lets go and the system saver and sleep return. Tracks now carry the album year and each artist's photo. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
111 lines
5.7 KiB
Markdown
111 lines
5.7 KiB
Markdown
# 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. 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`).
|