CI / build (push) Successful in 1m56s
The mood screen now shows recommendation cards with thumbnails, a refresh action, and accept/reject buttons. Accepting a library match adds it as a seed immediately; other accepted tracks are marked as queued for download. The player persists the session, queue and current track, restores them paused on the next launch and starts the track on the next tap. While offline the store retries the library sync with exponential backoff, downloads retry three times before failing, and covers plus YT thumbnails are cached for the app's lifetime.
145 lines
8.1 KiB
Markdown
145 lines
8.1 KiB
Markdown
# AudioManager Client
|
|
|
|
Kotlin Multiplatform client for [AudioManager](../AudioManager) — a mood-first, self-hosted music server.
|
|
|
|
The client and server are designed together. There is no OpenSubsonic compatibility layer: the app speaks the native `/api/v1` API, where playback is a server-driven radio session and "likes" are replaced by explicit **add to mood** actions.
|
|
|
|
## Targets
|
|
|
|
| Target | UI | Playback | Offline downloads |
|
|
| --- | --- | --- | --- |
|
|
| **Android** | Compose Multiplatform | Media3 / ExoPlayer | Yes |
|
|
| **Desktop (JVM)** | Compose Multiplatform | MP3SPI, decoded to PCM + `SourceDataLine` | Yes |
|
|
| **Web (Wasm)** | Compose Multiplatform | HTML5 `Audio` | Browser-managed cache only |
|
|
|
|
The shared module contains the API client, session/cache storage, radio queue, app state and all screens. Platform code is limited to HTTP engines, storage, audio and back handling.
|
|
|
|
## Features
|
|
|
|
- Login with a server URL, username and password. The server returns a revocable bearer token.
|
|
- Mood grid with live counts; create, rename, delete and edit moods.
|
|
- Seed management: search the owner's music, add or remove anchors.
|
|
- Server-driven radio: the app keeps a small queue and asks for more from the same mood session.
|
|
- Playback events are reported automatically (`started`, `completed`, `skipped`) so the server learns.
|
|
- Two add-to-mood actions in the player:
|
|
- **Add to current mood** (the mood of the active radio session)
|
|
- **Choose another mood** (picker)
|
|
- YT Music recommendations in the mood editor: refresh on demand, accept or reject candidates, thumbnails, and a clear state for library matches (`Seed added`), accepted-for-download tracks and new picks. Accepting a track the library already has adds it as a seed immediately.
|
|
- Library search and playback, plus **Shuffle all** to queue the whole library without starting a mood.
|
|
- **Sleep timer** (15/30/45/60/90 minutes) that pauses playback. On Android the pause is scheduled inside the media service, so it still fires when the app is backgrounded or the task is swiped away.
|
|
- Offline library cache: moods, songs and the last sync revision are stored locally. When the server is unreachable, downloaded tracks still play.
|
|
- The play queue and current track are saved locally, so a restart reopens the player paused and resumes on the next tap.
|
|
- Reconnects automatically with exponential backoff (15s to 5min) while offline.
|
|
- Downloads retry up to three times before reporting an error; covers and YT thumbnails are cached for the app's lifetime.
|
|
- Original MP3 downloads with progress state, removal and storage usage.
|
|
- Session persistence: the login survives app restarts until the token is revoked or expires.
|
|
- Android background playback through a Media3 `MediaSessionService`: notification, lock-screen and headset controls, audio focus, and playback that survives the app being backgrounded or the task being swiped away.
|
|
|
|
## Project layout
|
|
|
|
```text
|
|
composeApp/
|
|
|-- src/commonMain/kotlin/win/taptap/musicmanager/client/
|
|
| |-- api/ # Ktor client and DTOs mirroring /api/v1
|
|
| |-- data/ # AppStorage, LibraryCache, session persistence
|
|
| |-- playback/ # AudioPlayer abstraction
|
|
| |-- store/ # AppStore: state, radio queue, downloads, editing
|
|
| `-- ui/ # Compose screens and theme
|
|
|-- src/androidMain/ # Activity, Media3 player, filesystem storage
|
|
|-- src/desktopMain/ # Main window, MP3SPI player, filesystem storage
|
|
|-- src/wasmJsMain/ # Compose viewport, HTML audio, localStorage
|
|
|-- src/commonTest/ # API, cache and store tests
|
|
|-- src/desktopTest/ # MP3 decoding and PCM conversion tests
|
|
`-- ci/ # Android SDK CI image
|
|
```
|
|
|
|
## Build
|
|
|
|
Requirements: JDK 21, Android SDK 35 for the app target, Node (Kotlin downloads its own for web).
|
|
|
|
With Nix, everything is provided by `shell.nix` (JDK 21, Gradle 8, Node 22, Android SDK 35 with build-tools 35.0.0, and the desktop runtime libraries):
|
|
|
|
```bash
|
|
nix-shell
|
|
```
|
|
|
|
The shell accepts the unfree Android SDK license for you; see the comment at the top of `shell.nix`. Without Nix, point `ANDROID_HOME` at an SDK containing platform 35 and build-tools 35.0.0.
|
|
|
|
```bash
|
|
export ANDROID_HOME=/opt/android-sdk
|
|
|
|
# Unit tests (JVM)
|
|
gradle :composeApp:desktopTest
|
|
|
|
# Android debug APK
|
|
gradle :composeApp:assembleDebug
|
|
# composeApp/build/outputs/apk/debug/composeApp-debug.apk
|
|
|
|
# Desktop application (run)
|
|
gradle :composeApp:run
|
|
|
|
# Desktop fat jar
|
|
gradle :composeApp:packageUberJarForCurrentOS
|
|
|
|
# Web bundle
|
|
gradle :composeApp:wasmJsBrowserDistribution
|
|
# composeApp/build/dist/wasmJs/productionExecutable
|
|
```
|
|
|
|
Serve the web bundle from any static host (for example `python3 -m http.server` inside the production directory). The server allows cross-origin API calls; enter its URL on the login screen. When the bundle is hosted on the same origin as the server, the URL is prefilled.
|
|
|
|
Android cleartext HTTP is enabled for local development. Use HTTPS in production.
|
|
|
|
## App state and offline behaviour
|
|
|
|
`AppStore` is a plain Kotlin class with a `StateFlow<AppState>`; Compose observes it. It owns:
|
|
|
|
- **Auth** — restore token, refresh token, logout.
|
|
- **Library sync** — first launch pages through `/library/songs`; later launches use the `since` delta and tombstones.
|
|
- **Mood cache** — mood details are stored so the app can open them offline.
|
|
- **Radio** — one session per mood, batches of 12, prefetch when the queue is short, no repeats within a session.
|
|
- **Downloads** — stored under the platform app directory, keyed by deterministic song ID.
|
|
- **Playback snapshot** — the session, upcoming queue and current track are persisted on every queue change and restored on the next launch.
|
|
- **Offline retry** — a background loop retries the library sync until the server responds again.
|
|
|
|
On startup the app is usable before the network call completes: cached moods and library render immediately, then refresh in the background.
|
|
|
|
## Radio and add-to-mood
|
|
|
|
```text
|
|
open mood ──► POST /moods/{id}/sessions ──► queue (12 tracks)
|
|
│
|
|
├─ track start ──► POST /sessions/{id}/events {type=started}
|
|
├─ track end ──► {type=completed} ──► next batch
|
|
├─ skip ──► {type=skipped} ──► next batch
|
|
└─ add ──► POST /sessions/{id}/add-to-mood
|
|
├─ no moodId: current mood
|
|
└─ moodId: chosen mood
|
|
```
|
|
|
|
Adding a song makes it a permanent seed, so it is always eligible in future radio and visible in the mood editor.
|
|
|
|
## CI and releases
|
|
|
|
`.gitea/workflows/ci.yaml` runs on Gitea Actions using `gitea.tap-tap.win/taptap/audiomanager-client-ci:3`. The image has the Android SDK, Node, Yarn and a warmed Gradle dependency cache, so jobs do not download them on every run.
|
|
|
|
- **main / PR:** run `desktopTest`, build the Android APK and the *development* Wasm bundle. The optimized Wasm build is CPU-bound and reserved for releases.
|
|
- **`v*` tag:** additionally build the desktop fat jar and the optimized Wasm bundle, then attach all three to the Gitea release.
|
|
|
|
Rebuild the CI image after changing `ci/Dockerfile` or dependency versions:
|
|
|
|
```bash
|
|
scripts/build-ci-image.sh 3
|
|
```
|
|
|
|
The image build performs one warm-up compile (`kotlinNodeJsSetup`, `kotlinYarnSetup`, `desktopTest`, `assembleDebug`, `compileKotlinWasmJs`) and then removes the sources, keeping only `/root/.gradle`.
|
|
|
|
## Known limitations
|
|
|
|
- The media notification exposes play/pause and seeking. Queue actions (skip, add to mood) stay in the app because the mood session and its events belong to the server.
|
|
- Desktop playback cannot seek (sequential decoder); pause/resume and skipping work. MP3s are decoded to 16-bit PCM before the line is opened, because Java Sound has no line for the compressed format.
|
|
- Web downloads are disabled because the browser owns its storage; the app still streams and caches metadata.
|
|
- Accepted recommendations that are not in the library wait for the server-side downloader before they can be played.
|
|
- YT Music discovery runs server-side through `yt-dlp`; downloading accepted tracks that are not in the library is still roadmap.
|
|
- No iOS target yet. The shared module is ready for one.
|