Files
AudioManagerClient/README.md
T
TapTap 96ab25a91d
CI / build (push) Successful in 12m2s
CI / play (push) Successful in 3m18s
feat: search YouTube Music and poll for the first recommendation batch
- label and document the YouTube Music search source
- allow up to 60s for a search and request ten results
- keep refreshing a new mood until its first recommendations arrive
2026-11-16 18:38:58 +00:00

11 KiB
Raw Permalink Blame History

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 songs are added by searching 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 YouTube Music from inside a mood or globally with a mood picker. Results are canonical songs with artist, album and duration; 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)
  • 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.
  • 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 Music 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

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

nix-shell

Without Nix, point ANDROID_HOME at an SDK containing platform 36 and build-tools 36.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.

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:

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:

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

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.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.

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 YouTube Music 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 render immediately, then refresh in the background. Offline playback uses the mood's cached songs filtered by downloaded files.

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

scripts/build-ci-image.sh 3

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. 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. Music search resolves every result for its artist/album/duration, so a search takes roughly 10–15 seconds for ten results.
  • No iOS target yet. The shared module is ready for one.