AudioManager
A self-hosted, mood-first music server. You create private moods, add tracks from YouTube Music 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
- Quick start
- Configuration
- Native API
- Architecture
- Media store and GC
- Database
- Deployment
- Client
- 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 indownloading,readyorfailedstate. Hiddennewcandidates 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.
# 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 Music. 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
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 Music search |
Results longer than 10 minutes (or shorter than 30 seconds) are hidden. Each
result reports downloaded, songId and inMood when applicable.
Search uses the YouTube Music catalog (the "Songs" filter), so results are canonical tracks with an artist, album and duration instead of arbitrary uploads. yt-dlp has to resolve every hit to read those fields, which takes roughly 10–15 seconds for ten results. If the Music search fails, the server falls back to the regular YouTube search so the feature keeps working.
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 YouTube Music 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.
Downloads are requested from the YouTube Music player
(music.youtube.com/watch?v=<id>), which makes yt-dlp embed the song's artist,
album and release year into the MP3. Videos that are not on the Music host fall
back to the regular YouTube URL. Files are MP3 only
(-x --audio-format mp3 --audio-quality 0).
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.
usersandapi_tokensare 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.
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:
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
./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.