feat: move the client to searchable, downloadable moods
CI / build (push) Successful in 3m28s
CI / play (push) Skipped

- new mood/song/search/recommendation models and API calls
- AppCache v2 with moods and details only
- Search and Downloads screens; remove Library and Longform
- new mood detail with songs, add music and recommendation states
- song-keyed covers and updated tests/docs
This commit is contained in:
TapTap committed 2026-11-15 21:37:39 +00:00
1 parent 1bb23901eb
commit dc270f863c
18 files changed
+1466 -1929

No files matched your search

+113 -72
View File
@@ -1,8 +1,11 @@
# AudioManager Client
Kotlin Multiplatform client for [AudioManager](../AudioManager) — a mood-first, self-hosted music server.
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 "likes" are replaced by explicit **add to mood** actions.
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 by searching YouTube.
## Targets
@@ -12,33 +15,65 @@ The client and server are designed together. There is no OpenSubsonic compatibil
| **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.
- 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 YouTube** from inside a mood or globally with a mood picker. 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.
- 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.
- 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.
- **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**: name, description, discovery hint, genres, collection share,
active recommendation count (0–30), and refresh interval.
- **Downloads** screen for device-side copies: play, delete, clear, storage
usage.
- **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.
- 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.
- 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.
- 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 | Search | Downloads | Settings`
- **Moods** — grid with song and pick counts, create, global search.
- **Mood Detail** — songs, add music, recommendations, next batch, settings.
- **Search** — mood picker, YouTube search, paste URL, downloaded badges.
- **Downloads** — offline files and storage usage.
- **Settings** — account, server URL, offline storage, sign out.
There is no Library tab, no Longform tab and no global shuffle.
## Project layout
@@ -46,9 +81,9 @@ The shared module contains the API client, session/cache storage, radio queue, a
composeApp/
|-- src/commonMain/kotlin/win/taptap/musicmanager/client/
| |-- api/ # Ktor client and DTOs mirroring /api/v1
| |-- data/ # AppStorage, LibraryCache, session persistence
| |-- data/ # AppStorage, AppCache, session persistence
| |-- playback/ # AudioPlayer abstraction
| |-- store/ # AppStore: state, radio queue, downloads, editing
| |-- 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
@@ -60,15 +95,18 @@ composeApp/
## Build
Requirements: JDK 21, Android SDK 36 for the app target, Node (Kotlin downloads its own for web).
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):
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
```
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 36 and build-tools 36.0.0.
Without Nix, point `ANDROID_HOME` at an SDK containing platform 36 and
build-tools 36.0.0.
```bash
export ANDROID_HOME=/opt/android-sdk
@@ -91,9 +129,12 @@ 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.
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.
Android cleartext HTTP is enabled for local development. Use HTTPS in
production.
## Publishing to Google Play (internal testing)
@@ -130,27 +171,17 @@ 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. Bump `versionCode` for
every upload; `VERSION_CODE`/`VERSION_NAME` can also be set in the environment.
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**. The first upload enrolls the app in Play App Signing. Share
the opt-in link from the Testers tab with your test list.
**Save → Roll out**.
### 4. Automated uploads
Tagged builds (`v*`) publish to internal testing from CI. One-time setup:
1. In Google Cloud, enable the **Google Play Android Developer API**.
2. Create a service account and download a JSON key.
3. In Play Console → **Users and permissions → Invite new user**, add the
service account's `client_email`, give it access to this app with
**Release to testing tracks** and **View app information** (do not grant
production or admin access).
4. Add these repository secrets in Gitea:
Tagged builds (`v*`) publish to internal testing from CI. The Gitea secrets are:
| Secret | Value |
| --- | --- |
@@ -164,28 +195,28 @@ Then `git tag v0.2.0 && 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.
Local equivalent (takes the JSON from an environment variable, never a file in
the repo):
```bash
ANDROID_PUBLISHER_CREDENTIALS="$(cat ~/play-service-account.json)" \
ANDROID_HOME=/opt/android-sdk gradle :composeApp:publishBundle
```
## App state and offline behaviour
`AppStore` is a plain Kotlin class with a `StateFlow<AppState>`; Compose observes it. It owns:
`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.
- **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.
- **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 YouTube search with the selected target mood.
- **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 and library render immediately, then refresh in the background.
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
@@ -200,14 +231,20 @@ open mood ──► POST /moods/{id}/sessions ──► queue (12 tracks)
└─ 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.
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, so jobs do not download them on every run.
`.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`, 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.
- **main / PR:** run `desktopTest`, build the Android APK and the *development*
Wasm bundle.
- **`v*` tag:** additionally build the desktop fat jar and the optimized Wasm
bundle, attach the artifacts to the Gitea release, and publish the AAB to Play
internal testing.
Rebuild the CI image after changing `ci/Dockerfile` or dependency versions:
@@ -215,14 +252,18 @@ 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.
- 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. 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 `yt-dlp` on the server. YouTube bot checks can
fail a search (`502`) or leave a recommendation in `failed` with Retry.
- No iOS target yet. The shared module is ready for one.