# 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 `-/.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. - Loudness: after indexing, ffmpeg measures `input_i`/`input_tp` with `loudnorm`. `gain_db = min(target - input_i, truePeak - input_tp)` is stored; clients apply it per track. New downloads are measured inline, the existing library is backfilled one file at a time. `LOUDNESS_ENABLED` and `LOUDNESS_TARGET_LUFS` control it. - 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 **radio** (`/artist/{id}/radio`, the platform's own mix) and top tracks; up to 2 of those artists' related artists -> their top tracks; up to 2 collection albums -> album deep cuts. YouTube Music runs the `RDAMVM<videoId>` watch-playlist radio for the 2 newest collection songs, which is the same queue its player builds (`yt-dlp --flat-playlist`), so it also returns real recommendations. - 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 (platform radio `2.0`, 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`. - A recording is deduplicated by `(artist, title)` as well as by external id, so two uploads of a song already in the mood do not both enter the pool. - 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 | the platform's own radio (Deezer artist radio, YouTube `RDAMVM`) + catalog graph + 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 platforms' own radio endpoints. Spotify is not an option: its `/v1/recommendations`, related artists, audio features and audio analysis were removed for new apps on 2024-11-27, and its terms forbid training on Spotify content. ### 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: 97 server tests, 67-step smoke test with fake `yt-dlp`, `rip` and a fake Deezer API (including the artist graph and both radio paths). ### Client - Models, `ApiClient`, `AppCache` (version 3 + separate client settings file) and `AppStore` match the new API. - Screens are `Moods | MoodDetail | MoodSettings | Search | Downloads | Settings | NowPlaying`. `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). The preview/next-batch section and the inline settings form are gone: mood settings (including source and the offline switch) live on a dedicated screen, with Delete at the bottom. - **0.4.0 playback**: Android's `MediaSessionService` owns a Media3 timeline, so notification/headset next/back and gapless playback use real media items. Previous keeps the 2 s restart rule. The app mirrors the index, appends the next server batch and still reports skipped/completed events. - **Audio**: server gain is applied by an Android PCM `AudioProcessor` (boost and attenuation) and by the desktop mixer; the full-screen player shows source and bitrate. Android has an optional 0–8 s fade between tracks. - **Offline moods**: a per-mood switch downloads every song and keeps new additions in sync on unmetered networks, three at a time. - **Sleep timer** adds "Finish this track"; the full-screen player shows large artwork, transport, add-to-mood, queue and Up next. - Tests: 21 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`).