kami
130 lines
6.9 KiB
Markdown
130 lines
6.9 KiB
Markdown
# music — recommendation / vibe engine spec
|
|
|
|
Layers on top of core (spec 03). Handles enrichment (MusicBrainz + Last.fm), the vibe-endless-queue, candidate lifecycle, and the dislike → delayed-delete flow. Acquisition is a pluggable hook — the engine never fetches copyrighted audio itself.
|
|
|
|
## External providers
|
|
- **MusicBrainz** (no key, rate-limited 1 req/s, set a proper User-Agent): canonical recording/artist/release MBIDs, genres/tags. Used during enrichment to stamp `mbid` and genre data.
|
|
- **Last.fm** (free API key required): `track.getSimilar`, `artist.getSimilar`, `tag.getTopTracks`. Drives recommendations + vibe-queue.
|
|
- Store the **recommendation source** per candidate (`rec_source` on tracks: `lastfm` | `musicbrainz`) so feedback can be attributed.
|
|
- Respect rate limits: queue external calls, cache responses in sqlite.
|
|
|
|
```sql
|
|
CREATE TABLE IF NOT EXISTS mb_cache (
|
|
key TEXT PRIMARY KEY, -- e.g. "recording:<artist>:<title>"
|
|
payload TEXT NOT NULL, -- JSON
|
|
fetched_at TEXT NOT NULL
|
|
);
|
|
|
|
CREATE TABLE IF NOT EXISTS lastfm_cache (
|
|
key TEXT PRIMARY KEY, -- e.g. "similar:<mbid|artist-title>"
|
|
payload TEXT NOT NULL,
|
|
fetched_at TEXT NOT NULL
|
|
);
|
|
|
|
-- candidate dislike lifecycle
|
|
CREATE TABLE IF NOT EXISTS dislikes (
|
|
track_id INTEGER PRIMARY KEY REFERENCES tracks(id) ON DELETE CASCADE,
|
|
disliked_at TEXT NOT NULL,
|
|
warn_after TEXT NOT NULL, -- disliked_at + grace period ("a couple days")
|
|
warned_at TEXT, -- set when reminder fired
|
|
delete_after TEXT, -- warned_at + 24h
|
|
state TEXT NOT NULL -- 'hidden' | 'warned' | 'deleted'
|
|
);
|
|
|
|
CREATE TABLE IF NOT EXISTS feedback (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
track_id INTEGER,
|
|
rec_source TEXT, -- which provider suggested it
|
|
action TEXT NOT NULL, -- 'promoted' | 'disliked' | 'skipped'
|
|
at TEXT NOT NULL
|
|
);
|
|
```
|
|
|
|
## Enrichment
|
|
- After core indexing, a background enrichment pass fills missing `mbid`, `genre`, artist `genres`, artist `image_path`:
|
|
- MusicBrainz lookup by artist+title → recording MBID + tags.
|
|
- Last.fm `artist.getInfo` / `track.getInfo` for tags + similar seeds; cache.
|
|
- Throttled, cached, resumable. Never blocks playback.
|
|
|
|
## Recommendation / vibe queue
|
|
```
|
|
GET /api/vibe?seed_track_id=&limit= -> ordered vibe queue (track ids)
|
|
GET /api/vibe/from-genre?genre=&limit=
|
|
```
|
|
Algorithm:
|
|
1. Seed = current track / chosen track / genre.
|
|
2. Pull similar from Last.fm (`track.getSimilar`, `artist.getSimilar`, `tag.getTopTracks`), cached.
|
|
3. Score each candidate against the **owned library**:
|
|
- +score if artist/album already owned, genre overlap, similar to favorites, low recent-play (freshness), not disliked.
|
|
4. **Mix**: vibe queue interleaves owned tracks with promoted-from-recommendation tracks — recommendations are NOT front-loaded; they're shuffled into the stream so it feels organic.
|
|
5. Candidates **not yet owned** → enter the candidate pipeline (below) rather than playing immediately.
|
|
|
|
## Candidate lifecycle (acquisition)
|
|
- Hard cap: **max 5 candidates in probation at once** (`tracks.probation=1`). Engine won't request new acquisitions beyond the cap.
|
|
- When the engine wants to surface an unowned suggestion, it calls the acquisition hook:
|
|
|
|
```kotlin
|
|
// or python equivalent — defined seam, implemented by the operator
|
|
interface AcquisitionProvider {
|
|
/** Fetch audio for a candidate. Return the local file path on success, null to skip.
|
|
* The engine does NOT care where the bytes come from. */
|
|
suspend fun acquire(candidate: TrackCandidate): AcquiredFile?
|
|
}
|
|
|
|
data class TrackCandidate(
|
|
val title: String,
|
|
val artist: String,
|
|
val album: String?,
|
|
val mbid: String?,
|
|
val recSource: String, // lastfm | musicbrainz
|
|
)
|
|
data class AcquiredFile(val path: String)
|
|
```
|
|
- Default shipped impl: `NoopAcquisitionProvider` (returns null → candidate stays metadata-only, never plays). Operator wires a real one (bandcamp purchase dl, FMA/Jamendo CC, internet archive, personal rips, etc.).
|
|
- On successful acquire: file lands in music root, indexed as a track with `probation=1`, `source='recommendation'`, `rec_source` set, hidden from normal library lists (filtered by `probation=0`) but eligible to appear mixed into the **vibe queue**.
|
|
|
|
### Promotion
|
|
- A probation track that gets played and **not disliked** (passes the play-completion threshold) → `probation=0`, `source` stays `recommendation` for analytics but it's now full library, eligible as a future recommendation seed. Log `feedback(action='promoted')`.
|
|
|
|
## Dislike → delayed delete flow
|
|
Exact lifecycle:
|
|
1. **User dislikes a track** → insert/[update] `dislikes` row: `state='hidden'`, `disliked_at=now`, `warn_after=now + GRACE` (GRACE = "a couple days", e.g. 48h). Track is **hidden** from library + queues immediately. **File stays on disk.** Also `feedback(action='disliked')`.
|
|
2. **Reminder**: a periodic sweep finds `state='hidden'` rows past `warn_after` → fire notification (ntfy) / surface a toast in UI: *"You disliked '<track>'. It will be deleted in 24h — are you sure?"* Set `warned_at=now`, `delete_after=now + 24h`, `state='warned'`.
|
|
3. **Final**: sweep finds `state='warned'` rows past `delete_after` where the dislike still stands → **delete file from fs + all db rows** (calls core `DELETE /api/track`). Set `state='deleted'` (or just remove the dislike row since the track row is gone).
|
|
4. **Un-dislike** at any point before final deletion → remove `dislikes` row, un-hide the track. It's spared.
|
|
|
|
```
|
|
POST /api/dislike/{track_id} -> start lifecycle (hide + schedule)
|
|
DELETE /api/dislike/{track_id} -> un-dislike (spare it), un-hide
|
|
GET /api/dislikes -> pending dislikes + their states/timers
|
|
POST /api/dislikes/sweep -> manual trigger of the sweep (also runs on a timer)
|
|
```
|
|
|
|
### Sweep scheduler
|
|
- A background timer (e.g. hourly) runs the sweep: hidden→warned (fires ntfy), warned→deleted. Hourly granularity is fine for day-scale timers.
|
|
- ntfy integration: POST to the ntfy topic (reuse the server's ntfy from the parked list) for the reminder.
|
|
|
|
## Feedback loop (future-facing, stub now)
|
|
- `feedback` table records promoted/disliked/skipped with `rec_source`.
|
|
- Later: weight providers/genres by acceptance rate (promoted vs disliked) to bias future recommendations. v1 just records; scoring tweak is a later iteration.
|
|
|
|
## Endpoints summary (this layer)
|
|
```
|
|
GET /api/vibe
|
|
GET /api/vibe/from-genre
|
|
POST /api/dislike/{id}
|
|
DELETE /api/dislike/{id}
|
|
GET /api/dislikes
|
|
POST /api/dislikes/sweep
|
|
POST /api/enrich -> manual enrichment pass
|
|
GET /api/recommendations -> current probation candidates + why (rec_source, seed)
|
|
```
|
|
|
|
## Config / prefs
|
|
- `lastfm_api_key` (prefs or env)
|
|
- `mb_user_agent` (required by MusicBrainz)
|
|
- `dislike_grace_hours` (default 48)
|
|
- `dislike_final_hours` (default 24)
|
|
- `max_candidates` (default 5)
|
|
- `ntfy_topic_url` for reminders
|