Stop half a second before the boundary so ExoPlayer cannot start the next item, report the final completed event, and show offline download progress in mood settings. Version 0.4.2.
295 lines
13 KiB
Markdown
295 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.
|
||
- **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.2 && 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.
|