# 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 # 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`; 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 (`.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.