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

28 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.
  • All content enters the server by downloading from YouTube through yt-dlp.
  • Search is a remote YouTube-Music-style search. 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 YouTube video id 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 YouTube video id; the same track from two videos is two songs. 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 keep; change music length to 45..600s; 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 <videoId>/<title>.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>/<videoId>/<sanitized-title>.mp3 plus <media>/cover-cache/... or a song-keyed cover derived from embedded art. The first path segment is the YouTube video id, which makes startup scans deterministic and independent of tags.
  • Song id: sg- + SHA-256 prefix of "yt:<videoId>".
  • MP3 only (yt-dlp -x --audio-format mp3 --audio-quality 0), embedded metadata and thumbnail.
  • The scanner walks MEDIA_DIR, extracts videoId 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,
  video_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,
  video_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, video_id)
)

download_jobs(
  id TEXT PRIMARY KEY,
  video_id TEXT NOT NULL,
  mood_id TEXT NOT NULL REFERENCES moods(id) ON DELETE CASCADE,
  kind TEXT NOT NULL CHECK (kind IN ('song', 'recommendation')),
  state TEXT NOT NULL DEFAULT 'queued'
    CHECK (state IN ('queued', 'downloading', 'done', 'failed')),
  priority INTEGER NOT NULL DEFAULT 0,
  attempts INTEGER NOT NULL DEFAULT 0,
  error TEXT,
  song_id TEXT REFERENCES songs(id) ON DELETE SET NULL,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
)

playback_sessions(id, user_name, mood_id, next_position, created_at, last_seen_at, closed_at)
playback_session_items(session_id, position, song_id, state, queued_at, updated_at)
song_affinity(user_name, song_id, completions, skips, last_event_at)

Drop: music_folders, artists, albums, album_artists, song_artists, song_genres, album_genres, artist_genres, mood_seeds, library_tombstones, longform_progress, user_song_state, user_stars, bookmarks, old download_jobs, old mood_recommendations, old moods, old songs.

DatabaseFactory.normalizeLegacyMoodStates stays: an old V4 DB must still pass V5/V6/V7 before V8 can wipe it.

4.3 Recommendation lifecycle

States: new (hidden candidate pool), downloading, ready, failed, added, rejected.

  • Discovery stores up to a bounded pool of new candidates (e.g. 60) from the collection's artists/titles + query + genres + mood name. Exclude video ids already in mood_songs, added or rejected.
  • topUp(mood, force):
    1. Count active = downloading + ready + failed.
    2. If active >= recommendationCount, stop.
    3. Promote the best new candidates to downloading and enqueue download_jobs until the count is met.
    4. If more slots remain and (force || discoveryDue(mood)), run discovery, then promote again.
  • force = true on user add/reject/retry and on the explicit refresh action. Coalesce per-mood discovery with an in-flight guard. Background passes use force = false and respect refreshHours.
  • recommendationCount = 0 stops discovery and downloads for the mood.
  • On download success:
    • downloading -> ready with song_id.
    • added (user added while downloading) -> insert mood_songs, keep added, do not create a duplicate.
    • rejected -> delete the file if unreferenced.
  • On final download failure: failed with error; keep the slot.
  • Add: if ready, attach the song; if downloading, mark added and attach when the job completes; insert mood_songs with origin recommendation; top up.
  • Reject: mark rejected, cancel the job, GC, top up.
  • Retry: failed -> downloading, reset the job, top up.
  • new candidates are not shown in the client.

4.4 Download pipeline

  • download_jobs are global; kind=song (manual add) has higher priority than kind=recommendation. Claim by priority DESC, created_at ASC.
  • Before downloading, check songs.video_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>/<videoId>/<title>.mp3.
    3. If the song exists, finish.
    4. Download to temp with yt-dlp; move atomically into the target dir; 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 <videoId> 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=... -> YT results with videoId,title, artist,album,duration,thumbnail,songId?,downloaded.
  • Hide results with duration > 600 seconds (and probably < 30).
  • POST /api/v1/moods/{id}/songs accepts either songId (existing download) or download metadata, or url. A URL is resolved with yt-dlp (--dump-single-json --no-playlist) before enqueueing.
  • Search requires auth; it is a server-side yt-dlp call, so use a 120s client timeout and return 502 with the yt-dlp error 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/{videoId}/add
POST   /api/v1/moods/{id}/recommendations/{videoId}/reject
POST   /api/v1/moods/{id}/recommendations/{videoId}/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, videoId, 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(videoId, title, artist, album, duration, thumbnail, state,
                  song?, download?, firstSeen, lastSeen)
SearchResultDto(videoId, 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: no extra packages; yt-dlp and ffmpeg already present.
  • 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.