From 408b3c8308f6baac327699410cff9f8a3878a964 Mon Sep 17 00:00:00 2001 From: vicrodh <103399283+vicrodh@users.noreply.github.com> Date: Sat, 27 Jun 2026 02:37:32 -0600 Subject: [PATCH] feat(reco): external-recommendations engine (Last.fm + ListenBrainz -> Qobuz) New frontend-agnostic crate qbz-external-reco: blends Last.fm + ListenBrainz recommendation signals into the Discover "External Recommendations" carousels, validating every candidate against the Qobuz catalog (ISRC direct -> MusicBrainz inc=isrcs bridge -> fuzzy text scorer, gated) before display. Four carousels (C1 similar artists / C2 similar tracks you haven't heard, C3 listened-but-not- recently, C4 deep cuts from known artists) capped at 20 with daily rotation over a larger cache-backed pool, plus a Qobuz-editorial cold-start fallback (top albums + artists) when no external source is connected. Round-robin blend across sources. Resolution cache (per-user SQLite, 30d hits / 7d misses, WAL). Supporting public read methods added to qbz-integrations: - Last.fm: get_top_artists / get_top_tracks / get_loved_tracks / get_recent_tracks / get_similar_tracks (public reads via the Cloudflare proxy). - ListenBrainz: get_cf_recommendations / get_recent_listens / get_metadata_recordings (204/404 -> empty, never error). - MusicBrainz: get_recording_isrcs (the MBID -> ISRC bridge). Engine is headless and unit-tested (matching + cache); no qbz-ui dependency. cc --- crates/Cargo.lock | 15 + crates/Cargo.toml | 1 + crates/qbz-external-reco/Cargo.toml | 25 + crates/qbz-external-reco/src/cache.rs | 154 +++++ crates/qbz-external-reco/src/carousels.rs | 546 ++++++++++++++++++ crates/qbz-external-reco/src/lib.rs | 88 +++ crates/qbz-external-reco/src/matching.rs | 222 +++++++ crates/qbz-external-reco/src/types.rs | 103 ++++ crates/qbz-external-reco/src/validate.rs | 191 ++++++ crates/qbz-integrations/src/lastfm/client.rs | 466 ++++++++++++++- crates/qbz-integrations/src/lastfm/mod.rs | 4 +- crates/qbz-integrations/src/lastfm/models.rs | 45 ++ .../src/listenbrainz/client.rs | 299 ++++++++++ .../qbz-integrations/src/listenbrainz/mod.rs | 4 +- .../src/listenbrainz/models.rs | 51 ++ .../src/musicbrainz/client.rs | 19 + .../src/musicbrainz/models.rs | 8 + 17 files changed, 2236 insertions(+), 5 deletions(-) create mode 100644 crates/qbz-external-reco/Cargo.toml create mode 100644 crates/qbz-external-reco/src/cache.rs create mode 100644 crates/qbz-external-reco/src/carousels.rs create mode 100644 crates/qbz-external-reco/src/lib.rs create mode 100644 crates/qbz-external-reco/src/matching.rs create mode 100644 crates/qbz-external-reco/src/types.rs create mode 100644 crates/qbz-external-reco/src/validate.rs diff --git a/crates/Cargo.lock b/crates/Cargo.lock index 1efa4de08..00d6c289b 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -5596,6 +5596,21 @@ dependencies = [ "slint", ] +[[package]] +name = "qbz-external-reco" +version = "0.1.0" +dependencies = [ + "async-trait", + "futures-util", + "log", + "qbz-integrations", + "qbz-models", + "rusqlite", + "serde", + "serde_json", + "tokio", +] + [[package]] name = "qbz-i18n" version = "0.1.0" diff --git a/crates/Cargo.toml b/crates/Cargo.toml index 8b4e9176b..e0c6abff1 100644 --- a/crates/Cargo.toml +++ b/crates/Cargo.toml @@ -35,6 +35,7 @@ members = [ "qbz-i18n", "qbz-music-link", "qbz-reco", + "qbz-external-reco", ] [workspace.package] diff --git a/crates/qbz-external-reco/Cargo.toml b/crates/qbz-external-reco/Cargo.toml new file mode 100644 index 000000000..f86adde2c --- /dev/null +++ b/crates/qbz-external-reco/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "qbz-external-reco" +version.workspace = true +edition.workspace = true +license.workspace = true +description = "Frontend-agnostic external-recommendations engine (Last.fm + ListenBrainz -> Qobuz) for Discover" + +[dependencies] +qbz-integrations = { path = "../qbz-integrations" } +qbz-models = { path = "../qbz-models" } + +# Async +tokio = { workspace = true } +async-trait = { workspace = true } +futures-util = { workspace = true } + +# Serialization +serde = { workspace = true } +serde_json = { workspace = true } + +# Cache (per-user SQLite, WAL per ADR-002) +rusqlite = { version = "0.31", features = ["bundled"] } + +# Logging +log = { workspace = true } diff --git a/crates/qbz-external-reco/src/cache.rs b/crates/qbz-external-reco/src/cache.rs new file mode 100644 index 000000000..04aaa0e10 --- /dev/null +++ b/crates/qbz-external-reco/src/cache.rs @@ -0,0 +1,154 @@ +//! Resolved-recommendation -> Qobuz-id cache (per-user SQLite, WAL per ADR-002). +//! +//! Mirrors the `MusicBrainzCache` shape. Caches BOTH positive hits (a resolved +//! Qobuz id, TTL 30d) AND negative hits (a recommendation that does not exist on +//! Qobuz, TTL 7d) so an unfindable rec does not re-hammer the Qobuz search API +//! on every render. The connection is `!Sync`; wrap it in a `Mutex` for +//! concurrent validation (locks are brief and never held across `.await`). + +use rusqlite::{params, Connection, OptionalExtension}; +use std::path::Path; +use std::time::{SystemTime, UNIX_EPOCH}; + +/// TTL for positive (found) entries — 30 days. +const FOUND_TTL_SECS: i64 = 30 * 24 * 60 * 60; +/// TTL for negative (not-on-Qobuz) entries — 7 days. +const MISS_TTL_SECS: i64 = 7 * 24 * 60 * 60; + +/// A cache lookup outcome. +pub enum CacheLookup { + /// Resolved Qobuz id (track id as decimal string, or album id verbatim). + Found(String), + /// Previously resolved to "does not exist on Qobuz". + Negative, + /// Not cached (or expired) — caller must resolve live. + Miss, +} + +pub struct RecoCache { + conn: Connection, +} + +impl RecoCache { + /// Open (or create) the cache at `/external_reco_cache.db`. + pub fn open_at(base_dir: &Path) -> Result { + std::fs::create_dir_all(base_dir) + .map_err(|e| format!("Failed to create reco cache dir: {}", e))?; + let conn = Connection::open(base_dir.join("external_reco_cache.db")) + .map_err(|e| format!("Failed to open external reco cache: {}", e))?; + conn.execute_batch("PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;") + .map_err(|e| format!("Failed to enable WAL: {}", e))?; + conn.execute_batch( + "CREATE TABLE IF NOT EXISTS reco_qobuz_cache ( + key TEXT PRIMARY KEY, + kind TEXT NOT NULL, + qobuz_id TEXT, + found INTEGER NOT NULL, + fetched_at INTEGER NOT NULL + ); + CREATE INDEX IF NOT EXISTS idx_reco_qobuz_cache_fetched + ON reco_qobuz_cache(fetched_at);", + ) + .map_err(|e| format!("Failed to init reco cache schema: {}", e))?; + Ok(Self { conn }) + } + + fn now() -> i64 { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|d| d.as_secs() as i64) + .unwrap_or(0) + } + + /// Look up a resolution by key, honoring the per-regime TTL. + pub fn get(&self, key: &str) -> CacheLookup { + let row: Option<(i64, Option, i64)> = self + .conn + .query_row( + "SELECT found, qobuz_id, fetched_at FROM reco_qobuz_cache WHERE key = ?", + params![key], + |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)), + ) + .optional() + .unwrap_or(None); + + match row { + Some((found, qobuz_id, fetched_at)) => { + let ttl = if found != 0 { FOUND_TTL_SECS } else { MISS_TTL_SECS }; + if Self::now() - fetched_at > ttl { + return CacheLookup::Miss; // expired + } + if found != 0 { + match qobuz_id { + Some(id) if !id.is_empty() => CacheLookup::Found(id), + _ => CacheLookup::Miss, + } + } else { + CacheLookup::Negative + } + } + None => CacheLookup::Miss, + } + } + + /// Store a resolution. `qobuz_id = None` records a negative (not-on-Qobuz). + pub fn put(&self, key: &str, kind: &str, qobuz_id: Option<&str>) { + let found = if qobuz_id.is_some() { 1 } else { 0 }; + let _ = self.conn.execute( + "INSERT OR REPLACE INTO reco_qobuz_cache (key, kind, qobuz_id, found, fetched_at) + VALUES (?, ?, ?, ?, ?)", + params![key, kind, qobuz_id, found, Self::now()], + ); + } + + /// Drop expired rows (both regimes). Safe to call opportunistically. + pub fn cleanup_expired(&self) -> usize { + let now = Self::now(); + let found = self + .conn + .execute( + "DELETE FROM reco_qobuz_cache WHERE found = 1 AND fetched_at <= ?", + params![now - FOUND_TTL_SECS], + ) + .unwrap_or(0); + let miss = self + .conn + .execute( + "DELETE FROM reco_qobuz_cache WHERE found = 0 AND fetched_at <= ?", + params![now - MISS_TTL_SECS], + ) + .unwrap_or(0); + found + miss + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn tmp_dir(tag: &str) -> std::path::PathBuf { + let nonce = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap() + .as_nanos(); + std::env::temp_dir().join(format!("qbz-extreco-{tag}-{}-{nonce}", std::process::id())) + } + + #[test] + fn positive_negative_and_miss() { + let dir = tmp_dir("cache"); + let cache = RecoCache::open_at(&dir).expect("open"); + assert!(matches!(cache.get("k1"), CacheLookup::Miss)); + + cache.put("k1", "track", Some("12345")); + match cache.get("k1") { + CacheLookup::Found(id) => assert_eq!(id, "12345"), + _ => panic!("expected Found"), + } + + cache.put("k2", "track", None); + assert!(matches!(cache.get("k2"), CacheLookup::Negative)); + + let _ = std::fs::remove_dir_all(dir); + } +} diff --git a/crates/qbz-external-reco/src/carousels.rs b/crates/qbz-external-reco/src/carousels.rs new file mode 100644 index 000000000..b2b4be553 --- /dev/null +++ b/crates/qbz-external-reco/src/carousels.rs @@ -0,0 +1,546 @@ +//! Per-carousel candidate generation, blending, filtering, validation, rotation. + +use std::collections::HashSet; +use std::sync::Mutex; + +use futures_util::stream::{self, StreamExt}; +use qbz_integrations::MusicBrainzClient; +use qbz_models::Album; + +use crate::cache::RecoCache; +use crate::matching::normalize; +use crate::types::{ + AlbumReco, ArtistCandidate, ArtistReco, ExternalCarousels, RecoSource, TrackCandidate, TrackReco, +}; +use crate::validate::{validate_artist, validate_track}; +use crate::{RecoCatalog, RecoInputs}; + +const DISPLAY_CAP: usize = 20; +const VALIDATE_CONCURRENCY: usize = 6; +const ARTIST_SEEDS: usize = 5; +const SIMILAR_PER_SEED: u32 = 15; +const KNOWN_ARTISTS_PER_BUILD: usize = 8; +const DEEP_CUT_SKIP_TOP: usize = 3; + +type Cache<'a> = Option<&'a Mutex>; + +/// Normalized "artist|title" key for the listened/scrobbled exclusion sets. +fn track_key(artist: &str, title: &str) -> String { + format!("{}|{}", normalize(artist), normalize(title)) +} + +/// External listening signal (normalized) used to filter "not heard" rows. +struct ExtHistory { + /// Artists the user has listened to (Last.fm/LB) — excludes C1. + artist_names: HashSet, + /// Tracks the user has scrobbled — excludes C2 / C4. + track_keys: HashSet, +} + +/// Interleave candidate groups round-robin so every connected source is fairly +/// represented (the Option-B blend). +fn round_robin(groups: Vec>) -> Vec { + let mut iters: Vec> = groups.into_iter().map(|g| g.into_iter()).collect(); + let mut out = Vec::new(); + loop { + let mut any = false; + for it in iters.iter_mut() { + if let Some(x) = it.next() { + out.push(x); + any = true; + } + } + if !any { + break; + } + } + out +} + +/// Rotate the pool by the daily seed, then take the display cap — gives "change" +/// across days without re-hitting the APIs (the pool is cache-backed). +fn rotate_take(mut pool: Vec, seed: u64, take: usize) -> Vec { + if pool.is_empty() { + return pool; + } + let off = (seed as usize) % pool.len(); + pool.rotate_left(off); + pool.truncate(take); + pool +} + +fn map_album_reco(a: &Album) -> AlbumReco { + let year = a + .release_date_original + .as_deref() + .and_then(|s| s.get(..4).map(|y| y.to_string())) + .unwrap_or_default(); + let quality_tier = match a.maximum_bit_depth { + Some(d) if d >= 24 => "hires", + Some(_) => "cd", + None => "", + } + .to_string(); + let quality_label = match (a.maximum_bit_depth, a.maximum_sampling_rate) { + (Some(bd), Some(sr)) => format!("{}-bit / {} kHz", bd, sr), + _ => String::new(), + }; + AlbumReco { + qobuz_album_id: a.id.clone(), + title: a.title.clone(), + artist: a.artist.name.clone(), + artist_id: a.artist.id.to_string(), + year, + quality_tier, + quality_label, + artwork_url: a.image.best().cloned().unwrap_or_default(), + } +} + +/// Validate a track-candidate pool concurrently, preserving blend order, deduped +/// by Qobuz track id. +async fn validate_track_pool( + catalog: &dyn RecoCatalog, + mb: &MusicBrainzClient, + cache: Cache<'_>, + cands: Vec, +) -> Vec { + let resolved: Vec> = stream::iter( + cands + .into_iter() + .map(|cand| async move { validate_track(catalog, mb, cache, &cand).await }), + ) + .buffered(VALIDATE_CONCURRENCY) + .collect() + .await; + + let mut seen = HashSet::new(); + resolved + .into_iter() + .flatten() + .filter(|r| seen.insert(r.qobuz_track_id)) + .collect() +} + +/// Validate an artist-candidate pool concurrently, deduped by Qobuz artist id. +async fn validate_artist_pool( + catalog: &dyn RecoCatalog, + cache: Cache<'_>, + cands: Vec, +) -> Vec { + let resolved: Vec> = stream::iter( + cands + .into_iter() + .map(|cand| async move { validate_artist(catalog, cache, &cand).await }), + ) + .buffered(VALIDATE_CONCURRENCY) + .collect() + .await; + + let mut seen = HashSet::new(); + resolved + .into_iter() + .flatten() + .filter(|r| seen.insert(r.qobuz_artist_id)) + .collect() +} + +pub async fn build(inputs: RecoInputs<'_>) -> ExternalCarousels { + let has_external = inputs.lastfm.is_some() || inputs.listenbrainz.is_some(); + if !has_external { + return build_editorial_fallback(&inputs).await; + } + + let history = gather_external_history(&inputs).await; + + // Shared ListenBrainz CF (the personalized recommender), kept to the + // never-listened slice — feeds BOTH C1 (its artists) and C2 (its tracks). + let lb_cf_unheard = fetch_lb_cf_unheard(&inputs).await; + + let (c1, c2, c3, c4) = tokio::join!( + build_similar_artists(&inputs, &history, &lb_cf_unheard), + build_similar_tracks(&inputs, &history, &lb_cf_unheard), + build_rediscover_tracks(&inputs, &history), + build_deep_cut_tracks(&inputs, &history), + ); + + ExternalCarousels { + editorial_fallback: false, + similar_artists: c1, + similar_tracks: c2, + rediscover_tracks: c3, + deep_cut_tracks: c4, + top_albums: Vec::new(), + top_artists: Vec::new(), + } +} + +async fn gather_external_history(inputs: &RecoInputs<'_>) -> ExtHistory { + let mut artist_names = HashSet::new(); + let mut track_keys = HashSet::new(); + + if let Some(lf) = &inputs.lastfm { + let (tops, recents, loved) = tokio::join!( + lf.client.get_top_artists(&lf.username, "overall", 200), + lf.client.get_recent_tracks(&lf.username, 200, 1), + lf.client.get_loved_tracks(&lf.username, 100), + ); + for a in tops.unwrap_or_default() { + artist_names.insert(normalize(&a.name)); + } + for t in recents.unwrap_or_default() { + artist_names.insert(normalize(&t.artist)); + track_keys.insert(track_key(&t.artist, &t.name)); + } + for t in loved.unwrap_or_default() { + artist_names.insert(normalize(&t.artist)); + track_keys.insert(track_key(&t.artist, &t.name)); + } + } + + if let Some(lb) = &inputs.listenbrainz { + let listens = lb + .client + .get_recent_listens(&lb.username, 1000) + .await + .unwrap_or_default(); + for l in listens { + artist_names.insert(normalize(&l.artist_name)); + track_keys.insert(track_key(&l.artist_name, &l.track_name)); + } + } + + ExtHistory { + artist_names, + track_keys, + } +} + +/// ListenBrainz CF recommendations, never-listened slice, hydrated to names. +async fn fetch_lb_cf_unheard( + inputs: &RecoInputs<'_>, +) -> Vec { + let Some(lb) = &inputs.listenbrainz else { + return Vec::new(); + }; + let recs = lb + .client + .get_cf_recommendations(&lb.username, 200) + .await + .unwrap_or_default(); + let unheard_mbids: Vec = recs + .into_iter() + .filter(|r| r.latest_listened_at.is_none()) + .map(|r| r.recording_mbid) + .filter(|m| !m.is_empty()) + .take(80) + .collect(); + if unheard_mbids.is_empty() { + return Vec::new(); + } + lb.client + .get_metadata_recordings(&unheard_mbids) + .await + .unwrap_or_default() +} + +// ── C1 — Similar artists you haven't heard ───────────────────────────────── +async fn build_similar_artists( + inputs: &RecoInputs<'_>, + history: &ExtHistory, + lb_cf_unheard: &[qbz_integrations::listenbrainz::LbRecordingMeta], +) -> Vec { + let mut lastfm_group: Vec = Vec::new(); + if let Some(lf) = &inputs.lastfm { + let seeds = lf + .client + .get_top_artists(&lf.username, "6month", 10) + .await + .unwrap_or_default(); + let seed_names: Vec = seeds.into_iter().take(ARTIST_SEEDS).map(|a| a.name).collect(); + let sims = stream::iter(seed_names.into_iter().map(|name| { + let lf = lf; + async move { + lf.client + .get_similar_artists(&name, SIMILAR_PER_SEED) + .await + .unwrap_or_default() + } + })) + .buffered(4) + .collect::>() + .await; + for group in sims { + for s in group { + lastfm_group.push(ArtistCandidate { + name: s.name, + source: RecoSource::LastFm, + score: s.match_score as f32, + }); + } + } + } + + let mut lb_group: Vec = Vec::new(); + let total = lb_cf_unheard.len().max(1) as f32; + for (i, meta) in lb_cf_unheard.iter().enumerate() { + if meta.artist_name.is_empty() { + continue; + } + lb_group.push(ArtistCandidate { + name: meta.artist_name.clone(), + source: RecoSource::ListenBrainz, + score: 1.0 - (i as f32 / total), + }); + } + + // Blend, drop already-heard, dedup by normalized name. + let mut seen: HashSet = HashSet::new(); + let candidates: Vec = round_robin(vec![lb_group, lastfm_group]) + .into_iter() + .filter(|c| { + let n = normalize(&c.name); + !n.is_empty() && !history.artist_names.contains(&n) && seen.insert(n) + }) + .take(45) + .collect(); + + let pool = validate_artist_pool(inputs.catalog, inputs.cache, candidates).await; + rotate_take(pool, inputs.rotation_seed, DISPLAY_CAP) +} + +// ── C2 — Similar tracks you haven't heard ────────────────────────────────── +async fn build_similar_tracks( + inputs: &RecoInputs<'_>, + history: &ExtHistory, + lb_cf_unheard: &[qbz_integrations::listenbrainz::LbRecordingMeta], +) -> Vec { + // LB: CF recordings (already never-listened). + let total = lb_cf_unheard.len().max(1) as f32; + let lb_group: Vec = lb_cf_unheard + .iter() + .enumerate() + .filter(|(_, m)| !m.recording_name.is_empty() && !m.artist_name.is_empty()) + .map(|(i, m)| TrackCandidate { + artist: m.artist_name.clone(), + title: m.recording_name.clone(), + album: m.release_name.clone(), + duration_ms: None, + isrc: None, + recording_mbid: Some(m.recording_mbid.clone()).filter(|s| !s.is_empty()), + source: RecoSource::ListenBrainz, + score: 1.0 - (i as f32 / total), + }) + .collect(); + + // Last.fm: track.getSimilar seeded by loved tracks. + let mut lastfm_group: Vec = Vec::new(); + if let Some(lf) = &inputs.lastfm { + let loved = lf + .client + .get_loved_tracks(&lf.username, 30) + .await + .unwrap_or_default(); + let seeds: Vec<(String, String)> = loved + .into_iter() + .take(8) + .map(|t| (t.artist, t.name)) + .collect(); + let sims = stream::iter(seeds.into_iter().map(|(artist, title)| { + let lf = lf; + async move { + lf.client + .get_similar_tracks(&artist, &title, 10) + .await + .unwrap_or_default() + } + })) + .buffered(4) + .collect::>() + .await; + for group in sims { + for s in group { + lastfm_group.push(TrackCandidate { + artist: s.artist, + title: s.name, + album: None, + duration_ms: None, + isrc: None, + recording_mbid: None, + source: RecoSource::LastFm, + score: s.match_score as f32, + }); + } + } + } + + let mut seen: HashSet = HashSet::new(); + let candidates: Vec = round_robin(vec![lb_group, lastfm_group]) + .into_iter() + .filter(|c| { + let k = track_key(&c.artist, &c.title); + !history.track_keys.contains(&k) && seen.insert(k) + }) + .take(50) + .collect(); + + let pool = validate_track_pool(inputs.catalog, inputs.musicbrainz, inputs.cache, candidates).await; + rotate_take(pool, inputs.rotation_seed, DISPLAY_CAP) +} + +// ── C3 — Listened but not recently (Last.fm long-term minus recent) ───────── +async fn build_rediscover_tracks(inputs: &RecoInputs<'_>, _history: &ExtHistory) -> Vec { + let Some(lf) = &inputs.lastfm else { + return Vec::new(); + }; + let (long_term, recent) = tokio::join!( + lf.client.get_top_tracks(&lf.username, "12month", 60), + lf.client.get_top_tracks(&lf.username, "1month", 60), + ); + let recent_keys: HashSet = recent + .unwrap_or_default() + .into_iter() + .map(|t| track_key(&t.artist, &t.name)) + .collect(); + + let mut seen: HashSet = HashSet::new(); + let candidates: Vec = long_term + .unwrap_or_default() + .into_iter() + .filter_map(|t| { + let k = track_key(&t.artist, &t.name); + if recent_keys.contains(&k) || !seen.insert(k) { + return None; + } + Some(TrackCandidate { + artist: t.artist, + title: t.name, + album: t.album, + duration_ms: None, + isrc: None, + recording_mbid: None, + source: RecoSource::LastFm, + score: 0.0, + }) + }) + .take(50) + .collect(); + + let pool = validate_track_pool(inputs.catalog, inputs.musicbrainz, inputs.cache, candidates).await; + rotate_take(pool, inputs.rotation_seed, DISPLAY_CAP) +} + +// ── C4 — From artists you know but not scrobbled (deep cuts) ──────────────── +async fn build_deep_cut_tracks(inputs: &RecoInputs<'_>, history: &ExtHistory) -> Vec { + if inputs.local.known_artist_ids.is_empty() { + return Vec::new(); + } + // Rotate which known artists we mine today. + let mut ids: Vec = inputs.local.known_artist_ids.iter().copied().collect(); + ids.sort_unstable(); + let ids = rotate_take(ids, inputs.rotation_seed, KNOWN_ARTISTS_PER_BUILD); + + let per_artist = stream::iter(ids.into_iter().map(|id| { + let catalog = inputs.catalog; + async move { catalog.artist_top_tracks(id, 15).await } + })) + .buffered(4) + .collect::>() + .await; + + let mut seen: HashSet = HashSet::new(); + let mut pool: Vec = Vec::new(); + for tracks in per_artist { + // Skip the artist's top hits to favor deep cuts. + for track in tracks.into_iter().skip(DEEP_CUT_SKIP_TOP) { + if !track.streamable { + continue; + } + let artist = track + .performer + .as_ref() + .map(|a| a.name.clone()) + .unwrap_or_default(); + let k = track_key(&artist, &track.title); + // Not scrobbled externally AND not played in-app. + if history.track_keys.contains(&k) || inputs.local.played_track_ids.contains(&track.id) { + continue; + } + if !seen.insert(track.id) { + continue; + } + pool.push(TrackReco { + qobuz_track_id: track.id, + title: track.title.clone(), + artist, + artwork_url: track + .album + .as_ref() + .and_then(|al| al.image.best().cloned()) + .unwrap_or_default(), + source: RecoSource::Internal, + }); + } + } + + rotate_take(pool, inputs.rotation_seed, DISPLAY_CAP) +} + +// ── Cold-start fallback — Qobuz editorial top (albums + artists) ──────────── +async fn build_editorial_fallback(inputs: &RecoInputs<'_>) -> ExternalCarousels { + let (most_streamed, new_releases) = tokio::join!( + inputs.catalog.featured_albums("most-streamed", 20), + inputs.catalog.featured_albums("new-releases", 20), + ); + + let mut seen_albums: HashSet = HashSet::new(); + let mut top_albums: Vec = Vec::new(); + for album in most_streamed.iter().chain(new_releases.iter()) { + if !album.id.is_empty() && seen_albums.insert(album.id.clone()) { + top_albums.push(map_album_reco(album)); + } + } + top_albums.truncate(20); + + // Top artists: distinct album artists, portraits fetched by id. + let mut seen_artists: HashSet = HashSet::new(); + let mut artist_ids: Vec<(u64, String)> = Vec::new(); + for album in most_streamed.iter().chain(new_releases.iter()) { + let id = album.artist.id; + if id != 0 && seen_artists.insert(id) { + artist_ids.push((id, album.artist.name.clone())); + } + if artist_ids.len() >= 12 { + break; + } + } + let top_artists: Vec = stream::iter(artist_ids.into_iter().map(|(id, name)| { + let catalog = inputs.catalog; + async move { + let image_url = catalog + .get_artist(id) + .await + .and_then(|a| a.image.and_then(|i| i.best().cloned())) + .unwrap_or_default(); + ArtistReco { + qobuz_artist_id: id, + name, + image_url, + source: RecoSource::Editorial, + } + } + })) + .buffered(4) + .collect() + .await; + + ExternalCarousels { + editorial_fallback: true, + similar_artists: Vec::new(), + similar_tracks: Vec::new(), + rediscover_tracks: Vec::new(), + deep_cut_tracks: Vec::new(), + top_albums, + top_artists, + } +} diff --git a/crates/qbz-external-reco/src/lib.rs b/crates/qbz-external-reco/src/lib.rs new file mode 100644 index 000000000..dfeb8709f --- /dev/null +++ b/crates/qbz-external-reco/src/lib.rs @@ -0,0 +1,88 @@ +//! Frontend-agnostic external-recommendations engine for Discover (ADR-006). +//! +//! Blends up to three sources — the in-house artist-vector engine (`qbz-reco`, +//! deferred/placeholder), Last.fm, and ListenBrainz — into the Discover +//! "External Recommendations" carousels, validating every candidate against the +//! Qobuz catalog before it is shown (the app can only play Qobuz content). +//! +//! Owner design (2026-06-26/27): +//! - C1 "Similar artists you haven't heard" + C2 "Similar tracks you haven't +//! heard" = pure discovery, **blended** across all connected sources. +//! - C3 "Listened but not recently" = re-discovery (Last.fm long-term tops). +//! - C4 "From artists you know but not scrobbled" = deep cuts (Qobuz catalog +//! of known artists, minus the external scrobble set). +//! - Each carousel caps at 20 with daily rotation over a larger pool. +//! - NEVER hide: with no connected external source it falls back to Qobuz +//! editorial top albums + artists (already Qobuz-native, zero validation). +//! +//! The crate depends only on frontend-agnostic crates (`qbz-integrations`, +//! `qbz-models`). The Qobuz catalog is reached via the [`RecoCatalog`] trait, +//! which the frontend implements over its own core. + +pub mod cache; +pub mod matching; +pub mod types; + +mod carousels; +mod validate; + +use std::sync::Mutex; + +use qbz_integrations::{LastFmClient, ListenBrainzClient, MusicBrainzClient}; +use qbz_models::{Album, Artist, Track}; + +pub use cache::RecoCache; +pub use types::{ + AlbumReco, ArtistReco, ExternalCarousels, LocalHistory, RecoSource, TrackReco, +}; + +/// The Qobuz catalog operations the engine needs. Implemented by the frontend +/// over its own `QbzCore`. Every method swallows errors to an empty result — +/// "no data" must never be an error to the engine. +#[async_trait::async_trait] +pub trait RecoCatalog: Send + Sync { + /// Free-text Qobuz track search (also used for ISRC-as-query). + async fn search_tracks(&self, query: &str, limit: usize) -> Vec; + /// Qobuz artist search (for validating a recommended artist name). + async fn search_artists(&self, query: &str, limit: usize) -> Vec; + /// An artist's top tracks (the deep-cut candidate source for C4). + async fn artist_top_tracks(&self, artist_id: u64, limit: usize) -> Vec; + /// Editorial featured albums by kind ("most-streamed" | "new-releases" | …). + async fn featured_albums(&self, kind: &str, limit: usize) -> Vec; + /// Full artist by id (cold-start top-artist portraits). + async fn get_artist(&self, artist_id: u64) -> Option; +} + +/// A connected Last.fm account: the public username + a ready client. +pub struct LastFmHandle<'a> { + pub username: String, + pub client: &'a LastFmClient, +} + +/// A connected ListenBrainz account: the public username + a ready client. +pub struct ListenBrainzHandle<'a> { + pub username: String, + pub client: &'a ListenBrainzClient, +} + +/// All the inputs `build_external_carousels` needs. Borrowed so the frontend +/// owns the clients/cache and the engine stays allocation-light. +pub struct RecoInputs<'a> { + pub lastfm: Option>, + pub listenbrainz: Option>, + pub musicbrainz: &'a MusicBrainzClient, + pub catalog: &'a dyn RecoCatalog, + /// Optional resolution cache (per-user SQLite). `None` disables caching. + pub cache: Option<&'a Mutex>, + /// Local listening signal from the `reco_events` store. + pub local: LocalHistory, + /// Daily rotation offset (e.g. days since the Unix epoch). + pub rotation_seed: u64, +} + +/// Build the Discover "External Recommendations" carousels. Cheap to call +/// repeatedly thanks to the resolution cache; the frontend should still throttle +/// rebuilds (e.g. once per session) to bound external-API load. +pub async fn build_external_carousels(inputs: RecoInputs<'_>) -> ExternalCarousels { + carousels::build(inputs).await +} diff --git a/crates/qbz-external-reco/src/matching.rs b/crates/qbz-external-reco/src/matching.rs new file mode 100644 index 000000000..6d084215c --- /dev/null +++ b/crates/qbz-external-reco/src/matching.rs @@ -0,0 +1,222 @@ +//! Text + ISRC scoring to validate a recommendation against the Qobuz catalog. +//! +//! Clean-room port of `qbz-playlist-import::match_qobuz` (the proven importer +//! scorer), adapted to score a lightweight [`MatchInput`] (artist/title/album/ +//! duration/isrc) against a `qbz_models::Track`. Kept self-contained here so the +//! engine has no dependency on the importer crate; the algorithm is identical +//! (ISRC short-circuit -> title*0.6 + artist*0.3 + album*0.1 + duration bonus, +//! `!streamable` skipped, hi-res tiebreak). + +use qbz_models::Track; + +const TITLE_WEIGHT: f32 = 0.6; +const ARTIST_WEIGHT: f32 = 0.3; +const ALBUM_WEIGHT: f32 = 0.1; + +/// Minimum score to accept a text-only (no-ISRC) match. Mirrors the importer. +pub const MIN_SCORE: f32 = 0.65; + +/// The recommendation being matched against Qobuz candidates. +pub struct MatchInput<'a> { + pub artist: &'a str, + pub title: &'a str, + pub album: Option<&'a str>, + pub duration_ms: Option, + pub isrc: Option<&'a str>, +} + +/// Pick the best streamable candidate and its score (hi-res breaks ties). +/// Does NOT gate on [`MIN_SCORE`] — the caller decides. +pub fn select_best_match<'a>(input: &MatchInput, candidates: &'a [Track]) -> (Option<&'a Track>, f32) { + let mut best: Option<&Track> = None; + let mut best_score = 0.0f32; + let mut best_quality = 0.0f32; + + for candidate in candidates { + if !candidate.streamable { + continue; + } + let score = score_candidate(input, candidate); + let quality = quality_score(candidate); + + if score > best_score + 0.0001 { + best = Some(candidate); + best_score = score; + best_quality = quality; + } else if (score - best_score).abs() < 0.01 && quality > best_quality { + best = Some(candidate); + best_quality = quality; + } + } + + (best, best_score) +} + +pub fn score_candidate(input: &MatchInput, candidate: &Track) -> f32 { + if let (Some(isrc), Some(candidate_isrc)) = (input.isrc, &candidate.isrc) { + if isrc.eq_ignore_ascii_case(candidate_isrc) { + return 1.0; + } + } + + let title_score = similarity(input.title, &candidate.title); + let artist_score = similarity( + input.artist, + candidate + .performer + .as_ref() + .map(|a| a.name.as_str()) + .unwrap_or(""), + ); + let album_score = input + .album + .map(|album| { + candidate + .album + .as_ref() + .map(|a| similarity(album, &a.title)) + .unwrap_or(0.0) + }) + .unwrap_or(0.0); + + let mut score = + title_score * TITLE_WEIGHT + artist_score * ARTIST_WEIGHT + album_score * ALBUM_WEIGHT; + + if let (Some(import_duration), candidate_duration) = ( + input.duration_ms, + (candidate.duration as u64).saturating_mul(1000), + ) { + let diff = if import_duration > candidate_duration { + import_duration - candidate_duration + } else { + candidate_duration - import_duration + }; + if diff <= 3000 { + score += 0.05; + } else if diff <= 5000 { + score += 0.02; + } + } + + score +} + +pub fn similarity(a: &str, b: &str) -> f32 { + let na = normalize(a); + let nb = normalize(b); + if na.is_empty() || nb.is_empty() { + return 0.0; + } + if na == nb { + return 1.0; + } + if na.contains(&nb) || nb.contains(&na) { + return 0.85; + } + token_overlap(&na, &nb) +} + +/// Normalize a name for matching AND for cache keys (lowercase, strip brackets + +/// stop-words, collapse punctuation to spaces). +pub fn normalize(input: &str) -> String { + let stripped = remove_bracketed(input); + let mut cleaned = String::new(); + for ch in stripped.chars() { + if ch.is_ascii_alphanumeric() || ch.is_whitespace() { + cleaned.push(ch.to_ascii_lowercase()); + } else { + cleaned.push(' '); + } + } + let stop_words = [ + "remaster", + "remastered", + "deluxe", + "edition", + "live", + "feat", + "featuring", + "version", + "mix", + "mono", + "stereo", + "edit", + ]; + cleaned + .split_whitespace() + .filter(|token| !stop_words.contains(token)) + .collect::>() + .join(" ") +} + +fn remove_bracketed(input: &str) -> String { + let mut out = String::new(); + let mut depth = 0u32; + for ch in input.chars() { + match ch { + '(' | '[' => depth += 1, + ')' | ']' => { + if depth > 0 { + depth -= 1; + } + } + _ => { + if depth == 0 { + out.push(ch); + } + } + } + } + out +} + +fn token_overlap(a: &str, b: &str) -> f32 { + let a_tokens: Vec<&str> = a.split_whitespace().collect(); + let b_tokens: Vec<&str> = b.split_whitespace().collect(); + if a_tokens.is_empty() || b_tokens.is_empty() { + return 0.0; + } + let mut matches = 0u32; + for token in &a_tokens { + if b_tokens.contains(token) { + matches += 1; + } + } + matches as f32 / a_tokens.len().max(b_tokens.len()) as f32 +} + +fn quality_score(track: &Track) -> f32 { + let bit_depth = track.maximum_bit_depth.unwrap_or(0) as f32; + let sample_rate = track.maximum_sampling_rate.unwrap_or(0.0) as f32; + bit_depth * 100000.0 + sample_rate +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn normalize_strips_brackets_and_stop_words() { + assert_eq!(normalize("Song Title (Remastered 2011)"), "song title"); + assert_eq!(normalize("Hey Jude - Remastered"), "hey jude"); + } + + #[test] + fn similarity_exact_and_substring() { + assert_eq!(similarity("Hey Jude (Remastered)", "hey jude"), 1.0); + assert_eq!(similarity("hey jude", "hey jude na na"), 0.85); + assert_eq!(similarity("", "anything"), 0.0); + } + + #[test] + fn token_overlap_uses_longer_side() { + assert_eq!(token_overlap("a b", "a b c d"), 0.5); + assert_eq!(token_overlap("x", "y"), 0.0); + } + + #[test] + fn normalize_is_stable_for_cache_keys() { + assert_eq!(normalize(" The Beatles "), "the beatles"); + assert_eq!(normalize("AC/DC"), "ac dc"); + } +} diff --git a/crates/qbz-external-reco/src/types.rs b/crates/qbz-external-reco/src/types.rs new file mode 100644 index 000000000..460a12c7d --- /dev/null +++ b/crates/qbz-external-reco/src/types.rs @@ -0,0 +1,103 @@ +//! Data types for the external-recommendations engine. + +use serde::{Deserialize, Serialize}; + +/// Which source produced a recommendation row item. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] +pub enum RecoSource { + /// In-house artist-vector engine (`qbz-reco`) — deferred, placeholder. + Internal, + LastFm, + ListenBrainz, + /// Qobuz editorial (cold-start fallback). + Editorial, +} + +/// A raw artist candidate before Qobuz validation. +#[derive(Debug, Clone)] +pub struct ArtistCandidate { + pub name: String, + pub source: RecoSource, + /// Source-normalized similarity score in 0..1. + pub score: f32, +} + +/// A raw track candidate before Qobuz validation. +#[derive(Debug, Clone)] +pub struct TrackCandidate { + pub artist: String, + pub title: String, + pub album: Option, + pub duration_ms: Option, + pub isrc: Option, + pub recording_mbid: Option, + pub source: RecoSource, + /// Source-normalized similarity score in 0..1. + pub score: f32, +} + +/// A resolved artist row (validated to a Qobuz artist). +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct ArtistReco { + pub qobuz_artist_id: u64, + pub name: String, + pub image_url: String, + pub source: RecoSource, +} + +/// A resolved track row (validated to / sourced from a Qobuz track). +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct TrackReco { + pub qobuz_track_id: u64, + pub title: String, + pub artist: String, + pub artwork_url: String, + pub source: RecoSource, +} + +/// One album row for the cold-start editorial fallback. +#[derive(Debug, Clone)] +pub struct AlbumReco { + pub qobuz_album_id: String, + pub title: String, + pub artist: String, + pub artist_id: String, + pub year: String, + pub quality_tier: String, + pub quality_label: String, + pub artwork_url: String, +} + +/// The full external-recommendations result for the Discover section. +/// +/// At runtime exactly one regime is populated: `editorial_fallback == true` +/// fills `top_albums`/`top_artists` (cold start, no connected external source), +/// otherwise the four personalized carousels are filled. Empty vecs self-hide +/// their row in the view, so partial population is always safe. +#[derive(Debug, Clone, Default)] +pub struct ExternalCarousels { + /// No external integration connected -> editorial fallback regime. + pub editorial_fallback: bool, + /// C1 — "Similar artists you haven't heard". + pub similar_artists: Vec, + /// C2 — "Similar tracks you haven't heard". + pub similar_tracks: Vec, + /// C3 — "Listened but not recently". + pub rediscover_tracks: Vec, + /// C4 — "From artists you know but not scrobbled" (deep cuts). + pub deep_cut_tracks: Vec, + /// Cold-start fallback: Qobuz editorial top albums. + pub top_albums: Vec, + /// Cold-start fallback: Qobuz editorial top artists. + pub top_artists: Vec, +} + +/// Local listening signal derived from the per-user `reco_events` store (all ids +/// are Qobuz ids; the play log is Qobuz-source-gated). +#[derive(Debug, Clone, Default)] +pub struct LocalHistory { + /// Artists the user already knows (played > threshold or favorited). + pub known_artist_ids: std::collections::HashSet, + /// Tracks played in-app (the local "already heard" set). + pub played_track_ids: std::collections::HashSet, +} diff --git a/crates/qbz-external-reco/src/validate.rs b/crates/qbz-external-reco/src/validate.rs new file mode 100644 index 000000000..b6c5e93e0 --- /dev/null +++ b/crates/qbz-external-reco/src/validate.rs @@ -0,0 +1,191 @@ +//! Resolve a recommendation candidate to a real, streamable Qobuz entity. +//! +//! Precedence for tracks (strongest key first): +//! 1. ISRC known -> Qobuz text-search the ISRC, accept only on an +//! exact `Track.isrc` match (Qobuz indexes ISRC). +//! 2. recording_mbid known -> MusicBrainz `inc=isrcs` bridge -> step 1. +//! 3. names only -> fuzzy text search scored by [`crate::matching`], +//! gated at `MIN_SCORE`. +//! Artists resolve by Qobuz artist-search + normalized-name match. +//! +//! Every outcome (positive AND negative) is cached so rotation re-renders and +//! repeat builds never re-hit the Qobuz/MusicBrainz APIs for a known candidate. + +use std::sync::Mutex; + +use qbz_integrations::MusicBrainzClient; +use qbz_models::Track; + +use crate::cache::{CacheLookup, RecoCache}; +use crate::matching::{normalize, select_best_match, MatchInput, MIN_SCORE}; +use crate::types::{ArtistCandidate, ArtistReco, TrackCandidate, TrackReco}; +use crate::RecoCatalog; + +type Cache<'a> = Option<&'a Mutex>; + +fn track_cache_key(c: &TrackCandidate) -> String { + if let Some(isrc) = c.isrc.as_deref().filter(|s| !s.is_empty()) { + format!("t:isrc:{}", isrc.to_uppercase()) + } else if let Some(mbid) = c.recording_mbid.as_deref().filter(|s| !s.is_empty()) { + format!("t:mbid:{}", mbid) + } else { + format!("t:name:{}|{}", normalize(&c.artist), normalize(&c.title)) + } +} + +fn build_track_reco(track: &Track, source: crate::types::RecoSource) -> TrackReco { + TrackReco { + qobuz_track_id: track.id, + title: track.title.clone(), + artist: track + .performer + .as_ref() + .map(|a| a.name.clone()) + .unwrap_or_default(), + artwork_url: track + .album + .as_ref() + .and_then(|al| al.image.best().cloned()) + .unwrap_or_default(), + source, + } +} + +/// Find a Qobuz track whose ISRC matches `isrc` exactly (Qobuz has no ISRC +/// endpoint; it indexes ISRC in free-text search, so we verify the field). +async fn find_by_isrc(catalog: &dyn RecoCatalog, isrc: &str) -> Option { + let results = catalog.search_tracks(isrc, 5).await; + results.into_iter().find(|t| { + t.streamable + && t.isrc + .as_deref() + .map(|c| c.eq_ignore_ascii_case(isrc)) + .unwrap_or(false) + }) +} + +async fn resolve_track_live( + catalog: &dyn RecoCatalog, + mb: &MusicBrainzClient, + cand: &TrackCandidate, +) -> Option { + // 1. ISRC direct. + if let Some(isrc) = cand.isrc.as_deref().filter(|s| !s.is_empty()) { + if let Some(track) = find_by_isrc(catalog, isrc).await { + return Some(build_track_reco(&track, cand.source)); + } + } + // 2. recording_mbid -> MusicBrainz ISRCs -> ISRC. + if let Some(mbid) = cand.recording_mbid.as_deref().filter(|s| !s.is_empty()) { + let isrcs = mb.get_recording_isrcs(mbid).await.unwrap_or_default(); + for isrc in isrcs { + if let Some(track) = find_by_isrc(catalog, &isrc).await { + return Some(build_track_reco(&track, cand.source)); + } + } + } + // 3. Fuzzy text search. + let query = format!("{} {}", cand.artist, cand.title); + let candidates = catalog.search_tracks(query.trim(), 20).await; + let input = MatchInput { + artist: &cand.artist, + title: &cand.title, + album: cand.album.as_deref(), + duration_ms: cand.duration_ms, + isrc: cand.isrc.as_deref(), + }; + let (best, score) = select_best_match(&input, &candidates); + match best { + Some(track) if score >= MIN_SCORE => Some(build_track_reco(track, cand.source)), + _ => None, + } +} + +/// Validate a track candidate, using the cache for both hits and misses. +pub async fn validate_track( + catalog: &dyn RecoCatalog, + mb: &MusicBrainzClient, + cache: Cache<'_>, + cand: &TrackCandidate, +) -> Option { + let key = track_cache_key(cand); + if let Some(c) = cache { + if let Ok(guard) = c.lock() { + match guard.get(&key) { + CacheLookup::Found(json) => { + if let Ok(mut reco) = serde_json::from_str::(&json) { + reco.source = cand.source; + return Some(reco); + } + } + CacheLookup::Negative => return None, + CacheLookup::Miss => {} + } + } + } + + let reco = resolve_track_live(catalog, mb, cand).await; + + if let Some(c) = cache { + if let Ok(guard) = c.lock() { + match &reco { + Some(r) => { + let json = serde_json::to_string(r).unwrap_or_default(); + guard.put(&key, "track", Some(&json)); + } + None => guard.put(&key, "track", None), + } + } + } + reco +} + +/// Validate an artist candidate (name -> Qobuz artist), cached. +pub async fn validate_artist( + catalog: &dyn RecoCatalog, + cache: Cache<'_>, + cand: &ArtistCandidate, +) -> Option { + let key = format!("a:{}", normalize(&cand.name)); + if let Some(c) = cache { + if let Ok(guard) = c.lock() { + match guard.get(&key) { + CacheLookup::Found(json) => { + if let Ok(mut reco) = serde_json::from_str::(&json) { + reco.source = cand.source; + return Some(reco); + } + } + CacheLookup::Negative => return None, + CacheLookup::Miss => {} + } + } + } + + let target = normalize(&cand.name); + let artists = catalog.search_artists(&cand.name, 8).await; + let reco = artists + .iter() + .find(|a| normalize(&a.name) == target) + .or_else(|| artists.first()) + .filter(|a| a.id != 0) + .map(|a| ArtistReco { + qobuz_artist_id: a.id, + name: a.name.clone(), + image_url: a.image.as_ref().and_then(|i| i.best().cloned()).unwrap_or_default(), + source: cand.source, + }); + + if let Some(c) = cache { + if let Ok(guard) = c.lock() { + match &reco { + Some(r) => { + let json = serde_json::to_string(r).unwrap_or_default(); + guard.put(&key, "artist", Some(&json)); + } + None => guard.put(&key, "artist", None), + } + } + } + reco +} diff --git a/crates/qbz-integrations/src/lastfm/client.rs b/crates/qbz-integrations/src/lastfm/client.rs index 2e19f4414..f82c459ed 100644 --- a/crates/qbz-integrations/src/lastfm/client.rs +++ b/crates/qbz-integrations/src/lastfm/client.rs @@ -4,8 +4,8 @@ use reqwest::Client; use serde_json::json; use super::models::{ - AuthGetSessionResponse, AuthGetTokenResponse, LastFmResponse, LastFmSession, - LastFmSimilarArtist, + AuthGetSessionResponse, AuthGetTokenResponse, LastFmArtist, LastFmResponse, LastFmSession, + LastFmSimilarArtist, LastFmSimilarTrack, LastFmTrack, }; use crate::error::{IntegrationError, IntegrationResult}; @@ -296,4 +296,466 @@ impl LastFmClient { Ok(artists) } + + /// user.getTopArtists — top artists for the user (taste seed + known-artist set). + /// + /// `period` must be one of: `overall|7day|1month|3month|6month|12month`. + /// Public read endpoint — no session key needed (the proxy injects the API key). + pub async fn get_top_artists( + &self, + user: &str, + period: &str, + limit: u32, + ) -> IntegrationResult> { + let url = format!("{}/user.getTopArtists", LASTFM_PROXY_URL); + + let response = self + .client + .post(&url) + .json(&json!({ + "user": user, + "period": period, + "limit": limit, + })) + .send() + .await?; + + if !response.status().is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "Last.fm user.getTopArtists failed: {}", + text + ))); + } + + let text = response.text().await?; + + let data: serde_json::Value = serde_json::from_str(&text)?; + + // Handle Last.fm error responses + if let Some(error) = data.get("error") { + let message = data + .get("message") + .and_then(|m| m.as_str()) + .unwrap_or("Unknown error"); + return Err(IntegrationError::api( + error.as_u64().unwrap_or(0) as u32, + message.to_string(), + )); + } + + let artists = data + .get("topartists") + .and_then(|ta| ta.get("artist")) + .and_then(|a| a.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|item| { + let name = item.get("name")?.as_str()?.to_string(); + let mbid = extract_mbid(item); + let playcount = parse_u64(item.get("playcount")); + let image = extract_image(item); + + Some(LastFmArtist { + name, + mbid, + playcount, + image, + }) + }) + .collect() + }) + .unwrap_or_default(); + + Ok(artists) + } + + /// user.getTopTracks — top tracks for the user (period gives coarse recency). + /// + /// `period` must be one of: `overall|7day|1month|3month|6month|12month`. + pub async fn get_top_tracks( + &self, + user: &str, + period: &str, + limit: u32, + ) -> IntegrationResult> { + let url = format!("{}/user.getTopTracks", LASTFM_PROXY_URL); + + let response = self + .client + .post(&url) + .json(&json!({ + "user": user, + "period": period, + "limit": limit, + })) + .send() + .await?; + + if !response.status().is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "Last.fm user.getTopTracks failed: {}", + text + ))); + } + + let text = response.text().await?; + + let data: serde_json::Value = serde_json::from_str(&text)?; + + if let Some(error) = data.get("error") { + let message = data + .get("message") + .and_then(|m| m.as_str()) + .unwrap_or("Unknown error"); + return Err(IntegrationError::api( + error.as_u64().unwrap_or(0) as u32, + message.to_string(), + )); + } + + let tracks = data + .get("toptracks") + .and_then(|tt| tt.get("track")) + .and_then(|t| t.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|item| { + let name = item.get("name")?.as_str()?.to_string(); + let mbid = extract_mbid(item); + let artist_obj = item.get("artist"); + let artist = artist_obj + .and_then(|a| a.get("name")) + .and_then(|n| n.as_str()) + .unwrap_or_default() + .to_string(); + let artist_mbid = artist_obj.and_then(|a| extract_mbid(a)); + let image = extract_image(item); + + Some(LastFmTrack { + name, + artist, + artist_mbid, + mbid, + album: None, + image, + uts: None, + }) + }) + .collect() + }) + .unwrap_or_default(); + + Ok(tracks) + } + + /// user.getLovedTracks — explicitly loved tracks (strong taste seed). + pub async fn get_loved_tracks( + &self, + user: &str, + limit: u32, + ) -> IntegrationResult> { + let url = format!("{}/user.getLovedTracks", LASTFM_PROXY_URL); + + let response = self + .client + .post(&url) + .json(&json!({ + "user": user, + "limit": limit, + })) + .send() + .await?; + + if !response.status().is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "Last.fm user.getLovedTracks failed: {}", + text + ))); + } + + let text = response.text().await?; + + let data: serde_json::Value = serde_json::from_str(&text)?; + + if let Some(error) = data.get("error") { + let message = data + .get("message") + .and_then(|m| m.as_str()) + .unwrap_or("Unknown error"); + return Err(IntegrationError::api( + error.as_u64().unwrap_or(0) as u32, + message.to_string(), + )); + } + + let tracks = data + .get("lovedtracks") + .and_then(|lt| lt.get("track")) + .and_then(|t| t.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|item| { + let name = item.get("name")?.as_str()?.to_string(); + let mbid = extract_mbid(item); + let artist_obj = item.get("artist"); + let artist = artist_obj + .and_then(|a| a.get("name")) + .and_then(|n| n.as_str()) + .unwrap_or_default() + .to_string(); + let artist_mbid = artist_obj.and_then(|a| extract_mbid(a)); + let uts = extract_uts(item); + let image = extract_image(item); + + Some(LastFmTrack { + name, + artist, + artist_mbid, + mbid, + album: None, + image, + uts, + }) + }) + .collect() + }) + .unwrap_or_default(); + + Ok(tracks) + } + + /// user.getRecentTracks — timestamped scrobble history (max limit 200; paginate via `page`). + pub async fn get_recent_tracks( + &self, + user: &str, + limit: u32, + page: u32, + ) -> IntegrationResult> { + // Last.fm caps this endpoint at 200 items per page. + let limit = limit.min(200); + let url = format!("{}/user.getRecentTracks", LASTFM_PROXY_URL); + + let response = self + .client + .post(&url) + .json(&json!({ + "user": user, + "limit": limit, + "page": page, + })) + .send() + .await?; + + if !response.status().is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "Last.fm user.getRecentTracks failed: {}", + text + ))); + } + + let text = response.text().await?; + + let data: serde_json::Value = serde_json::from_str(&text)?; + + if let Some(error) = data.get("error") { + let message = data + .get("message") + .and_then(|m| m.as_str()) + .unwrap_or("Unknown error"); + return Err(IntegrationError::api( + error.as_u64().unwrap_or(0) as u32, + message.to_string(), + )); + } + + let tracks = data + .get("recenttracks") + .and_then(|rt| rt.get("track")) + .and_then(|t| t.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|item| { + // Skip the currently-playing track: it has no scrobble timestamp. + let now_playing = item + .get("@attr") + .and_then(|a| a.get("nowplaying")) + .and_then(|np| np.as_str()) + == Some("true"); + if now_playing { + return None; + } + + let name = item.get("name")?.as_str()?.to_string(); + let mbid = extract_mbid(item); + + // `artist` may be an object ({"#text"|"name", "mbid"}) or a bare string. + let artist_obj = item.get("artist"); + let artist = artist_obj + .and_then(|a| { + a.get("#text") + .and_then(|v| v.as_str()) + .or_else(|| a.get("name").and_then(|v| v.as_str())) + .or_else(|| a.as_str()) + }) + .unwrap_or_default() + .to_string(); + let artist_mbid = artist_obj.and_then(|a| extract_mbid(a)); + + let album = item + .get("album") + .and_then(|al| al.get("#text")) + .and_then(|v| v.as_str()) + .filter(|s| !s.is_empty()) + .map(|s| s.to_string()); + + let uts = extract_uts(item); + let image = extract_image(item); + + Some(LastFmTrack { + name, + artist, + artist_mbid, + mbid, + album, + image, + uts, + }) + }) + .collect() + }) + .unwrap_or_default(); + + Ok(tracks) + } + + /// track.getSimilar — tracks similar to a seed track (raw match weight, NOT 0..1). + pub async fn get_similar_tracks( + &self, + artist: &str, + track: &str, + limit: u32, + ) -> IntegrationResult> { + let url = format!("{}/track.getSimilar", LASTFM_PROXY_URL); + + let response = self + .client + .post(&url) + .json(&json!({ + "artist": artist, + "track": track, + "limit": limit, + })) + .send() + .await?; + + if !response.status().is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "Last.fm track.getSimilar failed: {}", + text + ))); + } + + let text = response.text().await?; + + let data: serde_json::Value = serde_json::from_str(&text)?; + + if let Some(error) = data.get("error") { + let message = data + .get("message") + .and_then(|m| m.as_str()) + .unwrap_or("Unknown error"); + return Err(IntegrationError::api( + error.as_u64().unwrap_or(0) as u32, + message.to_string(), + )); + } + + let tracks = data + .get("similartracks") + .and_then(|st| st.get("track")) + .and_then(|t| t.as_array()) + .map(|arr| { + arr.iter() + .filter_map(|item| { + let name = item.get("name")?.as_str()?.to_string(); + // Last.fm returns match as a string weight (e.g. "0.83492"). + let match_score: f64 = item + .get("match") + .and_then(|m| { + m.as_str() + .and_then(|s| s.parse().ok()) + .or_else(|| m.as_f64()) + }) + .unwrap_or(0.0); + let mbid = extract_mbid(item); + let artist = item + .get("artist") + .and_then(|a| a.get("name")) + .and_then(|n| n.as_str()) + .unwrap_or_default() + .to_string(); + + Some(LastFmSimilarTrack { + name, + artist, + mbid, + match_score, + }) + }) + .collect() + }) + .unwrap_or_default(); + + Ok(tracks) + } +} + +/// Extract the largest image URL (last array entry's `#text`) from a Last.fm object. +/// Returns `None` when the array is missing, empty, or the URL is blank. +fn extract_image(value: &serde_json::Value) -> Option { + value + .get("image") + .and_then(|i| i.as_array()) + .and_then(|arr| arr.last()) + .and_then(|last| last.get("#text")) + .and_then(|t| t.as_str()) + .filter(|s| !s.is_empty()) + .map(|s| s.to_string()) +} + +/// Extract a non-empty `mbid` field as `Option` (empty strings become `None`). +fn extract_mbid(value: &serde_json::Value) -> Option { + value + .get("mbid") + .and_then(|m| m.as_str()) + .filter(|s| !s.is_empty()) + .map(|s| s.to_string()) +} + +/// Extract a Unix timestamp from a Last.fm `date.uts` field (string or number). +fn extract_uts(value: &serde_json::Value) -> Option { + value + .get("date") + .and_then(|d| d.get("uts")) + .and_then(|u| { + u.as_str() + .and_then(|s| s.parse::().ok()) + .or_else(|| u.as_i64()) + }) +} + +/// Parse a `u64` that Last.fm may return as a JSON string or number; defaults to 0. +fn parse_u64(value: Option<&serde_json::Value>) -> u64 { + value + .and_then(|v| { + v.as_str() + .and_then(|s| s.parse::().ok()) + .or_else(|| v.as_u64()) + }) + .unwrap_or(0) } diff --git a/crates/qbz-integrations/src/lastfm/mod.rs b/crates/qbz-integrations/src/lastfm/mod.rs index 37db8fe45..8da0854eb 100644 --- a/crates/qbz-integrations/src/lastfm/mod.rs +++ b/crates/qbz-integrations/src/lastfm/mod.rs @@ -31,4 +31,6 @@ mod client; mod models; pub use client::LastFmClient; -pub use models::{LastFmSession, LastFmSimilarArtist}; +pub use models::{ + LastFmArtist, LastFmSession, LastFmSimilarArtist, LastFmSimilarTrack, LastFmTrack, +}; diff --git a/crates/qbz-integrations/src/lastfm/models.rs b/crates/qbz-integrations/src/lastfm/models.rs index 3801725aa..94ec36288 100644 --- a/crates/qbz-integrations/src/lastfm/models.rs +++ b/crates/qbz-integrations/src/lastfm/models.rs @@ -60,3 +60,48 @@ pub struct LastFmSimilarArtist { /// MusicBrainz ID if available pub mbid: Option, } + +/// A user's top artist from Last.fm's user.getTopArtists +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] +pub struct LastFmArtist { + /// Artist name + pub name: String, + /// MusicBrainz ID if available + pub mbid: Option, + /// Number of times the user has played this artist + pub playcount: u64, + /// Largest available image URL, if any + pub image: Option, +} + +/// A track from Last.fm user methods (top / loved / recent tracks) +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] +pub struct LastFmTrack { + /// Track name + pub name: String, + /// Artist name + pub artist: String, + /// Artist MusicBrainz ID if available + pub artist_mbid: Option, + /// Track MusicBrainz ID if available + pub mbid: Option, + /// Album name if available + pub album: Option, + /// Largest available image URL, if any + pub image: Option, + /// Unix timestamp of the scrobble / love, if available + pub uts: Option, +} + +/// A similar track from Last.fm's track.getSimilar +#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)] +pub struct LastFmSimilarTrack { + /// Track name + pub name: String, + /// Artist name + pub artist: String, + /// MusicBrainz ID if available + pub mbid: Option, + /// Raw match weight (NOT normalized to 0..1) + pub match_score: f64, +} diff --git a/crates/qbz-integrations/src/listenbrainz/client.rs b/crates/qbz-integrations/src/listenbrainz/client.rs index e1c3f619e..1812bc4bf 100644 --- a/crates/qbz-integrations/src/listenbrainz/client.rs +++ b/crates/qbz-integrations/src/listenbrainz/client.rs @@ -303,4 +303,303 @@ impl ListenBrainzClient { ))) } } + + /// Collaborative-filtering recommendations (PRIMARY personalized recommender). + /// + /// `GET /cf/recommendation/user/{user_name}/recording?count={count}` + /// + /// The `Authorization` header is sent only when a token is configured (raises + /// rate limits but is not required — this is a public read keyed by username). + /// HTTP 204/404 and empty bodies are treated as "no data" -> `Ok(vec![])`. + /// Parses `payload.mbids[]` into `{recording_mbid, score, latest_listened_at}`. + /// `latest_listened_at` is an ISO-8601 string OR null (null/absent = never listened). + pub async fn get_cf_recommendations( + &self, + user_name: &str, + count: u32, + ) -> IntegrationResult> { + let token = self.config.lock().await.token.clone(); + + let url = format!( + "{}/cf/recommendation/user/{}/recording", + LISTENBRAINZ_API_URL, user_name + ); + + let mut request = self + .client + .get(&url) + .query(&[("count", count.to_string())]); + if let Some(token) = token { + request = request.header("Authorization", format!("Token {}", token)); + } + + let response = request.send().await?; + let status = response.status(); + + // 204 No Content / 404 Not Found -> the user simply has no recommendations. + if status == reqwest::StatusCode::NO_CONTENT || status == reqwest::StatusCode::NOT_FOUND { + return Ok(vec![]); + } + if !status.is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "ListenBrainz CF recommendations failed: {} - {}", + status, text + ))); + } + + let body = response.text().await.unwrap_or_default(); + if body.trim().is_empty() { + return Ok(vec![]); + } + // Defensive parse: tolerate any malformed payload as "no data". + let json: serde_json::Value = match serde_json::from_str(&body) { + Ok(value) => value, + Err(_) => return Ok(vec![]), + }; + + let mbids = json + .get("payload") + .and_then(|payload| payload.get("mbids")) + .and_then(|mbids| mbids.as_array()) + .cloned() + .unwrap_or_default(); + + let mut recommendations = Vec::with_capacity(mbids.len()); + for item in mbids { + let recording_mbid = match item + .get("recording_mbid") + .and_then(|value| value.as_str()) + { + Some(mbid) if !mbid.is_empty() => mbid.to_string(), + // An entry with no recording_mbid is useless downstream; skip it. + _ => continue, + }; + let score = item.get("score").and_then(|value| value.as_f64()).unwrap_or(0.0); + let latest_listened_at = item + .get("latest_listened_at") + .and_then(|value| value.as_str()) + .map(|value| value.to_string()); + + recommendations.push(CfRecommendation { + recording_mbid, + score, + latest_listened_at, + }); + } + + Ok(recommendations) + } + + /// Raw scrobble history with timestamps. + /// + /// `GET /user/{user_name}/listens?count={count}` + /// + /// The `Authorization` header is sent only when a token is configured. + /// HTTP 204/404 and empty bodies are treated as "no data" -> `Ok(vec![])`. + /// Parses `payload.listens[]` into + /// `{listened_at, track_metadata.artist_name, track_metadata.track_name, + /// track_metadata.mbid_mapping.recording_mbid}`. + pub async fn get_recent_listens( + &self, + user_name: &str, + count: u32, + ) -> IntegrationResult> { + let token = self.config.lock().await.token.clone(); + + let url = format!("{}/user/{}/listens", LISTENBRAINZ_API_URL, user_name); + + let mut request = self + .client + .get(&url) + .query(&[("count", count.to_string())]); + if let Some(token) = token { + request = request.header("Authorization", format!("Token {}", token)); + } + + let response = request.send().await?; + let status = response.status(); + + if status == reqwest::StatusCode::NO_CONTENT || status == reqwest::StatusCode::NOT_FOUND { + return Ok(vec![]); + } + if !status.is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "ListenBrainz recent listens failed: {} - {}", + status, text + ))); + } + + let body = response.text().await.unwrap_or_default(); + if body.trim().is_empty() { + return Ok(vec![]); + } + let json: serde_json::Value = match serde_json::from_str(&body) { + Ok(value) => value, + Err(_) => return Ok(vec![]), + }; + + let listens = json + .get("payload") + .and_then(|payload| payload.get("listens")) + .and_then(|listens| listens.as_array()) + .cloned() + .unwrap_or_default(); + + let mut parsed = Vec::with_capacity(listens.len()); + for item in listens { + let listened_at = item + .get("listened_at") + .and_then(|value| value.as_i64()) + .unwrap_or(0); + let track_metadata = item.get("track_metadata"); + let artist_name = track_metadata + .and_then(|meta| meta.get("artist_name")) + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + let track_name = track_metadata + .and_then(|meta| meta.get("track_name")) + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + let recording_mbid = track_metadata + .and_then(|meta| meta.get("mbid_mapping")) + .and_then(|mapping| mapping.get("recording_mbid")) + .and_then(|value| value.as_str()) + .map(|value| value.to_string()); + + parsed.push(LbListen { + listened_at, + artist_name, + track_name, + recording_mbid, + }); + } + + Ok(parsed) + } + + /// Hydrate CF `recording_mbid`s into names + artist mbids + cover art. + /// + /// `GET /metadata/recording/?recording_mbids={comma-joined}&inc=artist+release` + /// + /// The response is a JSON OBJECT keyed by `recording_mbid`: + /// ```text + /// { "": { "recording": {"name": ...}, + /// "artist": {"name": ..., "artists": [{"artist_mbid": ...}, ...]}, + /// "release": {"name": ..., "caa_id": ..., "caa_release_mbid": ...} } } + /// ``` + /// Iterates the object entries; the KEY is the `recording_mbid`. Empty input + /// short-circuits to `Ok(vec![])`. HTTP 204/404 and empty bodies are also + /// treated as "no data". + pub async fn get_metadata_recordings( + &self, + recording_mbids: &[String], + ) -> IntegrationResult> { + if recording_mbids.is_empty() { + return Ok(vec![]); + } + + let token = self.config.lock().await.token.clone(); + + let url = format!("{}/metadata/recording/", LISTENBRAINZ_API_URL); + let joined = recording_mbids.join(","); + + // `inc=artist release` is form-encoded to `inc=artist+release` by reqwest, + // which is exactly the value ListenBrainz expects. + let mut request = self.client.get(&url).query(&[ + ("recording_mbids", joined.as_str()), + ("inc", "artist release"), + ]); + if let Some(token) = token { + request = request.header("Authorization", format!("Token {}", token)); + } + + let response = request.send().await?; + let status = response.status(); + + if status == reqwest::StatusCode::NO_CONTENT || status == reqwest::StatusCode::NOT_FOUND { + return Ok(vec![]); + } + if !status.is_success() { + let text = response.text().await.unwrap_or_default(); + return Err(IntegrationError::internal(format!( + "ListenBrainz metadata recordings failed: {} - {}", + status, text + ))); + } + + let body = response.text().await.unwrap_or_default(); + if body.trim().is_empty() { + return Ok(vec![]); + } + let json: serde_json::Value = match serde_json::from_str(&body) { + Ok(value) => value, + Err(_) => return Ok(vec![]), + }; + + let object = match json.as_object() { + Some(object) => object, + None => return Ok(vec![]), + }; + + let mut recordings = Vec::with_capacity(object.len()); + for (recording_mbid, entry) in object { + let recording_name = entry + .get("recording") + .and_then(|recording| recording.get("name")) + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + + let artist = entry.get("artist"); + let artist_name = artist + .and_then(|artist| artist.get("name")) + .and_then(|value| value.as_str()) + .unwrap_or_default() + .to_string(); + let artist_mbids = artist + .and_then(|artist| artist.get("artists")) + .and_then(|artists| artists.as_array()) + .map(|artists| { + artists + .iter() + .filter_map(|credit| { + credit + .get("artist_mbid") + .and_then(|value| value.as_str()) + .map(|value| value.to_string()) + }) + .collect::>() + }) + .unwrap_or_default(); + + let release = entry.get("release"); + let release_name = release + .and_then(|release| release.get("name")) + .and_then(|value| value.as_str()) + .map(|value| value.to_string()); + let caa_id = release + .and_then(|release| release.get("caa_id")) + .and_then(|value| value.as_i64()); + let caa_release_mbid = release + .and_then(|release| release.get("caa_release_mbid")) + .and_then(|value| value.as_str()) + .map(|value| value.to_string()); + + recordings.push(LbRecordingMeta { + recording_mbid: recording_mbid.clone(), + recording_name, + artist_name, + artist_mbids, + release_name, + caa_id, + caa_release_mbid, + }); + } + + Ok(recordings) + } } diff --git a/crates/qbz-integrations/src/listenbrainz/mod.rs b/crates/qbz-integrations/src/listenbrainz/mod.rs index 9a2c1a165..244778522 100644 --- a/crates/qbz-integrations/src/listenbrainz/mod.rs +++ b/crates/qbz-integrations/src/listenbrainz/mod.rs @@ -45,6 +45,6 @@ pub mod cache; pub use client::{ListenBrainzClient, ListenBrainzConfig}; pub use models::{ - AdditionalInfo, Listen, ListenBrainzStatus, ListenType, QueuedListen, SubmitListensPayload, - TrackMetadata, UserInfo, + AdditionalInfo, CfRecommendation, LbListen, LbRecordingMeta, Listen, ListenBrainzStatus, + ListenType, QueuedListen, SubmitListensPayload, TrackMetadata, UserInfo, }; diff --git a/crates/qbz-integrations/src/listenbrainz/models.rs b/crates/qbz-integrations/src/listenbrainz/models.rs index 7331a0f9c..c699c2a3e 100644 --- a/crates/qbz-integrations/src/listenbrainz/models.rs +++ b/crates/qbz-integrations/src/listenbrainz/models.rs @@ -152,3 +152,54 @@ pub struct QueuedListen { pub attempts: i32, pub sent: bool, } + +/// Collaborative-filtering recommendation entry +/// +/// Returned by `GET /cf/recommendation/user/{user_name}/recording`. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct CfRecommendation { + /// MusicBrainz recording ID of the recommended track + pub recording_mbid: String, + /// Recommendation score (higher = stronger match) + pub score: f64, + /// ISO-8601 timestamp of the user's last listen to this recording, + /// or `None` if never listened (null/absent in the API) + pub latest_listened_at: Option, +} + +/// A single listen from a user's scrobble history +/// +/// Returned by `GET /user/{user_name}/listens`. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LbListen { + /// Unix timestamp when the track was listened to + pub listened_at: i64, + /// Artist name + pub artist_name: String, + /// Track name + pub track_name: String, + /// MusicBrainz recording ID (from `mbid_mapping`), if the listen was mapped + pub recording_mbid: Option, +} + +/// Hydrated recording metadata +/// +/// Returned by `GET /metadata/recording/`. Used to enrich CF recommendation +/// MBIDs with human-readable names, artist IDs, and cover art references. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LbRecordingMeta { + /// MusicBrainz recording ID (the response object key) + pub recording_mbid: String, + /// Recording (track) name + pub recording_name: String, + /// Primary artist credit name + pub artist_name: String, + /// MusicBrainz artist IDs that make up the credit + pub artist_mbids: Vec, + /// Release/album name, if available + pub release_name: Option, + /// Cover Art Archive image ID, if available + pub caa_id: Option, + /// Cover Art Archive release MBID, if available + pub caa_release_mbid: Option, +} diff --git a/crates/qbz-integrations/src/musicbrainz/client.rs b/crates/qbz-integrations/src/musicbrainz/client.rs index 777035963..4095e20e9 100644 --- a/crates/qbz-integrations/src/musicbrainz/client.rs +++ b/crates/qbz-integrations/src/musicbrainz/client.rs @@ -354,6 +354,25 @@ impl MusicBrainzClient { .collect()) } + /// MBID -> ISRCs bridge. Looks up a recording's ISRCs (the strong key for Qobuz matching). + /// GET {base}/recording/{recording_mbid}?inc=isrcs&fmt=json + /// Returns the ISRC list, or an EMPTY vec on any non-success/parse failure (a missing ISRC is normal, not an error). + pub async fn get_recording_isrcs(&self, recording_mbid: &str) -> IntegrationResult> { + self.check_enabled().await?; + self.rate_limiter.wait().await; + let base = self.base_url().await; + let url = format!("{}/recording/{}?inc=isrcs&fmt=json", base, recording_mbid); + let response = self.client.get(&url).send().await?; + if !response.status().is_success() { + return Ok(Vec::new()); + } + let parsed: RecordingLookupResponse = match response.json().await { + Ok(p) => p, + Err(_) => return Ok(Vec::new()), + }; + Ok(parsed.isrcs.unwrap_or_default()) + } + /// Search artists by tag (genre) pub async fn search_artists_by_tag( &self, diff --git a/crates/qbz-integrations/src/musicbrainz/models.rs b/crates/qbz-integrations/src/musicbrainz/models.rs index 191c0fa3a..ac2208238 100644 --- a/crates/qbz-integrations/src/musicbrainz/models.rs +++ b/crates/qbz-integrations/src/musicbrainz/models.rs @@ -82,6 +82,14 @@ pub struct RecordingResult { pub releases: Option>, } +/// Response from the single-recording lookup `/recording/{mbid}?inc=isrcs`. +#[derive(Debug, Deserialize)] +pub struct RecordingLookupResponse { + pub id: String, + pub title: Option, + pub isrcs: Option>, +} + /// Artist credit entry #[derive(Debug, Deserialize)] pub struct ArtistCredit {