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:
vicrodh committed 2026-06-27 02:37:32 -06:00
1 parent 2e1d8e431d
commit 408b3c8308
17 files changed
+2236 -5

No files matched your search

+15
View File
@@ -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"
+1
View File
@@ -35,6 +35,7 @@ members = [
"qbz-i18n",
"qbz-music-link",
"qbz-reco",
"qbz-external-reco",
]
[workspace.package]
+25
View File
@@ -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 }
+154
View File
@@ -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);
}
}
+546
View File
@@ -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,
}
}
+88
View File
@@ -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
}
+222
View File
@@ -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");
}
}
+103
View File
@@ -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>,
}
+191
View File
@@ -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
}
+464 -2
View File
@@ -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)
}
+3 -1
View File
@@ -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 {