feat: add the Kotlin Multiplatform AudioManager client
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.
This commit is contained in:
commit
3281e46104
40 files changed
+7021
No files matched your search
@@ -0,0 +1,126 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user