feat: rebuild AudioManager around downloadable moods
- V8 wipe migration and the shared song store keyed by YouTube video id - media store, indexer, downloader, recommendation top-up and refcounted GC - mood songs plus the recommendation lifecycle and mixed radio pools - new search, song and recommendation API; remove library/longform/seed routes - chart PVC/media env, docs, Nix, README and an end-to-end smoke test
This commit is contained in:
1 parent
50d8b6c580
commit
824eb36dd2
59 files changed
+3838
-5276
No files matched your search
@@ -1,359 +1,257 @@
|
||||
# AudioManager
|
||||
|
||||
A self-hosted, mood-first music server in Kotlin/Ktor, plus a Kotlin Multiplatform client.
|
||||
A self-hosted, mood-first music server. You create private moods, add tracks
|
||||
from YouTube search or a pasted URL, and the server downloads them into a shared
|
||||
media store. Recommendations are discovered and downloaded automatically so a
|
||||
mood keeps playing without a mounted music library.
|
||||
|
||||
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.
|
||||
- Server: Kotlin, Ktor, SQLite (Exposed + Flyway), `yt-dlp`, `ffmpeg`.
|
||||
- Client: Compose Multiplatform (Android, desktop, Wasm).
|
||||
- No uploads, no mounted library, no likes, no podcasts.
|
||||
|
||||
## Contents
|
||||
|
||||
1. [Quick start](#quick-start)
|
||||
2. [Configuration](#configuration)
|
||||
3. [The mood model](#the-mood-model)
|
||||
4. [Native API](#native-api)
|
||||
5. [Architecture](#architecture)
|
||||
6. [Database](#database)
|
||||
7. [Scanner](#scanner)
|
||||
8. [Deployment](#deployment)
|
||||
9. [Client](#client)
|
||||
10. [Testing](#testing)
|
||||
11. [Roadmap](#roadmap)
|
||||
- [How it works](#how-it-works)
|
||||
- [Quick start](#quick-start)
|
||||
- [Configuration](#configuration)
|
||||
- [Native API](#native-api)
|
||||
- [Architecture](#architecture)
|
||||
- [Media store and GC](#media-store-and-gc)
|
||||
- [Database](#database)
|
||||
- [Deployment](#deployment)
|
||||
- [Client](#client)
|
||||
- [Testing](#testing)
|
||||
|
||||
---
|
||||
## How it works
|
||||
|
||||
- **Moods are private.** A user sees only their own moods. Songs are shared
|
||||
server-wide and deduplicated by YouTube video id.
|
||||
- **Songs are the collection.** A mood needs at least one song before it can
|
||||
play. Removing a song only detaches it; the file is deleted when no mood,
|
||||
recommendation slot or open playback session references it.
|
||||
- **Recommendations are active slots.** A mood keeps `recommendationCount`
|
||||
(0–30, default 10) recommendations in `downloading`, `ready` or `failed`
|
||||
state. Hidden `new` candidates refill the slots automatically.
|
||||
- **Add / Not interested are permanent.** Adding promotes a recommendation into
|
||||
the collection. Rejecting is remembered per mood. Both free a slot and the
|
||||
server refills it.
|
||||
- **Playback mixes both pools.** Every queue slot rolls `collectionPercent`;
|
||||
the rest comes from ready recommendations. An empty pool falls back to the
|
||||
other one. Small pools replay least-recently-played tracks.
|
||||
- **Downloads are automatic.** Recommendation downloads run in the background
|
||||
up to the configured count even if the mood is never played. Manual adds have
|
||||
higher priority.
|
||||
|
||||
## 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.
|
||||
Requirements: JDK 21, `ffmpeg`, `yt-dlp`, and (for the smoke test) `sqlite3`,
|
||||
`curl`, `python3`. `nix-shell` provides everything.
|
||||
|
||||
```bash
|
||||
# 1. Build
|
||||
gradle shadowJar
|
||||
# 1. Build and create local config
|
||||
./gradlew setupLocal
|
||||
# edit config/users.yaml (a password is required)
|
||||
|
||||
# 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
|
||||
# 2. Run
|
||||
./gradlew run
|
||||
# health: http://localhost:8080/health
|
||||
# API: http://localhost:8080/api/v1
|
||||
```
|
||||
|
||||
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:
|
||||
The server creates `./data/media` (the media store), `./data/downloads`
|
||||
(download temp files) and `./data/musicmanager.db`.
|
||||
|
||||
```bash
|
||||
curl -X POST -H "Authorization: Bearer $TOKEN" http://localhost:8080/api/v1/scan
|
||||
```
|
||||
Downloads require `yt-dlp` to be able to reach YouTube. If YouTube applies bot
|
||||
checks, search and downloads fail with `502 search_failed` / `failed`
|
||||
recommendations; retry later or update `yt-dlp`.
|
||||
|
||||
## Configuration
|
||||
|
||||
### `library.yaml`
|
||||
Everything is environment variables:
|
||||
|
||||
```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.
|
||||
| Variable | Default | Meaning |
|
||||
|---|---|---|
|
||||
| `PORT` | `8080` | HTTP port |
|
||||
| `DATA_DIR` | `./data` | Database, cover cache, default media root |
|
||||
| `MEDIA_DIR` | `<DATA_DIR>/media` | Server-owned song store |
|
||||
| `DOWNLOAD_DIR` | `<DATA_DIR>/downloads` | yt-dlp temp/work directory |
|
||||
| `USERS_FILE` | `./config/users.yaml` | User accounts |
|
||||
| `FFMPEG_PATH` | `ffmpeg` | Transcoder binary |
|
||||
| `YTDLP_PATH` | `yt-dlp` | Downloader / search binary |
|
||||
|
||||
### `users.yaml`
|
||||
|
||||
```yaml
|
||||
users:
|
||||
- name: alice
|
||||
password: change-me
|
||||
- name: admin
|
||||
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.
|
||||
- **Seed mix** (`seedPercent`, 0–100) chooses how much of each batch comes from the seeds. The rest is filled from the generated recommendation pool (genres, artists, text matches and the rest of the library). Every slot rolls the percentage independently; when one pool is exhausted the other fills in. The default is 50/50.
|
||||
- **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.
|
||||
Passwords live only in this file (use a Vault-managed Secret in Kubernetes).
|
||||
`admin` is only needed for the maintenance scan endpoints. Old `folders:` keys
|
||||
are accepted and ignored.
|
||||
|
||||
## Native API
|
||||
|
||||
All endpoints live under `/api/v1`. JSON in, JSON out, standard HTTP status codes. Errors use:
|
||||
|
||||
```json
|
||||
{ "error": { "code": "not_found", "message": "Mood not found" } }
|
||||
```
|
||||
All endpoints are under `/api/v1` and require a bearer token, except login.
|
||||
Media URLs may use `?token=` because HTML audio and images cannot send headers.
|
||||
|
||||
### Authentication
|
||||
|
||||
```http
|
||||
POST /api/v1/auth/login
|
||||
Content-Type: application/json
|
||||
|
||||
{ "username": "alice", "password": "change-me", "deviceName": "Pixel", "platform": "android" }
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `POST` | `/auth/login` | `{username,password,deviceName,platform}` → token |
|
||||
| `POST` | `/auth/logout` | Revoke the current token |
|
||||
| `GET` | `/me` | Current user |
|
||||
| `GET` | `/auth/devices` | List device tokens |
|
||||
| `DELETE` | `/auth/devices/{id}` | Revoke a device |
|
||||
|
||||
### Moods
|
||||
|
||||
- `GET /moods`
|
||||
- `POST /moods` — `{ name, description?, query?, genres[], targetSize, refreshHours, ytEnabled, seedSongIds[], seedPercent? }`
|
||||
- `seedPercent` is 0–100 (default 50); the mood DTO also reports `recommendationPercent = 100 - seedPercent`.
|
||||
- `GET /moods/{id}` — mood, seeds and recommendations.
|
||||
- `PATCH /moods/{id}` — partial settings update, including `seedPercent`; `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.
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/moods` | List the user's moods |
|
||||
| `POST` | `/moods` | Create `{name,description,query,genres,collectionPercent,recommendationCount,refreshHours}` |
|
||||
| `GET` | `/moods/{id}` | Mood detail: songs and active recommendations |
|
||||
| `PATCH` | `/moods/{id}` | Update options |
|
||||
| `DELETE` | `/moods/{id}` | Delete mood, detach songs and run GC |
|
||||
| `GET` | `/moods/{id}/preview` | Unpersisted radio preview |
|
||||
| `POST` | `/moods/{id}/songs` | Add `{songId}`, `{videoId}` or `{url}` |
|
||||
| `DELETE` | `/moods/{id}/songs/{songId}` | Detach a song |
|
||||
| `GET` | `/moods/{id}/recommendations` | Active recommendation slots |
|
||||
| `POST` | `/moods/{id}/recommendations/refresh` | Force discovery + top-up |
|
||||
| `POST` | `/moods/{id}/recommendations/{videoId}/add` | Add to the collection |
|
||||
| `POST` | `/moods/{id}/recommendations/{videoId}/reject` | Hide permanently |
|
||||
| `POST` | `/moods/{id}/recommendations/{videoId}/retry` | Retry a failed download |
|
||||
|
||||
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/<artist>/<title>/`, embeds the video thumbnail as cover art, runs a scan, matches the new song by its deterministic path, adds it as a seed and updates the recommendation. The nested layout keeps per-track covers from overwriting each other.
|
||||
Adding an already downloaded song attaches instantly (`200`). A new video is
|
||||
queued for download (`202`, `downloading: true`) and is attached when the job
|
||||
finishes.
|
||||
|
||||
### Radio sessions
|
||||
### Search
|
||||
|
||||
- `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.
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/search?q=...&limit=...` | YouTube search |
|
||||
|
||||
### Long-form
|
||||
Results longer than 10 minutes (or shorter than 30 seconds) are hidden. Each
|
||||
result reports `downloaded` and `songId` when the track is already in the store.
|
||||
|
||||
- `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? }`.
|
||||
### Playback
|
||||
|
||||
Long-form folders are never valid mood seeds and never enter radio.
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `POST` | `/moods/{id}/sessions` | Start a queue (`400 empty_mood` without songs) |
|
||||
| `GET` | `/sessions/{id}` | Resume a session |
|
||||
| `POST` | `/sessions/{id}/next` | Fetch more tracks |
|
||||
| `POST` | `/sessions/{id}/events` | Report `started`, `completed`, `skipped` |
|
||||
| `POST` | `/sessions/{id}/add-to-mood` | Add the playing track to a mood |
|
||||
| `DELETE` | `/sessions/{id}` | Close the session |
|
||||
|
||||
### System
|
||||
### Media and maintenance
|
||||
|
||||
- `GET /scan` — `{ scanning, count, error }`
|
||||
- `POST /scan` — admin only; 202 Accepted.
|
||||
- `GET /health` — unauthenticated liveness probe.
|
||||
| Method | Path | Purpose |
|
||||
|---|---|---|
|
||||
| `GET` | `/songs/{id}/stream` | Range-aware stream; `maxBitRate`, `timeOffset`, `download` |
|
||||
| `GET` | `/songs/{id}/cover?size=` | Embedded artwork |
|
||||
| `GET` | `/scan` | Scan status |
|
||||
| `POST` | `/scan` | Start a scan (admin only) |
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
Ktor routes
|
||||
└── MoodRepository ── moods, mood_songs, recommendation lifecycle
|
||||
└── SongRepository ── shared song store keyed by video id
|
||||
└── RadioService ── mixes collection + ready recommendations
|
||||
└── DownloadService── single worker: yt-dlp → media store → index → attach
|
||||
└── DiscoveryService── yt-dlp search → hidden `new` candidates
|
||||
└── TopUpService ── keeps active slots at recommendationCount
|
||||
└── MediaScanner ── rebuilds the index from the media root
|
||||
└── MediaGcService ── refcounted file deletion
|
||||
```
|
||||
|
||||
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.
|
||||
Background loops: download worker (continuous), recommendation top-up (hourly),
|
||||
media GC (hourly). A scan runs at startup.
|
||||
|
||||
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.
|
||||
## Media store and GC
|
||||
|
||||
Layout:
|
||||
|
||||
```
|
||||
<MEDIA_DIR>/<videoId>/<sanitized-title>.mp3
|
||||
```
|
||||
|
||||
The first path segment is the YouTube video id, so the startup scan never
|
||||
depends on tags. One row and one file exist per video, no matter how many moods
|
||||
or users reference it. Covers are cached under `<DATA_DIR>/covers` keyed by song
|
||||
id.
|
||||
|
||||
A file is deleted only when it has no references from `mood_songs`, an active
|
||||
recommendation (`downloading`, `ready`, `added`, `failed`), or an open playback
|
||||
session. GC runs after removals, after rejections, after mood deletion, and
|
||||
hourly.
|
||||
|
||||
## Database
|
||||
|
||||
SQLite in WAL mode, migrations through Flyway:
|
||||
SQLite in WAL mode. Migrations are Flyway scripts under
|
||||
`src/main/resources/db/migration`.
|
||||
|
||||
- `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.
|
||||
- **V8 is destructive.** It drops every table from the mounted-library design
|
||||
(folders, artists, albums, songs, moods, seeds, sessions, longform progress,
|
||||
downloads) and creates the mood-first schema. `users` and `api_tokens` are
|
||||
kept.
|
||||
- There is no import from an old media directory. Back up externally and start
|
||||
with an empty `MEDIA_DIR`.
|
||||
|
||||
## Deployment
|
||||
|
||||
Images and charts are published by Gitea Actions to `gitea.tap-tap.win`.
|
||||
The Helm chart is in `charts/audiomanager`. It renders one PVC at `/data`:
|
||||
|
||||
```text
|
||||
Image: gitea.tap-tap.win/taptap/audiomanager:<tag>
|
||||
Chart: https://gitea.tap-tap.win/TapTap/Charts/raw/branch/main
|
||||
```
|
||||
/data/musicmanager.db
|
||||
/data/media/<videoId>/<title>.mp3
|
||||
/data/covers/
|
||||
/data/downloads/
|
||||
```
|
||||
|
||||
The [Charts README](https://gitea.tap-tap.win/TapTap/Charts) always shows the
|
||||
newest published chart version; `scripts/push-chart.sh` regenerates that section
|
||||
on every publish.
|
||||
|
||||
|
||||
Kustomize example:
|
||||
|
||||
```yaml
|
||||
helmCharts:
|
||||
- name: audiomanager
|
||||
repo: https://gitea.tap-tap.win/TapTap/Charts/raw/branch/main
|
||||
releaseName: audiomanager
|
||||
version: 0.2.4-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. The chart runs a `prepare-imports` init container (`downloads.prepare`) that creates `<music>/AudioManager Imports` and gives it to UID 10001. If the host denies the write, jobs fail immediately with the underlying error instead of retrying;
|
||||
- a `library.yaml` ConfigMap;
|
||||
- a writable music hostPath for imports (or `downloads.enabled=false`) and a read-only long-form hostPath;
|
||||
- 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).
|
||||
No hostPath, no `library.yaml`, no init container. `fsGroup: 10001` makes the
|
||||
PVC writable by the non-root container.
|
||||
|
||||
```bash
|
||||
kustomize build --enable-helm . | kubectl apply -f -
|
||||
kubectl -n audiomanager rollout status deployment/audiomanager
|
||||
kubectl create secret generic audiomanager-users \
|
||||
--from-file=users.yaml=config/users.yaml
|
||||
helm upgrade --install audiomanager charts/audiomanager \
|
||||
--namespace audiomanager --create-namespace \
|
||||
--set users.existingSecret=audiomanager-users \
|
||||
--set image.tag=<sha>
|
||||
```
|
||||
|
||||
Flyway applies `V5__native_api.sql` automatically. Existing playlist-based moods are migrated to native moods; old playlists and user stars are dropped.
|
||||
`scripts/release.sh --deploy` builds/pushes the image and runs the same Helm
|
||||
upgrade. CI builds `:latest` and `:sha-<commit>` on every push to `main`, and
|
||||
publishes the packaged chart.
|
||||
|
||||
Before deploying the mood-first version over an old instance, wipe the old
|
||||
database and media: V8 drops the content, but the old mounted files are no
|
||||
longer referenced and should be removed by the operator.
|
||||
|
||||
## Client
|
||||
|
||||
The client lives in `TapTap/AudioManagerClient` and is built with Kotlin Multiplatform + Compose Multiplatform:
|
||||
Compose Multiplatform client: `/home/taptap/AudioManagerClient`.
|
||||
|
||||
- **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, JSON offline cache, mood radio queue, and platform player abstractions. Downloads are original MP3s from `/stream?download=true`. Web is streaming-only (the browser owns its cache).
|
||||
- Android, desktop and Wasm from `commonMain`.
|
||||
- Screens: Moods, Mood Detail, Search, Downloads, Settings.
|
||||
- Android background playback and media notifications are kept.
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
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
|
||||
./gradlew test # server unit/integration tests
|
||||
./scripts/smoke.sh # end-to-end with a fake yt-dlp
|
||||
scripts/check-chart.sh # lint + render the Helm chart
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
- [x] MP3 scanner, covers, deterministic IDs, SQLite + Flyway.
|
||||
- [x] Native bearer-auth API, sync deltas, tombstones.
|
||||
- [x] Mood CRUD, seeds, server-driven radio, playback events, add-to-mood.
|
||||
- [x] Kotlin Multiplatform client foundation (Android, desktop, web).
|
||||
- [x] Offline downloads and offline playback across clients.
|
||||
- [x] YT Music discovery through `yt-dlp`, recommendation list, accept/reject.
|
||||
- [x] Downloader that writes accepted tracks into an import folder and rescans.
|
||||
- [ ] Home-screen widgets, Android Auto, and richer radio tuning.
|
||||
The smoke test seeds a tiny media store, puts a deterministic fake `yt-dlp` on
|
||||
`PATH`, and exercises auth, search filtering, adding songs, URL resolve,
|
||||
downloads, recommendations, radio sessions, streaming, covers and logout.
|
||||
Reference in new issue
Block a user