- V9 adds source/external_id to songs, moods, recommendations and jobs - Deezer public catalog for search, related album covers and metadata - streamrip downloader configured with DEEZER_ARL, 128/320 MP3 - per-mood source selector; switching clears and refills recommendations - keep YouTube Music as a full second catalog and downloader - media layout <source>-<externalId>, legacy YouTube folders still read - Docker/streamrip install, chart ARL secret, docs and dual-source smoke test
32 KiB
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
collectionPercentit 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: statesdownloading,ready,failed.newcandidates are a hidden pool used to refill slots.addedandrejectedare 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
failedwith Retry / Not interested; it counts as a slot until the user acts. It is never silently replaced. refreshHoursis 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
recommendationCountcounts downloading + ready + failed; add/reject frees a slot and the server refills it.- 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.
- Failed downloads stay visible with Retry / Not interested.
refreshHoursonly throttles automatic discovery/top-up; it never replaces a ready recommendation.- Small pools loop/replay least-recently played instead of going silent.
seedPercentbecomescollectionPercent; recommendation plays count in history and affinity like songs.- Mood options: name, description, query, genres, collectionPercent,
recommendationCount (default 10, max 30), refreshHours.
targetSize,ytEnabledare removed. - No accept step. Rows show download state, Add to mood, Not interested; failed rows add Retry.
- 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.
- Library and Longform tabs are removed; Downloads stays for offline files. Global Shuffle all is removed; playback stays per mood.
- Migration: full wipe. Songs, moods, recommendations, downloads and longform data are dropped. No import from the old mount.
- Existing moods are wiped with the content.
- Chart uses a PVC for
/data(media at/data/media); music hostPath,library.yaml, user folder lists,DOWNLOADS_ENABLEDandDOWNLOAD_FOLDER_IDdisappear. - 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. - Recommendations are downloaded up to the configured count even if the mood is never played.
- Backups are external; no export/import feature and no offline CLI import.
- 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.
- 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>/downloadsor<media>/.tmp; must be on the same filesystem as the final path for atomic moves. - Layout:
<media>/<source>-<externalId>/<sanitized-title>.mp3plus<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.
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
newcandidates (e.g. 60) from the collection's artists/titles +query+genres+ mood name. Exclude video ids already inmood_songs,addedorrejected. topUp(mood, force):- Count active =
downloading + ready + failed. - If
active >= recommendationCount, stop. - Promote the best
newcandidates todownloadingand enqueuedownload_jobsuntil the count is met. - If more slots remain and (
force || discoveryDue(mood)), run discovery, then promote again.
- Count active =
force = trueon user add/reject/retry and on the explicit refresh action. Coalesce per-mood discovery with an in-flight guard. Background passes useforce = falseand respectrefreshHours.recommendationCount = 0stops discovery and downloads for the mood.- On download success:
downloading->readywithsong_id.added(user added while downloading) -> insertmood_songs, keepadded, do not create a duplicate.rejected-> delete the file if unreferenced.
- On final download failure:
failedwitherror; keep the slot. - Add: if
ready, attach the song; ifdownloading, markaddedand attach when the job completes; insertmood_songswith originrecommendation; top up. - Reject: mark
rejected, cancel the job, GC, top up. - Retry:
failed->downloading, reset the job, top up. newcandidates are not shown in the client.
4.4 Download pipeline
download_jobsare global;kind=song(manual add) has higher priority thankind=recommendation. Claim bypriority 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:
- Claim a job.
- Resolve target
<media>/<source>-<externalId>/<title>.mp3. - If the song exists, finish.
- Download to temp with yt-dlp/streamrip; move atomically; index the file (tags/cover) and upsert the song by video id.
- Apply the job outcome (song attach or recommendation state).
- 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) andreadyrecommendation 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 inpickMixed. 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
pickDiverseif it becomes dead code.
4.6 File GC
A song is referenced by:
- any
mood_songsrow; - any
mood_recommendationsrow withsong_id = songand state indownloading|ready|added|failed(addedalso hasmood_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 withsource,externalId,title,artist,album,duration,thumbnail,songId?,downloaded,inMood.sourcefalls back to the mood's source, thenDEFAULT_SOURCE.- Hide results with
duration > 600seconds and< 30. POST /api/v1/moods/{id}/songsacceptssongId(existing download),source+externalId, orurl. 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:
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.yamlkeepsname,password,admin. Removefolders; accept and ignore existingfolderskeys 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
LibraryScreenand all longform UI.
5.2 State and store
AppStateremove:library,longform,longformResults,longformProgress,musicResults,searchResults(replace withsearchResults: List<SearchResult>+searchTargetMoodId), longform progress.CachedStateversion 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;
refreshAllfetches moods only; selected mood detail on open/refresh;- create/update/delete mood;
addSong,removeSong,addRecommendation,rejectRecommendation,retryRecommendation,refreshRecommendations;searchRemote(query)with debounce and cancellation;playMooduses 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; addCurrentToMoodworks for collection songs viasongId.
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.yamlare 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). RemovelibraryConfigPath,downloadsEnabled,downloadFolderId.Application.kt: users only; scanner overmediaDir; 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,fsGroup10001, no hostPath/library ConfigMap, noprepare-importsinit container; DATA_DIR=/data,MEDIA_DIR=/data/media;- keep users Secret, probes, resources; add persistence values;
- README deployment section rewritten.
- one PVC for
- Nix shell: no library config;
DATA_DIR=./data. - Docker:
yt-dlp,ffmpeg, Python 3 andstreamrip(providesrip). - Smoke test: rewrite for mood creation, search stub or seeded songs, add,
recommendations, playback. A fake
yt-dlpscript 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.
MediaScannerover media root, video id from path.CoverArtServicesong-keyed.YtDlpDownloadertarget path; direct indexing after move.DownloadServiceattach-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
DiscoveryServiceinputs from collection; storenew; no library matching; 10-minute filter.RecommendationTopUpService(or methods inMoodRepository/DiscoveryService).RadioServicecollection + 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=0disables 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). Imagesha-4be502b/latest; chart0.2.4-sha.4be502b. - Client latest commit:
d9976a6; CI green; Play internal releasev0.1.1, versionCode 2, packagewin.tap_tap.audiomanager.client. - Client release automation: Gradle Play Publisher 3.13.0, tag
v*->publishBundleto 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.
recommendationCountis clamped 0..30;collectionPercent0..100.- Search results are transient; no DB rows until add.
- A recommendation that is
addedwhile 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.sqldrops the mounted-library schema and createssongs,moods,mood_songs,mood_recommendations,download_jobs, playback tables andsong_affinity. Users and device tokens survive. Themood_recommendationstable has an additionalrankcolumn so promotion follows the discovery score order.SongRepositorydedupes by(source, externalId)and is the only song table access.MediaStoreowns<MEDIA_DIR>/<source>-<externalId>/<title>.mp3(legacy YouTube folders without a prefix are still read);SongIndexeris shared by the scanner and the downloader.MoodRepositoryimplements the song collection, hiddennewcandidates, active slots and the add/reject/retry lifecycle.DiscoveryService+TopUpServiceimplement collection-based discovery and slot refills.TopUpServicecoalesces work behind a mutex and can be triggered fire-and-forget from API handlers.DownloadServiceis a single global worker withsongjobs outrankingrecommendationjobs. It indexes immediately after moving the file.MediaGcServiceimplements refcounted deletion (moods, active recommendations, open sessions).- The API surface is the one in section 4.8. Differences: search returns
{"results": [...]}, recommendation decisions areadd/reject/retry, and covers use/songs/{id}/cover./moods/{id}/songsreturns202withdownloading: truewhen a new video was queued. AppConfigisport,dataDir,usersFile,ffmpegPath,ytDlpPath,streamripPath,defaultSource,deezerArl,deezerQuality,deezerApiBase,mediaDir,downloadDir.LibraryConfigand the folder APIs are deleted.YtDlpSearchsearchesmusic.youtube.comwith the Songs filter and resolves each hit, so results carry the canonical artist, album and duration.YtDlpDownloaderrequests the Music watch URL first and falls back towww.youtube.comfor videos that are not on the Music host. If the Music search itself fails, search falls back toytsearch.- Background loops: download worker (continuous), recommendation top-up (hourly), media GC (hourly), startup scan.
- Chart 0.3.0 uses one
/dataPVC,MEDIA_DIR=/data/media, no hostPath, no library ConfigMap and no init container. - V9 adds
sourceto songs, moods, recommendations and download jobs and renamesvideo_idtoexternal_id; existing rows are YouTube. MusicCatalogsdispatches search/resolve by source (DeezerSearch+YtDlpSearch).SourceDownloadersdispatches downloads (DeezerDownloadervia 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: 81 server tests, 64-step smoke test with fake
yt-dlp,ripand a fake Deezer API.
Client
- Models,
ApiClient,AppCache(version 3) andAppStorematch 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
recommendationCountbut 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).