TapTap 43bd9629d3
CI / build (push) Successful in 2m1s
fix: harden playback, sync, downloads and mood state
Playback:
- Persist the playhead in the playback snapshot and resume from it; restored
  longform progress is no longer overwritten with 0 on first play.
- Previous compares elapsed playtime since the track start, so resuming at
  1:00:00 and pressing previous goes back instead of restarting the book.
- Auto-advance no longer overwrites completed=true with false, longform PUTs
  are serialized, and playing rows/search results resume saved positions.
- Pause cancels the 400 ms poll; seek errors are reported instead of crashing.

Sync and state:
- First-sync snapshots keep the first page revision; cached revisions are only
  trusted for the same server/user.
- Refresh re-reads /me, merges local and server longform progress by timestamp,
  replays newer local positions, and keeps cached longform after deltas.
- Logout cancels refresh jobs, suppresses late progress writes, clears after
  playback teardown, and closes the HTTP client on release.
- Failed/racing mood opens clear the previous mood; stale responses cannot
  replace a newer selection. Mood drafts survive background refreshes.

Downloads and storage:
- Stream downloads to a .part file and atomically rename on Android/desktop,
  with a download-specific timeout and no whole-file buffering.
- Cache writes are best-effort and atomic; blocked/full web storage no longer
  leaves the app on the splash screen or blocks playback.
- Artwork failures do not fail audio downloads; failed downloads refresh the
  download index.
- Android queues sleep-timer commands before the controller connects.

UI:
- Music search is wired, debounced and kept separate from mood search.
- Player bar respects navigation-bar insets and hides music-only mood actions
  for longform. Mood gradient handles Int.MIN_VALUE.
2026-11-15 18:18:30 +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, 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 (Queued, Downloading, Download failed with retry) and new picks. Accepting a track the library already has adds it as a seed immediately; the rest are downloaded by the server and promoted automatically.
  • Library search and playback, plus Shuffle all to queue the whole library without starting a mood.
  • A queue sheet from the player: the current track plus every upcoming track, with move up/down and remove. Changes are persisted locally.
  • Previous from the player: after two seconds of playback it restarts the current track; before that it restores the last played track. The track it leaves is put back at the front of the queue.
  • Scrubbing: the progress slider can be dragged on every platform. Android/web seek natively; desktop restarts the decoder at the requested position (timeOffset for remote streams, PCM skip for local files).
  • Seed mix per mood: a slider chooses the share of seeds vs recommendations for each generated batch. The server rolls the percentage for every queued track and falls back to the other pool when one runs out.
  • Longform tab for audiobooks and podcasts: per-artist read-only playlists, “Shuffle artist” for random episodes, a resume list with progress, and a separate search scope. Long-form never enters music search, Shuffle all, moods or radio.
  • 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

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

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.

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. Songs are split into music and longform using the folders assigned at login, so the two never mix client-side.
  • 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, current track and play history are persisted on every queue change and restored on the next launch.
  • Longform progress — position is saved locally and to /longform/progress while playing, on pause and on track changes; the resume list is fed from the server when online.
  • 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

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:

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 supports seeking by reopening the decoder at the requested position (server timeOffset for remote streams, PCM skipping for local files). Longform resume works there too. 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 are downloaded by the server into <music>/AudioManager Imports/<artist>/<title>/, with the YT thumbnail embedded as cover art, scanned and added as seeds. The per-track folder keeps covers distinct. The server needs outbound network access for this.
  • Offline downloads also store the 320 px cover next to the MP3 (<songId>.jpg), so the in-app cover and the Android notification artwork survive without the server. Deleting a download removes both files.
  • YT Music discovery and automatic downloads run server-side through yt-dlp. Accepted tracks that are not in the library are imported into AudioManager Imports with embedded cover art and promoted to seeds.
  • 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%