A shared Compose Multiplatform client for Android, desktop and web on the native mood-first API. - Bearer login with persisted, restorable sessions. - Mood grid and full editor (create, settings, seeds, delete). - Server-driven radio sessions with automatic started/completed/skipped events and prefetching. - Add to current mood or choose another mood from the player. - Library search, original MP3 downloads, offline playback of downloads. - Offline cache of moods, songs and the last sync revision. - Platform audio: Media3 on Android, MP3SPI on desktop, HTML audio on web. - Platform storage: filesystem on Android/desktop, localStorage on web. - Desktop tests for API parsing, errors and cache persistence. - Gitea CI image with Android SDK 35, build pipeline and tagged releases.
127 lines
5.6 KiB
Markdown
127 lines
5.6 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 + `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)
|
|
- Library search and playback.
|
|
- Offline library cache: moods, songs and the last sync revision are stored locally. When the server is unreachable, downloaded tracks still play.
|
|
- Original MP3 downloads with progress state, removal and storage usage.
|
|
- Session persistence: the login survives app restarts until the token is revoked or expires.
|
|
|
|
## 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 parsing and cache tests
|
|
`-- ci/ # Android SDK CI image
|
|
```
|
|
|
|
## Build
|
|
|
|
Requirements: JDK 21, Android SDK 35 for the app target, Node (Kotlin downloads its own for web).
|
|
|
|
```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.
|
|
|
|
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:1`:
|
|
|
|
1. `desktopTest` — shared API/cache tests.
|
|
2. Build Android APK, desktop fat jar and Wasm bundle.
|
|
3. Upload artifacts.
|
|
4. On a `v*` tag, attach the three artifacts to the Gitea release.
|
|
|
|
Rebuild the CI image after changing `ci/Dockerfile`:
|
|
|
|
```bash
|
|
scripts/build-ci-image.sh 2
|
|
```
|
|
|
|
## Known limitations
|
|
|
|
- Android playback runs inside the app process; a foreground `MediaSessionService` with a notification and lock-screen controls is the next step.
|
|
- Desktop playback cannot seek (sequential decoder); pause/resume and skipping work.
|
|
- Web downloads are disabled because the browser owns its storage; the app still streams and caches metadata.
|
|
- YT Music recommendations are displayed when the server provides them; discovery and downloading are server-side roadmap items.
|
|
- No iOS target yet. The shared module is ready for one.
|