TapTap 3281e46104
CI / test (push) Successful in 2m0s
CI / build (push) Successful in 13m27s
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.
2026-11-14 18:24:06 +00:00

AudioManager Client

Kotlin Multiplatform client for 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

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).

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

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:

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.
S
Description
No description provided
Readme
997 KiB
0 Stars 1 Watchers 0 Forks
2026-11-20 14:54:37 +01:00
Languages
Kotlin 97.7%
Shell 1%
Dockerfile 0.6%
Nix 0.5%
HTML 0.2%