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
This commit is contained in:
17 files changed
+2236
-5
No files matched your search
Generated
+15
@@ -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"
|
||||
|
||||
@@ -35,6 +35,7 @@ members = [
|
||||
"qbz-i18n",
|
||||
"qbz-music-link",
|
||||
"qbz-reco",
|
||||
"qbz-external-reco",
|
||||
]
|
||||
|
||||
[workspace.package]
|
||||
|
||||
@@ -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 }
|
||||
@@ -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 `<base_dir>/external_reco_cache.db`.
|
||||
pub fn open_at(base_dir: &Path) -> Result<Self, String> {
|
||||
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<String>, 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);
|
||||
}
|
||||
}
|
||||
@@ -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<RecoCache>>;
|
||||
|
||||
/// 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<String>,
|
||||
/// Tracks the user has scrobbled — excludes C2 / C4.
|
||||
track_keys: HashSet<String>,
|
||||
}
|
||||
|
||||
/// Interleave candidate groups round-robin so every connected source is fairly
|
||||
/// represented (the Option-B blend).
|
||||
fn round_robin<T>(groups: Vec<Vec<T>>) -> Vec<T> {
|
||||
let mut iters: Vec<std::vec::IntoIter<T>> = 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<T>(mut pool: Vec<T>, seed: u64, take: usize) -> Vec<T> {
|
||||
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<TrackCandidate>,
|
||||
) -> Vec<TrackReco> {
|
||||
let resolved: Vec<Option<TrackReco>> = 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<ArtistCandidate>,
|
||||
) -> Vec<ArtistReco> {
|
||||
let resolved: Vec<Option<ArtistReco>> = 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<qbz_integrations::listenbrainz::LbRecordingMeta> {
|
||||
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<String> = 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<ArtistReco> {
|
||||
let mut lastfm_group: Vec<ArtistCandidate> = 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<String> = 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::<Vec<_>>()
|
||||
.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<ArtistCandidate> = 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<String> = HashSet::new();
|
||||
let candidates: Vec<ArtistCandidate> = 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<TrackReco> {
|
||||
// LB: CF recordings (already never-listened).
|
||||
let total = lb_cf_unheard.len().max(1) as f32;
|
||||
let lb_group: Vec<TrackCandidate> = 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<TrackCandidate> = 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::<Vec<_>>()
|
||||
.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<String> = HashSet::new();
|
||||
let candidates: Vec<TrackCandidate> = 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<TrackReco> {
|
||||
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<String> = recent
|
||||
.unwrap_or_default()
|
||||
.into_iter()
|
||||
.map(|t| track_key(&t.artist, &t.name))
|
||||
.collect();
|
||||
|
||||
let mut seen: HashSet<String> = HashSet::new();
|
||||
let candidates: Vec<TrackCandidate> = 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<TrackReco> {
|
||||
if inputs.local.known_artist_ids.is_empty() {
|
||||
return Vec::new();
|
||||
}
|
||||
// Rotate which known artists we mine today.
|
||||
let mut ids: Vec<u64> = 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::<Vec<_>>()
|
||||
.await;
|
||||
|
||||
let mut seen: HashSet<u64> = HashSet::new();
|
||||
let mut pool: Vec<TrackReco> = 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<String> = HashSet::new();
|
||||
let mut top_albums: Vec<AlbumReco> = 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<u64> = 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<ArtistReco> = 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,
|
||||
}
|
||||
}
|
||||
@@ -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<Track>;
|
||||
/// Qobuz artist search (for validating a recommended artist name).
|
||||
async fn search_artists(&self, query: &str, limit: usize) -> Vec<Artist>;
|
||||
/// An artist's top tracks (the deep-cut candidate source for C4).
|
||||
async fn artist_top_tracks(&self, artist_id: u64, limit: usize) -> Vec<Track>;
|
||||
/// Editorial featured albums by kind ("most-streamed" | "new-releases" | …).
|
||||
async fn featured_albums(&self, kind: &str, limit: usize) -> Vec<Album>;
|
||||
/// Full artist by id (cold-start top-artist portraits).
|
||||
async fn get_artist(&self, artist_id: u64) -> Option<Artist>;
|
||||
}
|
||||
|
||||
/// 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<LastFmHandle<'a>>,
|
||||
pub listenbrainz: Option<ListenBrainzHandle<'a>>,
|
||||
pub musicbrainz: &'a MusicBrainzClient,
|
||||
pub catalog: &'a dyn RecoCatalog,
|
||||
/// Optional resolution cache (per-user SQLite). `None` disables caching.
|
||||
pub cache: Option<&'a Mutex<RecoCache>>,
|
||||
/// 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
|
||||
}
|
||||
@@ -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<u64>,
|
||||
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::<Vec<_>>()
|
||||
.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");
|
||||
}
|
||||
}
|
||||
@@ -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<String>,
|
||||
pub duration_ms: Option<u64>,
|
||||
pub isrc: Option<String>,
|
||||
pub recording_mbid: Option<String>,
|
||||
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<ArtistReco>,
|
||||
/// C2 — "Similar tracks you haven't heard".
|
||||
pub similar_tracks: Vec<TrackReco>,
|
||||
/// C3 — "Listened but not recently".
|
||||
pub rediscover_tracks: Vec<TrackReco>,
|
||||
/// C4 — "From artists you know but not scrobbled" (deep cuts).
|
||||
pub deep_cut_tracks: Vec<TrackReco>,
|
||||
/// Cold-start fallback: Qobuz editorial top albums.
|
||||
pub top_albums: Vec<AlbumReco>,
|
||||
/// Cold-start fallback: Qobuz editorial top artists.
|
||||
pub top_artists: Vec<ArtistReco>,
|
||||
}
|
||||
|
||||
/// 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<u64>,
|
||||
/// Tracks played in-app (the local "already heard" set).
|
||||
pub played_track_ids: std::collections::HashSet<u64>,
|
||||
}
|
||||
@@ -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<RecoCache>>;
|
||||
|
||||
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<Track> {
|
||||
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<TrackReco> {
|
||||
// 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<TrackReco> {
|
||||
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::<TrackReco>(&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<ArtistReco> {
|
||||
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::<ArtistReco>(&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
|
||||
}
|
||||
@@ -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<Vec<LastFmArtist>> {
|
||||
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<Vec<LastFmTrack>> {
|
||||
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<Vec<LastFmTrack>> {
|
||||
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<Vec<LastFmTrack>> {
|
||||
// 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<Vec<LastFmSimilarTrack>> {
|
||||
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<String> {
|
||||
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<String>` (empty strings become `None`).
|
||||
fn extract_mbid(value: &serde_json::Value) -> Option<String> {
|
||||
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<i64> {
|
||||
value
|
||||
.get("date")
|
||||
.and_then(|d| d.get("uts"))
|
||||
.and_then(|u| {
|
||||
u.as_str()
|
||||
.and_then(|s| s.parse::<i64>().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::<u64>().ok())
|
||||
.or_else(|| v.as_u64())
|
||||
})
|
||||
.unwrap_or(0)
|
||||
}
|
||||
@@ -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,
|
||||
};
|
||||
@@ -60,3 +60,48 @@ pub struct LastFmSimilarArtist {
|
||||
/// MusicBrainz ID if available
|
||||
pub mbid: Option<String>,
|
||||
}
|
||||
|
||||
/// 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<String>,
|
||||
/// Number of times the user has played this artist
|
||||
pub playcount: u64,
|
||||
/// Largest available image URL, if any
|
||||
pub image: Option<String>,
|
||||
}
|
||||
|
||||
/// 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<String>,
|
||||
/// Track MusicBrainz ID if available
|
||||
pub mbid: Option<String>,
|
||||
/// Album name if available
|
||||
pub album: Option<String>,
|
||||
/// Largest available image URL, if any
|
||||
pub image: Option<String>,
|
||||
/// Unix timestamp of the scrobble / love, if available
|
||||
pub uts: Option<i64>,
|
||||
}
|
||||
|
||||
/// 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<String>,
|
||||
/// Raw match weight (NOT normalized to 0..1)
|
||||
pub match_score: f64,
|
||||
}
|
||||
@@ -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<Vec<CfRecommendation>> {
|
||||
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<Vec<LbListen>> {
|
||||
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
|
||||
/// { "<mbid>": { "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<Vec<LbRecordingMeta>> {
|
||||
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::<Vec<String>>()
|
||||
})
|
||||
.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)
|
||||
}
|
||||
}
|
||||
@@ -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,
|
||||
};
|
||||
@@ -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<String>,
|
||||
}
|
||||
|
||||
/// 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<String>,
|
||||
}
|
||||
|
||||
/// 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<String>,
|
||||
/// Release/album name, if available
|
||||
pub release_name: Option<String>,
|
||||
/// Cover Art Archive image ID, if available
|
||||
pub caa_id: Option<i64>,
|
||||
/// Cover Art Archive release MBID, if available
|
||||
pub caa_release_mbid: Option<String>,
|
||||
}
|
||||
@@ -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<Vec<String>> {
|
||||
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,
|
||||
|
||||
@@ -82,6 +82,14 @@ pub struct RecordingResult {
|
||||
pub releases: Option<Vec<ReleaseRef>>,
|
||||
}
|
||||
|
||||
/// Response from the single-recording lookup `/recording/{mbid}?inc=isrcs`.
|
||||
#[derive(Debug, Deserialize)]
|
||||
pub struct RecordingLookupResponse {
|
||||
pub id: String,
|
||||
pub title: Option<String>,
|
||||
pub isrcs: Option<Vec<String>>,
|
||||
}
|
||||
|
||||
/// Artist credit entry
|
||||
#[derive(Debug, Deserialize)]
|
||||
pub struct ArtistCredit {
|
||||
|
||||
Reference in new issue
Block a user