Files
AudioManager/docs/design/mood-first.md
T

686 lines
32 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 stores up to a bounded pool of `new` candidates (e.g. 60) from the
collection's artists/titles + `query` + `genres` + mood name. Exclude video
ids already in `mood_songs`, `added` or `rejected`.
- `topUp(mood, force)`:
1. Count active = `downloading + ready + failed`.
2. If `active >= recommendationCount`, stop.
3. Promote the best `new` candidates to `downloading` and enqueue
`download_jobs` until the count is met.
4. If more slots remain and (`force || discoveryDue(mood)`), run discovery,
then promote again.
- `force = true` on user add/reject/retry and on the explicit refresh action.
Coalesce per-mood discovery with an in-flight guard. Background passes use
`force = false` and respect `refreshHours`.
- `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.
### 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 collection-based discovery and
slot refills. `TopUpService` coalesces work behind a mutex and can be triggered
fire-and-forget from API handlers.
- `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: 83 server tests, 64-step smoke test with fake `yt-dlp`, `rip` and a
fake Deezer API.
### 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`).