feat: rotate recommendations after a few plays
CI / chart (push) Successful in 3s
CI / test (push) Successful in 2m4s
CI / chart-push (push) Successful in 3s
CI / image (push) Failing after 6m21s

- V12 rebuilds mood_recommendations with a rotated state, play_count and
  rotated_at, plus a per-mood recommendation_rotation_plays (default 3)
- count a play when a session reports started; retire the slot at the limit
  and let TopUpService refill it, with discovery only when the pool is empty
- add POST /moods/{id}/recommendations/rotate for the All new action, which
  retires every active slot and forces discovery
- turned a rotated slot's late download completion into REJECTED so it cannot
  reappear as ready
- revive rotated slots after a 30-day cooldown to avoid draining the catalog
- expose playCount and recommendationRotationPlays in the API, chart 0.6.0
This commit is contained in:
TapTap committed 2026-11-22 17:31:28 +00:00
1 parent 44b75c4d4d
commit a3c5da559b
15 files changed
+507 -8

No files matched your search

+14 -3
View File
@@ -46,6 +46,12 @@ keeps playing without a mounted music library.
- **Add / Not interested are permanent.** Adding promotes a recommendation into
the collection. Rejecting is remembered per mood. Both free a slot and the
server refills it.
- **Picks rotate after a few plays.** `recommendationRotationPlays` (0–100,
default 3) retires an active recommendation once it has been started that many
times and fills its slot from the hidden pool. `0` turns automatic rotation
off. Retired tracks rest for 30 days, then may be offered again; this is a
cooldown, not a rejection. The "All new" action retires every active pick at
once, which is what you want when Refresh keeps returning the same songs.
- **Playback mixes both pools.** Every queue slot rolls `collectionPercent`;
the rest comes from ready recommendations. An empty pool falls back to the
other one. Small pools replay least-recently-played tracks.
@@ -176,7 +182,7 @@ Media URLs may use `?token=` because HTML audio and images cannot send headers.
| Method | Path | Purpose |
|---|---|---|
| `GET` | `/moods` | List the user's moods |
| `POST` | `/moods` | Create `{name,description,query,genres,source,collectionPercent,recommendationCount,refreshHours}` |
| `POST` | `/moods` | Create `{name,description,query,genres,source,collectionPercent,recommendationCount,recommendationRotationPlays,refreshHours}` |
| `GET` | `/moods/{id}` | Mood detail: songs, active recommendations, download status |
| `PATCH` | `/moods/{id}` | Update options |
| `DELETE` | `/moods/{id}` | Delete mood, detach songs and run GC |
@@ -185,6 +191,7 @@ Media URLs may use `?token=` because HTML audio and images cannot send headers.
| `DELETE` | `/moods/{id}/songs/{songId}` | Detach a song |
| `GET` | `/moods/{id}/recommendations` | Active recommendation slots |
| `POST` | `/moods/{id}/recommendations/refresh` | Force discovery + top-up |
| `POST` | `/moods/{id}/recommendations/rotate` | Retire every active pick and fill the slots with different tracks |
| `POST` | `/moods/{id}/recommendations/{externalId}/add` | Add to the collection |
| `POST` | `/moods/{id}/recommendations/{externalId}/reject` | Hide permanently |
| `POST` | `/moods/{id}/recommendations/{externalId}/retry` | Retry a failed download |
@@ -270,8 +277,9 @@ album and cover art, so the indexer can derive the metadata from the file.
A file is deleted only when it has no references from `mood_songs`, an active
recommendation (`downloading`, `ready`, `added`, `failed`), or an open playback
session. GC runs after removals, after rejections, after mood deletion, and
hourly.
session. Rotated and rejected slots do not keep a file alive, so a retired pick
disappears once no open session still queues it. GC runs after removals, after
rejections, after mood deletion, and hourly.
## Database
@@ -285,6 +293,9 @@ SQLite in WAL mode. Migrations are Flyway scripts under
- **V9 adds sources.** It renames `video_id` to `external_id` and adds a
`source` column to songs, moods, recommendations and download jobs. Existing
rows become `youtube`.
- **V12 adds rotation.** It rebuilds `mood_recommendations` to allow the
`rotated` state and adds `play_count`, `rotated_at` and the mood-level
`recommendation_rotation_plays` (default 3).
- There is no import from an old media directory. Back up externally and start
with an empty `MEDIA_DIR`.