TapTap a5af1ee83f
CI / chart (push) Successful in 4s
CI / chart-push (push) Successful in 4s
CI / test (push) Successful in 2m5s
CI / image (push) Successful in 3m14s
feat: download accepted recommendations and track longform progress
Accepted recommendations without a library match now enter a download queue.
A worker downloads the MP3 with yt-dlp into "<music>/AudioManager Imports",
runs a scan, matches the new song, links it to the recommendation and adds it
as a seed. Jobs retry three times and expose queued/downloading/done/failed
state (plus the error) on the recommendation DTO, so clients can show progress
and retry. Downloads can be disabled and the target folder chosen.

Long-form gets resume points: GET/PUT /longform/progress, scoped to longform
folders and to the owner, with automatic completion detection. Longform stays
excluded from moods and radio.

The chart mounts the music hostPath writable for imports and passes the new
DOWNLOAD_* settings; version 0.2.3.
2026-11-15 13:26:22 +00:00

AudioManager

A self-hosted, mood-first music server in Kotlin/Ktor, plus a Kotlin Multiplatform client.

AudioManager replaces static playlists with moods: curated anchors plus a radio queue that is generated live by the server and learns from what you finish and skip. There is no like button and no OpenSubsonic layer — the native API and the native client are designed together around this model.

Contents

  1. Quick start
  2. Configuration
  3. The mood model
  4. Native API
  5. Architecture
  6. Database
  7. Scanner
  8. Deployment
  9. Client
  10. Testing
  11. Roadmap

Quick start

Requirements: JDK 21, ffmpeg, SQLite (bundled through JDBC). With Nix, nix-shell provides the JDK, Gradle, ffmpeg, sqlite, Python, Helm, Kustomize and kubectl.

# 1. Build
gradle shadowJar

# 2. Point the server at a library
mkdir -p data
cat > config/library.yaml <<'YAML'
library:
  folders:
    - id: 1
      name: Music
      type: music
      path: /absolute/path/to/music
    - id: 10
      name: Long-form
      type: longform
      path: /absolute/path/to/longform
YAML

# 3. Define users (passwords stay outside SQLite)
cat > config/users.yaml <<'YAML'
users:
  - name: alice
    password: change-me
    admin: true
    folders: [1]
YAML

# 4. Run
DATA_DIR=./data LIBRARY_CONFIG=./config/library.yaml USERS_FILE=./config/users.yaml \
  java -jar build/libs/musicmanager-*-all.jar

The server exposes the native API under /api/v1; use the Kotlin Multiplatform client for browsing and playback. The first start scans the library automatically because the database is empty. Later scans are manual:

curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/scan

Configuration

library.yaml

library:
  folders:
    - id: 1
      name: Music
      type: music
      path: /mnt/media/music
    - id: 10
      name: Long-form
      type: longform
      path: /mnt/media/longform
  • type is either music or longform. They are never mixed in a mood.
  • IDs are stable and referenced by songs; never reuse an ID for a different path.
  • Long-form folders are shared with every user automatically.

users.yaml

users:
  - name: alice
    password: change-me
    admin: true
    folders: [1]
  - name: bob
    password: another-secret
    admin: false
    folders: [1]

Passwords are read into memory at startup and never written to SQLite. In production this file is a Vault-managed Secret. Restart the deployment after changing users.

Environment

Variable Default Meaning
PORT 8080 HTTP port
DATA_DIR ./data SQLite database and cover cache
LIBRARY_CONFIG ./config/library.yaml Library folders
USERS_FILE ./config/users.yaml Users and passwords
FFMPEG_PATH ffmpeg Transcoder binary
YTDLP_PATH yt-dlp yt-dlp binary used for discovery and downloads
DOWNLOADS_ENABLED true Download accepted recommendations that are not in the library
DOWNLOAD_DIR $DATA_DIR/downloads Temporary files for the download worker
DOWNLOAD_FOLDER_ID first visible music folder Folder that receives downloaded MP3s

The mood model

A mood is a private collection owned by one user:

  • Seeds are permanent anchors. Every seed is always eligible for the radio.
  • Genres / free-text hint widen the candidate pool.
  • Target size is the desired batch and session size, not a hard playlist length.
  • Radio is generated by the server for each playback session. It mixes seeds, related genres and artists, text matches, and the rest of the owner's music. Tracks started, finished or skipped in the last 7 days are skipped while the library is large enough, and artists/albums are spaced across the batch.
  • Signals come from playback: completed tracks gain weight, skips weigh three times as much. There are no likes.
  • Add to mood is explicit. The client offers add to current mood and choose another mood, and the server turns the track into a manual seed.
  • Long-form is excluded at seed validation and radio generation.

A playback session belongs to one mood and one user. The server remembers queued tracks so a batch never repeats within the session, and a client can resume after a restart.

Native API

All endpoints live under /api/v1. JSON in, JSON out, standard HTTP status codes. Errors use:

{ "error": { "code": "not_found", "message": "Mood not found" } }

Authentication

POST /api/v1/auth/login
Content-Type: application/json

{ "username": "alice", "password": "change-me", "deviceName": "Pixel", "platform": "android" }
{
  "token": "…",
  "expiresAt": "2027-05-13T…",
  "user": { "name": "alice", "admin": true, "musicFolders": [1], "longformFolders": [10] }
}

Send Authorization: Bearer <token> on every request. Tokens are stored as SHA-256 hashes and expire after 180 days. Media URLs may also use ?token= because HTML audio and <img> tags cannot set headers.

  • POST /auth/logout revokes the current token.
  • GET /auth/devices lists devices; DELETE /auth/devices/{id} revokes one.
  • GET /me returns the user and folder IDs.

Library sync

  • GET /library/songs?cursor=<id>&limit=500&scope=music|longform|all — snapshot page, ordered by song ID. Loop while nextCursor is present.
  • GET /library/songs?since=<revision> — delta with songs and deletedSongIds. Loop while nextSince is present.
  • GET /library/search?q=&limit=&scope= — normalized substring search.
  • GET /songs/{id}/stream — original MP3 with Range support. Optional maxBitRate, timeOffset, format, download=true.
  • GET /covers/{albumIdOrSongId}?size=320 — cached JPEG cover.

Song objects contain deterministic IDs (sg-…), album/artist names, duration, size, bitrate, genres, folderId, relativePath, and updatedAt, so a client can build an offline library without extra requests.

Moods

  • GET /moods
  • POST /moods — { name, description?, query?, genres[], targetSize, refreshHours, ytEnabled, seedSongIds[] }
  • GET /moods/{id} — mood, seeds and recommendations.
  • PATCH /moods/{id} — partial settings update; clearDescription / clearQuery clear fields.
  • DELETE /moods/{id}
  • POST /moods/{id}/seeds — { songId }
  • DELETE /moods/{id}/seeds/{songId}
  • GET /moods/{id}/preview?limit=20 — unpersisted radio preview.
  • GET /moods/{id}/recommendations — YT Music candidates with state and matched library song.
  • POST /moods/{id}/recommendations/refresh — run discovery now (bypasses refreshHours).
  • POST /moods/{id}/recommendations/{videoId}/accept — accept; the library match becomes a seed immediately.
  • POST /moods/{id}/recommendations/{videoId}/reject — reject; the candidate is not offered again.

Accepted recommendations without a library match are queued for download (download.state = queued|downloading|done|failed in the recommendation). The worker writes MP3s into <music folder>/AudioManager Imports, runs a scan, matches the new song, adds it as a seed and updates the recommendation.

Radio sessions

  • POST /moods/{id}/sessions — { limit?: 15 } → session plus the first queue.
  • GET /sessions/{id} — resume: session and queued tracks.
  • POST /sessions/{id}/next — { limit?, excludeSongIds[] } → the next batch.
  • POST /sessions/{id}/events — { events: [{ songId, type: "started"|"completed"|"skipped", positionSeconds? }] }
  • POST /sessions/{id}/add-to-mood — { songId, moodId? }. Without moodId, the session's mood is used. This is the replacement for likes.
  • DELETE /sessions/{id} — close.

Long-form

  • GET /library/songs?scope=longform — the long-form library (shared with every user).
  • GET /longform/progress — resume points, newest first, with song data.
  • PUT /longform/progress/{songId} — { positionSeconds, durationSeconds?, completed? }.

Long-form folders are never valid mood seeds and never enter radio.

System

  • GET /scan — { scanning, count, error }
  • POST /scan — admin only; 202 Accepted.
  • GET /health — unauthenticated liveness probe.

Architecture

src/main/kotlin/win/taptap/musicmanager/
|-- Application.kt              # Ktor entry point, plugins, graceful shutdown
|-- config/
|   |-- AppConfig.kt            # Port, data dir, ffmpeg, env overrides
|   |-- LibraryConfig.kt        # Folder IDs, types and paths
|   `-- UsersConfig.kt          # Users, admins and folder assignments
|-- discovery/
|   |-- YtSearch.kt             # yt-dlp search and result parsing
|   `-- DiscoveryService.kt     # Queries, matching, scoring, pruning
|-- download/
|   |-- DownloadService.kt      # Queue worker, import folder, scan, promotion
|   `-- YtDlpDownloader.kt      # MP3 download with embedded metadata
|-- api/
|   |-- ApiRoutes.kt            # /api/v1 wiring, auth and system endpoints
|   |-- ApiModels.kt            # Native DTOs
|   |-- ApiSupport.kt           # Token resolution, errors, folder scoping
|   |-- LibraryApi.kt           # Sync, search, stream, covers
|   |-- MoodApi.kt              # Mood CRUD, seeds, preview, recommendations
|   |-- LongformApi.kt          # Long-form resume points
|   `-- SessionApi.kt           # Radio sessions, events, add-to-mood
|-- radio/
|   `-- RadioService.kt         # Candidate pool, scoring, diversity, batches
|-- db/
|   |-- DatabaseFactory.kt      # SQLite WAL + Flyway
|   |-- Tables.kt               # Exposed definitions
|   |-- ApiTokenRepository.kt   # Hashed bearer tokens
|   |-- RadioRepository.kt      # Sessions, events, affinity
|   |-- MoodRepository.kt       # Moods, seeds, recommendations
|   |-- LibraryRepository.kt    # Scoped browsing, sync, search
|   `-- MediaRepository.kt      # Scanner persistence and tombstones
|-- scanner/                    # Recursive MP3 scan, tags, covers
|-- transcoding/                # ffmpeg MP3 transcoding
`-- util/                       # Deterministic IDs, sort names

YT discovery runs in the background for stale moods (refreshHours) and on demand from the mood screen. Queries come from the mood text, seed artists and genres; results are deduplicated, filtered to music-length videos, matched to library songs by normalized title and artist, and scored. Undecided candidates not seen in a refresh are pruned; accepted and rejected decisions are permanent. Accepted tracks that are not in the library are downloaded by the worker into <music>/AudioManager Imports, scanned, matched and added as seeds automatically.

The old OpenSubsonic layer (/rest, subsonic/, playlist materialization) was removed in 0.2.0. The server and the KMP client are the two halves of the same product; there is no compatibility layer to preserve and no server-rendered UI.

Database

SQLite in WAL mode, migrations through Flyway:

  • V1__init.sql — users, folders, artists, albums, songs, user state.
  • V2__user_item_ratings.sql, V3__song_lyrics.sql.
  • V4__moods.sql — the first playlist-based mood prototype.
  • V5__native_api.sql — native moods, tokens, playback sessions, affinity, tombstones; drops playlists; adds songs.updated_at.

Key invariants:

  • IDs are deterministic (ar-, al-, sg-, mo-) with frozen normalization (NFC, trimmed, collapsed whitespace, lowercase).
  • Albums are grouped by album artist, not by track artist.
  • Deleted songs leave tombstones so offline clients can remove them.
  • Passwords never appear in the database.

Scanner

  • Indexes .mp3 recursively; other extensions are skipped and logged.
  • Tags first, Artist/Album/Track path fallback.
  • Delta scan: unchanged file mtimes are skipped.
  • Orphan cleanup writes song tombstones.
  • The first start scans automatically when the songs table is empty.
  • Manual scans come from POST /api/v1/scan or a client.

Deployment

Images and charts are published by Gitea Actions to gitea.tap-tap.win.

Image: gitea.tap-tap.win/taptap/audiomanager:<tag>
Chart: https://gitea.tap-tap.win/TapTap/Charts/raw/branch/main

The Charts README always shows the newest published chart version; scripts/push-chart.sh regenerates that section on every publish.

Kustomize example:

helmCharts:
  - name: audiomanager
    repo: https://gitea.tap-tap.win/TapTap/Charts/raw/branch/main
    releaseName: audiomanager
    version: 0.2.0-sha.<commit>
    namespace: audiomanager
    valuesFile: values.yaml

The chart renders every resource into the namespace passed to Helm (--namespace or helmCharts[].namespace) and refuses to render when that namespace is missing or falls back to default, so a forgotten namespace cannot deploy into the wrong place. Set allowDefaultNamespace=true to opt in to default. scripts/check-chart.sh lints the chart and enforces this in CI.

The chart expects:

  • a users.yaml Secret (Vault-managed) referenced by users.existingSecret;
  • a writable music hostPath when automatic downloads are enabled;
  • a library.yaml ConfigMap;
  • read-only hostPaths for music and long-form;
  • a registry pull secret for the private image.

Ingress host: subsonic.tap-tap.win (the historical name is kept, but the server no longer speaks the Subsonic protocol).

kustomize build --enable-helm . | kubectl apply -f -
kubectl -n audiomanager rollout status deployment/audiomanager

Flyway applies V5__native_api.sql automatically. Existing playlist-based moods are migrated to native moods; old playlists and user stars are dropped.

Client

The client lives in TapTap/AudioManagerClient and is built with Kotlin Multiplatform + Compose Multiplatform:

  • Android: Media3/ExoPlayer, background playback, offline downloads.
  • Desktop (JVM): shared Compose UI and a JVM audio backend.
  • Web (Wasm): the same Compose UI, HTML audio, tokenized stream URLs.

The shared module owns the API client, auth store, SQLDelight offline database, mood radio queue, and platform player abstractions. Downloads are original MP3s from /stream?download=true. Web is streaming-only (the browser owns its cache).

Testing

gradle test                      # unit + API integration tests
GRADLE=gradle scripts/smoke.sh   # end-to-end server smoke test
scripts/check-chart.sh           # lint the chart and enforce the namespace rule

The smoke test generates tagged MP3s, starts the server, and verifies login, sync, moods, radio, add-to-mood, streaming, transcoding, covers, scan and logout.

Roadmap

  • MP3 scanner, covers, deterministic IDs, SQLite + Flyway.
  • Native bearer-auth API, sync deltas, tombstones.
  • Mood CRUD, seeds, server-driven radio, playback events, add-to-mood.
  • Kotlin Multiplatform client foundation (Android, desktop, web).
  • Offline downloads and offline playback across clients.
  • YT Music discovery through yt-dlp, recommendation list, accept/reject.
  • Downloader that writes accepted tracks into an import folder and rescans.
  • Home-screen widgets, Android Auto, and richer radio tuning.
S
Description
No description provided
Readme
1.5 MiB
0 Stars 1 Watchers 0 Forks
Languages
Kotlin 89.3%
Shell 9.4%
Dockerfile 0.7%
Go Template 0.5%
Nix 0.1%