- seed from every artist (weighted by song count) and every album, not one track - walk Deezer's graph: artist top tracks, related artists, album deep cuts - score by artist frequency, collection album, catalog affinity and hint text - penalise repeated artists so a 30-slot mood spans artists, not one - refresh the pool when a song is added instead of waiting for refreshHours - skip discovery for a mood with no hint, genres or songs - extend tests and the smoke test with the artist graph
739 lines
36 KiB
Markdown
739 lines
36 KiB
Markdown
# Mood-first redesign — decisions and implementation handoff
|
||
|
||
Status: **approved design, implementation not started** (2026-11-15).
|
||
This document supersedes the mounted-library, local-search and longform parts
|
||
of the previous design. It is the source of truth for the next development
|
||
cycle; update it as implementation details are settled.
|
||
|
||
Repos:
|
||
- server: `/home/taptap/AudioManager` (Kotlin/Ktor, SQLite, Exposed, Flyway)
|
||
- client: `/home/taptap/AudioManagerClient` (Compose Multiplatform)
|
||
|
||
## 1. Product model
|
||
|
||
- Users have **moods only**. There is no mounted music directory, no file
|
||
upload and no longform/podcast content.
|
||
- Content enters the server by downloading from **Deezer** (default) or
|
||
**YouTube Music** through `streamrip` / `yt-dlp`. Each mood picks one source.
|
||
- Search is a remote catalog search against the mood's source. Results are
|
||
shown before anything is added.
|
||
- A mood contains:
|
||
- **Songs** — the user's collection. Added from search, from a recommendation,
|
||
or by attaching an already-downloaded song.
|
||
- **Recommendations** — candidates derived from the collection and mood
|
||
options. They are downloaded automatically so they can take part in radio
|
||
playback, but they are not part of the collection until the user adds them.
|
||
- A mood needs **at least one song** before it can be played.
|
||
- Playback builds each queue slot at random: with probability
|
||
`collectionPercent` it comes from the collection, otherwise from the ready
|
||
recommendations. An empty pool falls back to the other pool.
|
||
- `recommendationCount` (0–30, default 10) is the number of **active**
|
||
recommendations per mood: states `downloading`, `ready`, `failed`. `new`
|
||
candidates are a hidden pool used to refill slots. `added` and `rejected` are
|
||
decisions and do not count.
|
||
- Adding a recommendation turns it into a permanent mood song. Rejecting it is
|
||
permanent for that mood. Both free a slot and trigger a top-up.
|
||
- A failed recommendation download stays visible as `failed` with Retry / Not
|
||
interested; it counts as a slot until the user acts. It is never silently
|
||
replaced.
|
||
- `refreshHours` is the minimum interval for **automatic** discovery passes.
|
||
It never replaces a ready recommendation the user has not acted on.
|
||
- Removing a song only detaches it from the mood. Files are deleted only when
|
||
no mood references them.
|
||
- Songs are stored once server-wide, keyed by `(source, externalId)` and
|
||
deduplicated. Moods are strictly per-user: a user never sees another user's
|
||
moods or collection, but the same file can serve several users.
|
||
- No per-song owner, no storage quota.
|
||
|
||
## 2. Resolved decisions
|
||
|
||
1. `recommendationCount` counts downloading + ready + failed; add/reject frees
|
||
a slot and the server refills it.
|
||
2. Adding turns a recommendation into a collection song and removes it from the
|
||
recommendation list. Rejecting is permanent per mood and deletes the file
|
||
when unreferenced.
|
||
3. Failed downloads stay visible with Retry / Not interested.
|
||
4. `refreshHours` only throttles automatic discovery/top-up; it never replaces a
|
||
ready recommendation.
|
||
5. Small pools loop/replay least-recently played instead of going silent.
|
||
6. `seedPercent` becomes `collectionPercent`; recommendation plays count in
|
||
history and affinity like songs.
|
||
7. Mood options: name, description, query, genres, collectionPercent,
|
||
recommendationCount (default 10, max 30), refreshHours. `targetSize`,
|
||
`ytEnabled` are removed.
|
||
8. No accept step. Rows show download state, Add to mood, Not interested; failed
|
||
rows add Retry.
|
||
9. Search is one track at a time plus paste-a-URL; multi-select later. Results
|
||
longer than **10 minutes** are hidden. Already downloaded/in-mood results are
|
||
marked, and attaching an existing song is instant. Search exists inside a
|
||
mood and globally with a mood picker.
|
||
10. Library and Longform tabs are removed; Downloads stays for offline files.
|
||
Global Shuffle all is removed; playback stays per mood.
|
||
11. **Migration: full wipe.** Songs, moods, recommendations, downloads and
|
||
longform data are dropped. No import from the old mount.
|
||
12. Existing moods are wiped with the content.
|
||
13. Chart uses a PVC for `/data` (media at `/data/media`); music hostPath,
|
||
`library.yaml`, user folder lists, `DOWNLOADS_ENABLED` and
|
||
`DOWNLOAD_FOLDER_ID` disappear.
|
||
14. One song per `(source, externalId)`; the same recording from two catalogs is
|
||
two songs. Deezer track ids and YouTube video ids do not overlap.
|
||
Manual downloads outrank automatic recommendation downloads. Detach only;
|
||
GC deletes unreferenced files. A removed playing track finishes and drops
|
||
from future queues.
|
||
15. Recommendations are downloaded up to the configured count even if the mood
|
||
is never played.
|
||
16. Backups are external; no export/import feature and no offline CLI import.
|
||
17. Client: remove Library/Longform; keep Downloads for offline; add flow is
|
||
search -> download -> attach to mood; existing downloads attach instantly;
|
||
downloads run server-side with optional device downloads for offline.
|
||
18. Metadata is kept for display and search (title, artist, album, duration,
|
||
thumbnail). Separate album/artist/genre browse tables are removed.
|
||
|
||
## 3. What exists today (server)
|
||
|
||
Current files and responsibilities, and what happens to them:
|
||
|
||
| File | Today | New |
|
||
|---|---|---|
|
||
| `config/AppConfig.kt` | data dir, library/users paths, downloads flags | drop library path and download flags; add `MEDIA_DIR` |
|
||
| `config/LibraryConfig.kt` | folders, `FolderType` | delete |
|
||
| `config/UsersConfig.kt` | users + folder IDs | users only; ignore/remove `folders` |
|
||
| `db/ConfigRepository.kt` | sync folders + users | sync users only |
|
||
| `db/Tables.kt` | folders, artists/albums/genres, songs, moods, seeds, recommendations, jobs, sessions, affinity, longform, tombstones | rewrite for the new schema |
|
||
| `db/MediaRepository.kt` | scan upsert, album/artist aggregates, orphan delete | simplify to song upsert by video id + GC |
|
||
| `db/LibraryRepository.kt` | folder-scoped browse/search/delta/random | delete; replace with `SongRepository` |
|
||
| `db/MoodRepository.kt` | moods, seeds, recommendations | rewrite around `mood_songs` + recommendation lifecycle |
|
||
| `db/RadioRepository.kt` | sessions, items, affinity | keep, minus folder/library assumptions |
|
||
| `db/DownloadRepository.kt` | per-user/mood jobs, longform progress | rewrite job model; move longform repository out |
|
||
| `discovery/DiscoveryService.kt` | seeds + genres/query -> candidates, review | same inputs from collection; store `new` candidates; no `matchedSongId` library matching |
|
||
| `discovery/YtSearch.kt` | yt-dlp flat search | YouTube Music songs search with resolved metadata; regular `ytsearch` fallback; add URL resolve |
|
||
| `download/DownloadService.kt` | accept -> import folder -> scan -> seed | index directly into media store; attach song/recommendation; GC on failure |
|
||
| `download/YtDlpDownloader.kt` | MP3 + embedded metadata | keep; target `<source>-<externalId>/<title>.mp3` |
|
||
| `download/DeezerDownloader.kt` | - | streamrip with `DEEZER_ARL`; 128/320 MP3 |
|
||
| `scanner/MediaScanner.kt` | walks folder config | walks `MEDIA_DIR`; derive video id from path |
|
||
| `scanner/Mp3TagExtractor.kt` | tags/cover/lyrics | keep tags+cover; drop album/artist IDs and lyrics use |
|
||
| `scanner/CoverArtService.kt` | album-keyed covers | song-keyed covers |
|
||
| `radio/RadioService.kt` | library + seeds pool | collection + ready recommendations pool |
|
||
| `api/LibraryApi.kt` | library sync/search/stream/covers | keep stream; cover by song; delete sync/search |
|
||
| `api/LongformApi.kt` | progress | delete |
|
||
| `api/MoodApi.kt` | seeds + accept/reject | songs + add/reject/retry + top-up |
|
||
| `api/SessionApi.kt` | sessions, events, add-to-mood | keep sessions/events; adapt add-to-mood |
|
||
| `api/ApiModels.kt` | old DTOs | rewrite |
|
||
| `api/ApiRoutes.kt` | wiring + scan | wire new services; users only |
|
||
| `Application.kt` | library/users/scan/download/discovery loops | media/users/download/top-up/GC loops |
|
||
|
||
Current tests (server): `ApiRoutesTest`, `DatabaseFactoryTest`,
|
||
`DownloadServiceTest`, `MediaScannerTest`, `Mp3TagExtractorTest`,
|
||
`CoverArtServiceTest`, `DiscoveryServiceTest`, `RadioServiceTest`,
|
||
`AppConfigTest`, etc. They must be rewritten around the new model; keep useful
|
||
cases (auth, ownership, streaming, transcription, permissions).
|
||
|
||
## 4. Target server architecture
|
||
|
||
### 4.1 Media store
|
||
|
||
- One server-owned root: `MEDIA_DIR` (default `<data>/media`; chart PVC at
|
||
`/data`, `DATA_DIR=/data`, `MEDIA_DIR=/data/media`).
|
||
- Download temp/work dir: `<data>/downloads` or `<media>/.tmp`; must be on the
|
||
same filesystem as the final path for atomic moves.
|
||
- Layout: `<media>/<source>-<externalId>/<sanitized-title>.mp3` plus
|
||
`<media>/cover-cache/...` or a song-keyed cover derived from embedded art.
|
||
The first path segment carries the source and external id, which makes startup scans
|
||
deterministic and independent of tags.
|
||
- Song id: `sg-` + SHA-256 prefix of `"yt:<videoId>"` for YouTube (stable legacy
|
||
ids) or `"dz:<trackId>"` for Deezer.
|
||
- MP3 only (`yt-dlp -x --audio-format mp3 --audio-quality 0`), embedded
|
||
metadata and thumbnail.
|
||
- The scanner walks `MEDIA_DIR`, extracts `(source, externalId)` from the top-level folder,
|
||
reads tags/cover, and upserts the song. The downloader can call the same
|
||
indexer for one file to avoid waiting for a full scan.
|
||
- Orphan cleanup keeps the old safety guard: never wipe when the media root is
|
||
missing/unreadable. GC is reference-based (see 4.6).
|
||
|
||
### 4.2 Schema (V8)
|
||
|
||
Keep `users` and `api_tokens`. Drop and recreate everything else.
|
||
|
||
```sql
|
||
songs(
|
||
id TEXT PRIMARY KEY,
|
||
source TEXT NOT NULL DEFAULT 'youtube',
|
||
external_id TEXT NOT NULL UNIQUE,
|
||
title TEXT NOT NULL,
|
||
artist TEXT NOT NULL,
|
||
album TEXT,
|
||
duration INTEGER NOT NULL DEFAULT 0,
|
||
bit_rate INTEGER NOT NULL DEFAULT 0,
|
||
size INTEGER NOT NULL DEFAULT 0,
|
||
suffix TEXT NOT NULL DEFAULT 'mp3',
|
||
content_type TEXT NOT NULL DEFAULT 'audio/mpeg',
|
||
relative_path TEXT NOT NULL,
|
||
file_mtime INTEGER NOT NULL DEFAULT 0,
|
||
thumbnail TEXT,
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT NOT NULL
|
||
)
|
||
|
||
moods(
|
||
id TEXT PRIMARY KEY,
|
||
owner TEXT NOT NULL REFERENCES users(name) ON DELETE CASCADE,
|
||
name TEXT NOT NULL,
|
||
description TEXT,
|
||
query TEXT,
|
||
genres TEXT NOT NULL DEFAULT '[]',
|
||
collection_percent INTEGER NOT NULL DEFAULT 50,
|
||
recommendation_count INTEGER NOT NULL DEFAULT 10
|
||
CHECK (recommendation_count BETWEEN 0 AND 30),
|
||
refresh_hours INTEGER NOT NULL DEFAULT 24,
|
||
last_discovery_at TEXT,
|
||
created_at TEXT NOT NULL,
|
||
changed_at TEXT NOT NULL,
|
||
last_error TEXT
|
||
)
|
||
|
||
mood_songs(
|
||
mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE,
|
||
song_id TEXT NOT NULL REFERENCES songs(id) ON DELETE CASCADE,
|
||
origin TEXT NOT NULL DEFAULT 'search'
|
||
CHECK (origin IN ('search', 'recommendation', 'url')),
|
||
added_at TEXT NOT NULL,
|
||
PRIMARY KEY (mood_id, song_id)
|
||
)
|
||
|
||
mood_recommendations(
|
||
mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE,
|
||
source TEXT NOT NULL DEFAULT 'youtube',
|
||
external_id TEXT NOT NULL,
|
||
title TEXT NOT NULL,
|
||
artist TEXT NOT NULL,
|
||
album TEXT,
|
||
duration INTEGER,
|
||
thumbnail TEXT,
|
||
state TEXT NOT NULL DEFAULT 'new'
|
||
CHECK (state IN ('new', 'downloading', 'ready', 'failed', 'added', 'rejected')),
|
||
song_id TEXT REFERENCES songs(id) ON DELETE SET NULL,
|
||
attempts INTEGER NOT NULL DEFAULT 0,
|
||
error TEXT,
|
||
first_seen TEXT NOT NULL,
|
||
last_seen TEXT NOT NULL,
|
||
PRIMARY KEY (mood_id, external_id)
|
||
)
|
||
|
||
download_jobs(
|
||
id TEXT PRIMARY KEY,
|
||
source TEXT NOT NULL DEFAULT 'youtube',
|
||
external_id TEXT NOT NULL,
|
||
mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE,
|
||
kind TEXT NOT NULL CHECK (kind IN ('song', 'recommendation')),
|
||
state TEXT NOT NULL DEFAULT 'queued'
|
||
CHECK (state IN ('queued', 'downloading', 'done', 'failed')),
|
||
priority INTEGER NOT NULL DEFAULT 0,
|
||
attempts INTEGER NOT NULL DEFAULT 0,
|
||
error TEXT,
|
||
song_id TEXT REFERENCES songs(id) ON DELETE SET NULL,
|
||
created_at TEXT NOT NULL,
|
||
updated_at TEXT NOT NULL
|
||
)
|
||
|
||
playback_sessions(id, user_name, mood_id, next_position, created_at, last_seen_at, closed_at)
|
||
playback_session_items(session_id, position, song_id, state, queued_at, updated_at)
|
||
song_affinity(user_name, song_id, completions, skips, last_event_at)
|
||
```
|
||
|
||
Drop: `music_folders`, `artists`, `albums`, `album_artists`, `song_artists`,
|
||
`song_genres`, `album_genres`, `artist_genres`, `mood_seeds`,
|
||
`library_tombstones`, `longform_progress`, `user_song_state`, `user_stars`,
|
||
`bookmarks`, old `download_jobs`, old `mood_recommendations`, old `moods`,
|
||
old `songs`.
|
||
|
||
`DatabaseFactory.normalizeLegacyMoodStates` stays: an old V4 DB must still pass
|
||
V5/V6/V7 before V8 can wipe it.
|
||
|
||
### 4.3 Recommendation lifecycle
|
||
|
||
States: `new` (hidden candidate pool), `downloading`, `ready`, `failed`,
|
||
`added`, `rejected`.
|
||
|
||
- Discovery reads the **whole collection** (not one seed track): every artist
|
||
with its song count, every album, `query`, `genres` and the mood name.
|
||
- Discovery has two candidate sources, merged and ranked together:
|
||
1. **Text queries**: `query`, then up to 3 collection artists ordered by how
|
||
many songs the mood has, then up to 2 genres, capped at 4 queries.
|
||
2. **Catalog similarity graph** (`MusicCatalog.discover`): up to 5 collection
|
||
artists -> their top tracks; up to 2 of those artists' related artists ->
|
||
their top tracks; up to 2 collection albums -> album deep cuts. Deezer
|
||
implements this; YouTube Music has no such API and returns nothing.
|
||
- Scoring: exact collection artist `3.0 + 0.5` per extra song (capped `+1.5`),
|
||
partial artist `1.5`, album already in the collection `+1.0`, catalog
|
||
affinity (related artist `1.5`, album deep cut `1.0`, artist top `0.5`),
|
||
mood words in the title `+1.0`, over 8 minutes `-1.0`.
|
||
- Stores up to a bounded pool of `new` candidates (60). Excludes external ids
|
||
already in `mood_songs`, `added` or `rejected`.
|
||
- `topUp(mood, force)`:
|
||
1. Count active = `downloading + ready + failed`.
|
||
2. Promote the best `new` candidates to `downloading` and enqueue
|
||
`download_jobs` until `recommendationCount` is met.
|
||
3. Run discovery when slots are missing, or when a song was added after the
|
||
last pass (the pool is based on the collection), and
|
||
(`force || discoveryDue(mood)`).
|
||
4. Promote again after the pass.
|
||
- `force = true` on user add/reject/retry, on a finished manual download and on
|
||
the explicit refresh action. Background passes use `force = false` and run
|
||
hourly.
|
||
- `recommendationCount = 0` stops discovery and downloads for the mood.
|
||
- On download success:
|
||
- `downloading` -> `ready` with `song_id`.
|
||
- `added` (user added while downloading) -> insert `mood_songs`, keep
|
||
`added`, do not create a duplicate.
|
||
- `rejected` -> delete the file if unreferenced.
|
||
- On final download failure: `failed` with `error`; keep the slot.
|
||
- Add: if `ready`, attach the song; if `downloading`, mark `added` and attach
|
||
when the job completes; insert `mood_songs` with origin `recommendation`;
|
||
top up.
|
||
- Reject: mark `rejected`, cancel the job, GC, top up.
|
||
- Retry: `failed` -> `downloading`, reset the job, top up.
|
||
- `new` candidates are not shown in the client.
|
||
|
||
### How this compares to the big services
|
||
|
||
The commercial engines are trained on behaviour this server does not have: no
|
||
account-level listening history, no cross-user co-occurrence, no audio models.
|
||
Still, their published architecture explains which parts of the problem can be
|
||
replicated from a mood collection alone.
|
||
|
||
- **Spotify** combines content-based features (audio features such as
|
||
danceability, energy and valence, plus metadata and text/visual embeddings)
|
||
with collaborative filtering that treats playlist co-occurrence as the
|
||
similarity signal ("two tracks are similar if people curate them together").
|
||
Retrieval produces candidates, a ranking stage orders them, and each surface
|
||
has its own reward (skips, saves, session length).
|
||
- **YouTube Music** runs retrieval -> ranking -> filtering. Candidates come from
|
||
a deep model over watch history, and a 2024 transformer encodes the *sequence*
|
||
of user actions (intent, how much of a track was played, artist, language)
|
||
before blending with the ranker. Audio-text embeddings (MuLan) describe the
|
||
content itself.
|
||
- **Deezer Flow / Flow Moods** (RecSys 2022) mixes collaborative filtering,
|
||
audio analysis and professional curator mood annotations to build
|
||
mood-specific radios; the 2026 Flow Tuner adds genre toggles, explicit
|
||
dislikes, long-term habits and context such as time of day.
|
||
|
||
What this server reproduces without telemetry:
|
||
|
||
| Signal | Here | There |
|
||
|---|---|---|
|
||
| Taste profile | whole mood collection, artists weighted by song count + albums | per-user history and playlists |
|
||
| Similarity | catalog graph (related artists, artist top tracks, album deep cuts) + text queries | learned embeddings + co-occurrence |
|
||
| Feedback | add / not interested (permanent) | skips, saves, play counts, survey models |
|
||
| Context | mood hint, genres, refresh window | session, time of day, device, activity |
|
||
| Ranking | weighted score + per-artist diversity penalty | deep rankers with hundreds of features |
|
||
|
||
Not reproducible here: cross-user collaborative filtering, audio analysis and
|
||
sequence models. The add/reject lifecycle and the collection itself are the
|
||
only behavioural signals, which is why discovery leans on the catalog graph.
|
||
|
||
### 4.4 Download pipeline
|
||
|
||
- `download_jobs` are global; `kind=song` (manual add) has higher priority than
|
||
`kind=recommendation`. Claim by `priority DESC, created_at ASC`.
|
||
- Before downloading, check `songs(source, external_id)`:
|
||
- if the song exists and the file is present, attach immediately;
|
||
- otherwise download.
|
||
- A per-video download is effectively deduplicated by the existence check; two
|
||
moods may queue the same video, but only the first downloads and the second
|
||
completes instantly.
|
||
- Worker steps:
|
||
1. Claim a job.
|
||
2. Resolve target `<media>/<source>-<externalId>/<title>.mp3`.
|
||
3. If the song exists, finish.
|
||
4. Download to temp with yt-dlp/streamrip; move atomically; index
|
||
the file (tags/cover) and upsert the song by video id.
|
||
5. Apply the job outcome (song attach or recommendation state).
|
||
6. On permanent failure, remove the partial file and set `failed`.
|
||
- Keep the 3-attempt retry, stale-job recovery, permission classification and
|
||
UTF-8 filename truncation from the current implementation.
|
||
- Rejected/cancelled jobs must not later attach the track.
|
||
|
||
### 4.5 Playback / radio
|
||
|
||
- Inputs: collection songs (`mood_songs`) and `ready` recommendation songs.
|
||
- 0 collection songs -> API rejects session start with a clear error; the client
|
||
shows "Add at least one song".
|
||
- Candidate scoring: affinity (`completions - 3*skips`), recent-play penalty,
|
||
jitter, plus artist/album spacing in `pickMixed`. No genre/artist library
|
||
matching.
|
||
- `pickMixed(collection, recommendations, limit, collectionPercent)`:
|
||
each slot rolls the percentage; an empty pool falls back to the other one.
|
||
- Session de-duplication: exclude songs already queued in the session.
|
||
- Exhaustion: allow replay of the least-recently queued songs, but never
|
||
duplicate within one batch. A one-song mood returns one track per batch and
|
||
the client loops it.
|
||
- Persist session items and playback events exactly as today.
|
||
- Recommendation plays count in history/affinity.
|
||
- Remove `pickDiverse` if it becomes dead code.
|
||
|
||
### 4.6 File GC
|
||
|
||
A song is referenced by:
|
||
- any `mood_songs` row;
|
||
- any `mood_recommendations` row with `song_id = song` and state in
|
||
`downloading|ready|added|failed` (`added` also has `mood_songs`);
|
||
- an open playback session item (avoid deleting a track currently streaming).
|
||
|
||
When the reference count is zero, delete the song row, the media
|
||
directory and the cover. Run GC:
|
||
- after removing a song;
|
||
- after rejecting a recommendation;
|
||
- after deleting a mood;
|
||
- after a cancelled/failed job with no references;
|
||
- periodically (hourly) to catch leftovers.
|
||
|
||
### 4.7 Search and URL adds
|
||
|
||
- `GET /api/v1/search?q=...&limit=...&source=...&moodId=...` -> catalog results
|
||
with `source,externalId,title,artist,album,duration,thumbnail,songId?,downloaded,inMood`.
|
||
- `source` falls back to the mood's source, then `DEFAULT_SOURCE`.
|
||
- Hide results with `duration > 600` seconds and `< 30`.
|
||
- `POST /api/v1/moods/{id}/songs` accepts `songId` (existing download),
|
||
`source`+`externalId`, or `url`. Deezer URLs use the public API; YouTube URLs
|
||
use yt-dlp `--dump-single-json --no-playlist`.
|
||
- Search requires auth; Deezer is a fast public API call, while YouTube Music
|
||
resolves every hit (use a 60s client timeout). Return 502 on failure.
|
||
|
||
### 4.8 API surface
|
||
|
||
```
|
||
POST /api/v1/auth/login
|
||
POST /api/v1/auth/logout
|
||
GET /api/v1/me
|
||
GET /api/v1/moods
|
||
POST /api/v1/moods
|
||
GET /api/v1/moods/{id}
|
||
PATCH /api/v1/moods/{id}
|
||
DELETE /api/v1/moods/{id}
|
||
GET /api/v1/moods/{id}/preview
|
||
GET /api/v1/moods/{id}/recommendations
|
||
POST /api/v1/moods/{id}/recommendations/refresh
|
||
POST /api/v1/moods/{id}/recommendations/{externalId}/add
|
||
POST /api/v1/moods/{id}/recommendations/{externalId}/reject
|
||
POST /api/v1/moods/{id}/recommendations/{externalId}/retry
|
||
POST /api/v1/moods/{id}/songs
|
||
DELETE /api/v1/moods/{id}/songs/{songId}
|
||
POST /api/v1/moods/{id}/sessions
|
||
GET /api/v1/sessions/{id}
|
||
POST /api/v1/sessions/{id}/next
|
||
POST /api/v1/sessions/{id}/events
|
||
DELETE /api/v1/sessions/{id}
|
||
GET /api/v1/search
|
||
GET /api/v1/songs/{id}/stream (Range/transcoding as today)
|
||
GET /api/v1/songs/{id}/cover
|
||
GET /api/v1/scan (admin diagnostic; optional)
|
||
POST /api/v1/scan (admin; optional)
|
||
```
|
||
|
||
DTO sketch:
|
||
|
||
```text
|
||
UserDto(name, admin)
|
||
SongDto(id, source, externalId, title, artist, album, duration, bitRate, size, suffix,
|
||
thumbnail)
|
||
MoodDto(id, name, description, query, genres, collectionPercent,
|
||
recommendationPercent, recommendationCount, refreshHours,
|
||
lastDiscoveryAt, createdAt, changedAt, lastError, songCount,
|
||
recommendationReady, recommendationDownloading, recommendationFailed)
|
||
MoodSongDto(song, origin, addedAt)
|
||
MoodDetailDto(mood, songs, recommendations, downloads)
|
||
RecommendationDto(source, externalId, title, artist, album, duration, thumbnail, state,
|
||
song?, download?, firstSeen, lastSeen)
|
||
SearchResultDto(source, externalId, title, artist, album, duration, thumbnail, songId?,
|
||
downloaded)
|
||
```
|
||
|
||
Remove: `LibraryPage`, `SearchResponse` of local songs, all longform DTOs,
|
||
`SeedDto`, `AddSeedRequest`, `targetSize`, `ytEnabled`, folder fields.
|
||
|
||
### 4.9 Auth and users
|
||
|
||
- `users.yaml` keeps `name`, `password`, `admin`. Remove `folders`; accept and
|
||
ignore existing `folders` keys for compatibility.
|
||
- No folder validation, no `musicFolderIds`/`longformFolderIds`.
|
||
- `ConfigRepository.sync(users)` only reconciles users.
|
||
- Admin remains for optional scan/maintenance endpoints.
|
||
|
||
## 5. Client design
|
||
|
||
### 5.1 Screens
|
||
|
||
`Screen = Moods | MoodDetail | Search | Downloads | Settings`
|
||
|
||
- **Moods**: mood grid/list, create, global search icon.
|
||
- **MoodDetail**:
|
||
- header/play/settings;
|
||
- **Songs** collection with play/remove;
|
||
- **Add music** -> Search targeted at this mood;
|
||
- **Recommendations**: active rows with thumbnail, state/progress, Add to
|
||
mood, Not interested, Retry (failed);
|
||
- **Next batch** preview;
|
||
- mood options: name, description, query, genres, collectionPercent,
|
||
recommendationCount (0–30, default 10), refreshHours.
|
||
- **Search**: query field, debounced remote search, results (hide >10min done
|
||
server-side), Add; if opened globally, choose a mood; badges for downloaded /
|
||
already in mood; paste-a-URL action.
|
||
- **Downloads**: device-side downloaded songs, play/delete/clear, storage usage.
|
||
- **Settings**: server/account/devices/logout; remove scan UI.
|
||
- Remove `LibraryScreen` and all longform UI.
|
||
|
||
### 5.2 State and store
|
||
|
||
- `AppState` remove: `library`, `longform`, `longformResults`,
|
||
`longformProgress`, `musicResults`, `searchResults` (replace with
|
||
`searchResults: List<SearchResult>` + `searchTargetMoodId`), longform
|
||
progress.
|
||
- `CachedState` version 2: `serverUrl`, `userName`, `moods`, `moodDetails`
|
||
(each including songs/recommendations). No revision/longform. Invalidate old
|
||
caches on version mismatch.
|
||
- `AppStore`:
|
||
- bootstrap restores session, moods/details, playback snapshot and position;
|
||
- `refreshAll` fetches moods only; selected mood detail on open/refresh;
|
||
- create/update/delete mood;
|
||
- `addSong`, `removeSong`, `addRecommendation`, `rejectRecommendation`,
|
||
`retryRecommendation`, `refreshRecommendations`;
|
||
- `searchRemote(query)` with debounce and cancellation;
|
||
- `playMood` uses sessions; clear error when the mood has no songs; offline
|
||
fallback = cached mood songs filtered by device downloads;
|
||
- remove `playAll`, `playLongform*`, `resumeLongform`, `savedPosition`,
|
||
longform progress reporting;
|
||
- keep playback snapshot/history/previous/sleep timer/queue editing;
|
||
- keep device downloads (`toggleDownload`, `clearDownloads`) and artwork;
|
||
- `addCurrentToMood` works for collection songs via `songId`.
|
||
- `ApiClient`: new models/routes; remove library/longform; `coverUrl(songId)`.
|
||
- Mood detail polling while recommendations/downloads are active (bounded, with
|
||
backoff; no infinite loop).
|
||
|
||
### 5.3 Playback
|
||
|
||
Keep `AudioPlayer`, desktop seek, Android media session, notification, sleep
|
||
timer, history and queue snapshot. Only the server content model changes.
|
||
Offline playback uses device downloads; online mood playback uses sessions.
|
||
|
||
## 6. Migration
|
||
|
||
- **V8 drops all content**, keeps users and tokens.
|
||
- The old mounted music directory is no longer mounted; the operator must
|
||
delete old files manually. The new media root starts empty.
|
||
- The chart's old music/longform mounts and `library.yaml` are removed; add a
|
||
PVC.
|
||
- Client cache version bump clears old library/longform data.
|
||
- No CLI import and no app export (external backups only).
|
||
|
||
## 7. Ops
|
||
|
||
- `AppConfig`: `port`, `dataDir`, `usersFile`, `ffmpegPath`, `ytDlpPath`,
|
||
`mediaDir` (`MEDIA_DIR`, default `<dataDir>/media`), `downloadDir`
|
||
(`<dataDir>/downloads`). Remove `libraryConfigPath`, `downloadsEnabled`,
|
||
`downloadFolderId`.
|
||
- `Application.kt`: users only; scanner over `mediaDir`; download worker;
|
||
discovery/top-up loop; GC loop. No library scan-at-start for empty DB (scan
|
||
media root at startup is fine).
|
||
- Chart:
|
||
- one PVC for `/data`, `fsGroup` 10001, no hostPath/library ConfigMap, no
|
||
`prepare-imports` init container;
|
||
- `DATA_DIR=/data`, `MEDIA_DIR=/data/media`;
|
||
- keep users Secret, probes, resources; add persistence values;
|
||
- README deployment section rewritten.
|
||
- Nix shell: no library config; `DATA_DIR=./data`.
|
||
- Docker: `yt-dlp`, `ffmpeg`, Python 3 and `streamrip` (provides `rip`).
|
||
- Smoke test: rewrite for mood creation, search stub or seeded songs, add,
|
||
recommendations, playback. A fake `yt-dlp` script can return deterministic
|
||
search JSON and a tiny MP3 fixture for downloads.
|
||
|
||
## 8. Implementation plan
|
||
|
||
### Phase 1 — server schema and repositories
|
||
- V8 migration.
|
||
- Rewrite `Tables.kt`.
|
||
- `SongRepository` (upsert by video id, get by video id/id, list by mood,
|
||
attach/detach, refcount, delete).
|
||
- `MoodRepository` (CRUD, songs, recommendations lifecycle, top-up helpers).
|
||
- `DownloadRepository` (jobs, priority, claim, recovery, cancel, retry).
|
||
- GC service/repository.
|
||
- Tests: migration wipe, song dedupe, mood songs, recommendation state machine,
|
||
refcount/GC.
|
||
|
||
### Phase 2 — media store and downloader
|
||
- `AppConfig`/users cleanup.
|
||
- Path layout + indexer shared by scanner and downloader.
|
||
- `MediaScanner` over media root, video id from path.
|
||
- `CoverArtService` song-keyed.
|
||
- `YtDlpDownloader` target path; direct indexing after move.
|
||
- `DownloadService` attach-to-song/recommendation; failure cleanup; priority.
|
||
- Tests: manual add, existing song attach, shared file across moods/users,
|
||
reject during download, retry, GC, UTF-8 names, scan recovery.
|
||
|
||
### Phase 3 — discovery, top-up, radio
|
||
- `DiscoveryService` inputs from collection; store `new`; no library matching;
|
||
10-minute filter.
|
||
- `RecommendationTopUpService` (or methods in `MoodRepository`/`DiscoveryService`).
|
||
- `RadioService` collection + ready recommendations.
|
||
- Background loops: top-up hourly, GC hourly.
|
||
- Tests: N active, refill on add/reject, failed stays, refresh top-up only,
|
||
0/50/100 percent, small-pool repeat, no duplicates per batch, 0 songs error.
|
||
|
||
### Phase 4 — API
|
||
- New DTOs and routes; remove library/longform/seed endpoints.
|
||
- Search endpoint + URL resolve.
|
||
- Cover by song id.
|
||
- Session start guard.
|
||
- Tests: ownership, add/reject/retry, search filter, streaming, 400s, auth.
|
||
|
||
### Phase 5 — server ops
|
||
- Chart PVC, env, ConfigMap removal, init container removal.
|
||
- Nix/README/smoke.
|
||
- Chart check.
|
||
|
||
### Phase 6 — client data layer
|
||
- Models/ApiClient/cache version/store rewrite.
|
||
- Remove longform/library code paths.
|
||
- Tests: search/add, recommendation actions, play empty mood, offline fallback,
|
||
cache migration, playback snapshot.
|
||
|
||
### Phase 7 — client UI
|
||
- Moods/MoodDetail/Search/Downloads/Settings.
|
||
- Remove Library/Longform screens; adapt PlayerBar.
|
||
- Tests/builds: desktopTest, assembleDebug, Wasm.
|
||
|
||
### Phase 8 — integration
|
||
- Full server tests, smoke, chart check.
|
||
- Client tests/builds.
|
||
- Commit/push both repos, CI green.
|
||
- Optional: deploy, wipe DB/media, validate real downloads.
|
||
|
||
## 9. Test plan (high signal)
|
||
|
||
Server:
|
||
- V7 -> V8 migration keeps users/tokens, drops content, creates schema.
|
||
- Song upsert dedupes by video id; same video different moods/users -> one file.
|
||
- Manual add: new download -> attach; existing -> instant attach.
|
||
- Recommendation top-up: N active; add/reject refills; failed stays; refresh
|
||
does not replace ready; `recommendationCount=0` disables discovery.
|
||
- Reject during download cancels and GCs.
|
||
- GC keeps files referenced by another mood/session and deletes unreferenced.
|
||
- Radio: collection-only, recommendation-only mix, fallback, 1-song replay,
|
||
no duplicate in a batch, 0-song start error.
|
||
- Search: duration >10min hidden, malformed yt-dlp output, URL resolve.
|
||
- Auth/ownership regressions.
|
||
|
||
Client:
|
||
- Search results/add flow, existing song instant, badges.
|
||
- Recommendation add/reject/retry UI state.
|
||
- Play mood with zero songs shows error; queue and history still work.
|
||
- Offline playback from device downloads; cache version reset.
|
||
- Device download/delete/clear.
|
||
|
||
## 10. Current repo and deployment state
|
||
|
||
- Server latest commit: `4be502b` (plus this uncommitted doc). Image
|
||
`sha-4be502b`/`latest`; chart `0.2.4-sha.4be502b`.
|
||
- Client latest commit: `d9976a6`; CI green; Play internal release
|
||
`v0.1.1`, versionCode 2, package `win.tap_tap.audiomanager.client`.
|
||
- Client release automation: Gradle Play Publisher 3.13.0, tag `v*` ->
|
||
`publishBundle` to internal, `ResolutionStrategy.AUTO`; Gitea secrets set.
|
||
- Server deployment still uses the old mounted-library design; upgrading wipes
|
||
content and needs a PVC.
|
||
- Play App Signing is active (Google-generated key).
|
||
|
||
## 11. Risks / implementation notes
|
||
|
||
- Auto-download of up to 30 recommendations per mood can consume significant
|
||
disk/bandwidth even if the mood is never played. This is accepted.
|
||
- yt-dlp bot checks can fail downloads/searches; failed states and retry must
|
||
be robust, and search must return a clear 502.
|
||
- The 10-minute filter must apply to both search and discovery; longform is
|
||
gone.
|
||
- Cover art becomes song-keyed; the client must use `coverUrl(songId)`.
|
||
- Streaming must still support Range and transcoding for the Wasm/desktop
|
||
clients.
|
||
- Don't delete a file that an open playback session or another mood references.
|
||
- `recommendationCount` is clamped 0..30; `collectionPercent` 0..100.
|
||
- Search results are transient; no DB rows until add.
|
||
- A recommendation that is `added` while downloading must not turn into a
|
||
duplicate collection row.
|
||
- The migration is destructive by design; document it prominently.
|
||
|
||
## Implementation status (2026-11-17)
|
||
|
||
Phases 1-8 are implemented in both repositories.
|
||
|
||
### Server
|
||
|
||
- `V8__mood_first.sql` drops the mounted-library schema and creates
|
||
`songs`, `moods`, `mood_songs`, `mood_recommendations`, `download_jobs`,
|
||
playback tables and `song_affinity`. Users and device tokens survive.
|
||
The `mood_recommendations` table has an additional `rank` column so
|
||
promotion follows the discovery score order.
|
||
- `SongRepository` dedupes by `(source, externalId)` and is the only song table access.
|
||
- `MediaStore` owns `<MEDIA_DIR>/<source>-<externalId>/<title>.mp3` (legacy
|
||
YouTube folders without a prefix are still read); `SongIndexer` is shared by
|
||
the scanner and the downloader.
|
||
- `MoodRepository` implements the song collection, hidden `new` candidates,
|
||
active slots and the add/reject/retry lifecycle.
|
||
- `DiscoveryService` + `TopUpService` implement whole-collection discovery and
|
||
slot refills: text queries plus `MusicCatalog.discover` (Deezer related
|
||
artists, artist top tracks, album deep cuts; YouTube Music text only).
|
||
`TopUpService` coalesces work behind a mutex and can be triggered
|
||
fire-and-forget from API handlers and finished downloads. A song added after
|
||
the last pass marks discovery due again, so the pool follows the collection.
|
||
- `DownloadService` is a single global worker with `song` jobs outranking
|
||
`recommendation` jobs. It indexes immediately after moving the file.
|
||
- `MediaGcService` implements refcounted deletion (moods, active recommendations,
|
||
open sessions).
|
||
- The API surface is the one in section 4.8. Differences: search returns
|
||
`{"results": [...]}`, recommendation decisions are `add`/`reject`/`retry`, and
|
||
covers use `/songs/{id}/cover`. `/moods/{id}/songs` returns `202` with
|
||
`downloading: true` when a new video was queued.
|
||
- `AppConfig` is `port`, `dataDir`, `usersFile`, `ffmpegPath`, `ytDlpPath`,
|
||
`streamripPath`, `defaultSource`, `deezerArl`, `deezerQuality`,
|
||
`deezerApiBase`, `mediaDir`, `downloadDir`. `LibraryConfig` and the folder
|
||
APIs are deleted.
|
||
- `YtDlpSearch` searches `music.youtube.com` with the Songs filter and resolves
|
||
each hit, so results carry the canonical artist, album and duration.
|
||
`YtDlpDownloader` requests the Music watch URL first and falls back to
|
||
`www.youtube.com` for videos that are not on the Music host. If the Music
|
||
search itself fails, search falls back to `ytsearch`.
|
||
- Background loops: download worker (continuous), recommendation top-up
|
||
(hourly), media GC (hourly), startup scan.
|
||
- Chart 0.3.0 uses one `/data` PVC, `MEDIA_DIR=/data/media`, no hostPath, no
|
||
library ConfigMap and no init container.
|
||
- V9 adds `source` to songs, moods, recommendations and download jobs and
|
||
renames `video_id` to `external_id`; existing rows are YouTube.
|
||
- `MusicCatalogs` dispatches search/resolve by source (`DeezerSearch` +
|
||
`YtDlpSearch`). `SourceDownloaders` dispatches downloads (`DeezerDownloader`
|
||
via streamrip + `YtDlpDownloader`).
|
||
- Deezer is the default for new moods; every mood stores its own source and
|
||
can switch it, which clears the active recommendation pool and refills it.
|
||
- Chart 0.4.0 adds `DEFAULT_SOURCE`, `DEEZER_*` and an optional ARL secret.
|
||
- Tests: 94 server tests, 66-step smoke test with fake `yt-dlp`, `rip` and a
|
||
fake Deezer API (including the artist graph).
|
||
|
||
### Client
|
||
|
||
- Models, `ApiClient`, `AppCache` (version 3) and `AppStore` match the new API.
|
||
- Screens are `Moods | MoodDetail | Search | Downloads | Settings`.
|
||
`LibraryScreen`, longform UI, seed management and global shuffle are gone.
|
||
- Search supports a target-mood picker, a **Deezer / YouTube Music** source
|
||
selector, downloaded badges and paste-a-URL.
|
||
- Mood detail shows songs, add music, recommendation states (Add / Not
|
||
interested / Retry), next batch and the new options.
|
||
- Playback, sleep timer, queue editing, Android media session and device
|
||
downloads are unchanged apart from song-keyed covers.
|
||
- Tests: 17 client tests; desktop, Android debug and Wasm compile.
|
||
|
||
### Known follow-ups
|
||
|
||
- Real-device Android background playback and desktop audio checks still need a
|
||
machine with an audio device.
|
||
- Automatic downloads are bounded by `recommendationCount` but can still consume
|
||
noticeable disk/bandwidth for unplayed moods.
|
||
- yt-dlp bot checks remain an operational risk; failed rows keep Retry.
|
||
- A Deezer Free ARL is limited to 128 kbps and ARL downloads are outside the
|
||
public API terms. A Premium ARL enables 320 kbps MP3 (`DEEZER_QUALITY=1`).
|