- 500-entry local ring buffer, immediate flush for warnings/errors - batch upload to POST /logs with device id, platform, version and session - redact tokens, Authorization headers and secrets before storage/upload - Android/desktop uncaught handlers persist a crash entry for the next launch - Settings diagnostics card with pending count, send now and clear - fall back cleanly when the server predates /logs - include X-Request-Id in API failure diagnostics; version 0.4.3
299 lines
13 KiB
Markdown
299 lines
13 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 songs are added from Deezer or YouTube Music.
|
||
|
||
## 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 |
|
||
|
||
## Features
|
||
|
||
- Login with a server URL, username and password. The server returns a revocable
|
||
bearer token.
|
||
- **Moods** are the only content model. Each user sees only their own moods.
|
||
- **Songs** belong to the mood's permanent collection. A mood needs at least one
|
||
song before it can play.
|
||
- **Search Deezer or YouTube Music** from inside a mood or globally with a mood
|
||
picker. Each mood has a **Download source** selector; search, recommendations
|
||
and downloads follow it. Tracks over 10 minutes are hidden. Results that are already downloaded are marked and
|
||
add instantly; other videos are queued for server-side download.
|
||
- **Paste a YouTube URL** to add a specific video.
|
||
- **Recommendations** are downloaded automatically and play in the radio without
|
||
being permanent. Rows show the download state with:
|
||
- Add to mood;
|
||
- Not interested (permanent for the mood);
|
||
- Retry for failed downloads.
|
||
- **Radio** mixes the collection and ready recommendations using the mood's
|
||
`collectionPercent`. 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.
|
||
- **Add to mood is one tap** in the bottom player and the full-screen player.
|
||
Choosing a different mood stays in the overflow/picker.
|
||
- A queue sheet from the player: the current track is pinned, upcoming tracks
|
||
can be reordered by **long-press and drag** or removed. 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.
|
||
- **Headset/Bluetooth next and previous** and the media notification's skip /
|
||
back buttons use the same queue rules as the in-app controls; they no longer
|
||
seek inside the single ExoPlayer item.
|
||
- The bottom player keeps the cover and title/artist readable on narrow phones.
|
||
Tapping it opens the **full-screen player**: large artwork, scrubber, transport,
|
||
add-to-mood, queue, sleep timer and Up next.
|
||
- **Audio consistency**: the server measures every track's integrated loudness
|
||
with ffmpeg and stores a gain (target `-16 LUFS`); the app applies it per
|
||
track. The player shows the source and bitrate, and settings explain when the
|
||
Deezer ARL is limited to 128 kbps.
|
||
- **Gapless playback** on Android with an optional 0–8 s fade between tracks.
|
||
- **Scrubbing**: the progress slider can be dragged on every platform. Android and
|
||
web seek natively; desktop restarts the decoder at the requested position.
|
||
- **Mood settings** live on their own screen: name, description, discovery hint,
|
||
genres, source, collection share, recommendations, refresh interval, a
|
||
**Keep this mood offline** switch, and Delete at the bottom.
|
||
- **Downloads** screen for device-side copies: play, delete, clear, storage
|
||
usage.
|
||
- **Diagnostics**: warnings, errors and crashes are kept in a 500-entry local
|
||
ring buffer and uploaded in batches (tokens and passwords are redacted). The
|
||
full-screen Settings screen shows the queue, last upload and a Send now action;
|
||
`scripts/logs.sh` on the server prints or clears stored entries.
|
||
- **Sleep timer** (15/30/45/60/90 minutes or **finish this track**) 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.
|
||
- Mood cache: moods and details are stored locally so the app opens instantly
|
||
and can show cached data offline.
|
||
- 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.
|
||
- 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.
|
||
|
||
## Screens
|
||
|
||
`Moods | Mood Detail | Mood settings | Search | Downloads | Settings | Now playing`
|
||
|
||
- **Moods** — grid with song and pick counts, create, global search.
|
||
- **Mood Detail** — songs, add music, recommendations, next batch, settings.
|
||
- **Search** — mood picker, source selector, catalog search, paste URL,
|
||
downloaded badges and an inline Downloading… / Added / Failed status per
|
||
result, so the keyboard never hides the feedback.
|
||
- **Downloads** — offline files and storage usage.
|
||
- **Settings** — account, server URL, audio (normalization, crossfade, source
|
||
quality), offline storage and auto-synced moods, sign out.
|
||
|
||
There is no Library tab, no Longform tab and no global shuffle.
|
||
|
||
## Project layout
|
||
|
||
```text
|
||
composeApp/
|
||
|-- src/commonMain/kotlin/win/taptap/musicmanager/client/
|
||
| |-- api/ # Ktor client and DTOs mirroring /api/v1
|
||
| |-- data/ # AppStorage, AppCache, session persistence
|
||
| |-- playback/ # AudioPlayer abstraction
|
||
| |-- store/ # AppStore: state, search, radio queue, downloads
|
||
| `-- 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 36 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 36 with build-tools 36.0.0, and the desktop runtime libraries):
|
||
|
||
```bash
|
||
nix-shell
|
||
```
|
||
|
||
Without Nix, point `ANDROID_HOME` at an SDK containing platform 36 and
|
||
build-tools 36.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 (local only, not built by CI)
|
||
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.
|
||
|
||
Android cleartext HTTP is enabled for local development. Use HTTPS in
|
||
production.
|
||
|
||
## Publishing to Google Play (internal testing)
|
||
|
||
The application id `win.tap_tap.audiomanager.client` is fixed after the first
|
||
upload. Google Play requires new apps to target API 36, and every upload needs a
|
||
higher `versionCode`.
|
||
|
||
### 1. Upload key (once)
|
||
|
||
Play App Signing keeps the real signing key; this project only needs an upload
|
||
key. Create it and store the keystore plus both passwords in a password manager:
|
||
|
||
```bash
|
||
keytool -genkeypair -v -keystore upload-keystore.jks -storetype PKCS12 \
|
||
-alias upload -keyalg RSA -keysize 4096 -validity 10000
|
||
```
|
||
|
||
Add the values to `local.properties` (git-ignored) or export them in CI:
|
||
|
||
```properties
|
||
UPLOAD_STORE_FILE=/absolute/path/upload-keystore.jks
|
||
UPLOAD_STORE_PASSWORD=...
|
||
UPLOAD_KEY_ALIAS=upload
|
||
UPLOAD_KEY_PASSWORD=...
|
||
```
|
||
|
||
CI equivalents: `ANDROID_KEYSTORE_PATH`, `ANDROID_KEYSTORE_PASSWORD`,
|
||
`ANDROID_KEY_ALIAS`, `ANDROID_KEY_PASSWORD`.
|
||
|
||
### 2. Build the bundle
|
||
|
||
```bash
|
||
scripts/build-release-aab.sh <versionCode> <versionName>
|
||
# composeApp/build/outputs/bundle/release/composeApp-release.aab
|
||
```
|
||
|
||
The script verifies the signature and prints the SHA-256.
|
||
|
||
### 3. Upload
|
||
|
||
In Play Console: **Testing → Internal testing → Create new release → App
|
||
integrity → Google-generated key**, upload the AAB, add release notes, then
|
||
**Save → Roll out**.
|
||
|
||
### 4. Automated uploads
|
||
|
||
Tagged builds (`v*`) publish to internal testing from CI. The Gitea secrets are:
|
||
|
||
| Secret | Value |
|
||
| --- | --- |
|
||
| `ANDROID_KEYSTORE_BASE64` | `base64 -w0 upload-keystore.jks` |
|
||
| `ANDROID_KEYSTORE_PASSWORD` | keystore password |
|
||
| `ANDROID_KEY_ALIAS` | `upload` |
|
||
| `ANDROID_KEY_PASSWORD` | key password |
|
||
| `PLAY_SERVICE_ACCOUNT_JSON` | contents of the service account JSON |
|
||
|
||
Then `git tag v0.4.3 && git push --tags` builds, signs and uploads the bundle.
|
||
Gradle Play Publisher asks Play for the next free `versionCode`
|
||
(`ResolutionStrategy.AUTO`), so only the tag/version name needs to change.
|
||
|
||
## App state and offline behaviour
|
||
|
||
`AppStore` is a plain Kotlin class with a `StateFlow<AppState>`; Compose observes
|
||
it. It owns:
|
||
|
||
- **Auth** — restore the saved token on launch and log out.
|
||
- **Mood sync** — GET `/moods` on login/refresh; details are fetched when a mood
|
||
is opened and cached.
|
||
- **Mood cache** — cached details power offline mood lists and downloads.
|
||
- **Search** — debounced remote catalog search with the selected target mood and
|
||
its source.
|
||
- **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 the shared
|
||
song id.
|
||
- **Playback snapshot** — the session, upcoming queue, current track, history and
|
||
position are persisted and restored on the next launch.
|
||
- **Offline retry** — a background loop retries the mood sync until the server
|
||
responds again.
|
||
|
||
On startup the app is usable before the network call completes: cached moods
|
||
render immediately, then refresh in the background. Offline playback uses the
|
||
mood's cached songs filtered by downloaded files.
|
||
|
||
## 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 permanent in the mood, so it is always eligible in future
|
||
radio and visible in the song list.
|
||
|
||
## 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.
|
||
|
||
- **main / PR:** run `desktopTest` and build the Android APK.
|
||
- **`v*` tag:** additionally build the desktop fat jar, attach the artifacts to
|
||
the Gitea release, and publish the AAB to Play internal testing.
|
||
- The Wasm target stays in the project for local builds but is **not** part of
|
||
CI; compiling it dominates the pipeline runtime.
|
||
|
||
Rebuild the CI image after changing `ci/Dockerfile` or dependency versions:
|
||
|
||
```bash
|
||
scripts/build-ci-image.sh 3
|
||
```
|
||
|
||
## Known limitations
|
||
|
||
- The media notification exposes play/pause, skip and back from the timeline.
|
||
Adding to a mood stays in the app because the session and its events belong to
|
||
the server. The queue lives in the Android media service, but the *next batch*
|
||
still comes from the app process; if the process is killed, the known queue
|
||
keeps working but nothing more is fetched.
|
||
- Desktop playback supports seeking by reopening the decoder at the requested
|
||
position. 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.
|
||
- Downloads 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.
|
||
- Search and downloads depend on the server's catalogs. YouTube bot checks can
|
||
fail a YouTube Music search (`502`) or leave a recommendation in `failed`
|
||
with Retry. Music search resolves every result for its artist/album/duration,
|
||
so a YouTube Music search takes roughly 10–15 seconds for ten results;
|
||
Deezer search is much faster.
|
||
- Deezer downloads need `DEEZER_ARL` on the server. A Free ARL is limited to
|
||
128 kbps; Premium enables 320 kbps. The client never stores the ARL.
|
||
- No iOS target yet. The shared module is ready for one.
|