Files
AudioManager/docs/design/mood-first.md
T
TapTap 91312faa1c
CI / chart (push) Successful in 3s
CI / test (push) Successful in 2m6s
CI / chart-push (push) Successful in 3s
CI / image (push) Successful in 3m31s
feat: per-track loudness normalization and server audio info
- measure downloads with ffmpeg's EBU R128 filter and store gain/LUFS
- backfill the existing library one file at a time
- expose gain on songs and a /info endpoint for source quality
- chart knobs LOUDNESS_ENABLED and LOUDNESS_TARGET_LUFS
2026-11-19 16:38:21 +00:00

38 KiB
Raw Blame History

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.
  • 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.

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:

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).