270 lines
9.9 KiB
Markdown
270 lines
9.9 KiB
Markdown
# AudioManager
|
||
|
||
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.
|
||
|
||
- 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
|
||
|
||
- [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`, `yt-dlp`, and (for the smoke test) `sqlite3`,
|
||
`curl`, `python3`. `nix-shell` provides everything.
|
||
|
||
```bash
|
||
# 1. Build and create local config
|
||
./gradlew setupLocal
|
||
# edit config/users.yaml (a password is required)
|
||
|
||
# 2. Run
|
||
./gradlew run
|
||
# health: http://localhost:8080/health
|
||
# API: http://localhost:8080/api/v1
|
||
```
|
||
|
||
The server creates `./data/media` (the media store), `./data/downloads`
|
||
(download temp files) and `./data/musicmanager.db`.
|
||
|
||
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
|
||
|
||
Everything is environment variables:
|
||
|
||
| 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: admin
|
||
password: "change-me"
|
||
admin: true
|
||
```
|
||
|
||
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 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
|
||
|
||
| 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
|
||
|
||
| 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 |
|
||
|
||
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.
|
||
|
||
### Search
|
||
|
||
| Method | Path | Purpose |
|
||
|---|---|---|
|
||
| `GET` | `/search?q=...&limit=...` | YouTube search |
|
||
|
||
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.
|
||
|
||
### Playback
|
||
|
||
| 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 |
|
||
|
||
### Media and maintenance
|
||
|
||
| 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
|
||
|
||
```
|
||
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
|
||
```
|
||
|
||
Background loops: download worker (continuous), recommendation top-up (hourly),
|
||
media GC (hourly). A scan runs at startup.
|
||
|
||
## 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 are Flyway scripts under
|
||
`src/main/resources/db/migration`.
|
||
|
||
- **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
|
||
|
||
The Helm chart is in `charts/audiomanager`. It renders one PVC at `/data`:
|
||
|
||
```
|
||
/data/musicmanager.db
|
||
/data/media/<videoId>/<title>.mp3
|
||
/data/covers/
|
||
/data/downloads/
|
||
```
|
||
|
||
No hostPath, no `library.yaml`, no init container. `fsGroup: 10001` makes the
|
||
PVC writable by the non-root container.
|
||
|
||
```bash
|
||
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>
|
||
```
|
||
|
||
`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. The old chart used the
|
||
same PVC name with a smaller size, and PVCs cannot shrink or be repopulated by
|
||
an upgrade, so recreate it:
|
||
|
||
```bash
|
||
kubectl -n audiomanager scale deployment/audiomanager --replicas=0
|
||
kubectl -n audiomanager delete pvc audiomanager-data
|
||
helm upgrade --install audiomanager charts/audiomanager \
|
||
--namespace audiomanager --reset-values \
|
||
--set users.existingSecret=audiomanager-users --set image.tag=<sha>
|
||
```
|
||
|
||
Old hostPath music/longform files can be deleted manually. There is no import.
|
||
|
||
## Client
|
||
|
||
Compose Multiplatform client: `/home/taptap/AudioManagerClient`.
|
||
|
||
- Android, desktop and Wasm from `commonMain`.
|
||
- Screens: Moods, Mood Detail, Search, Downloads, Settings.
|
||
- Android background playback and media notifications are kept.
|
||
|
||
## Testing
|
||
|
||
```bash
|
||
./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 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.
|