Files
qbz/crates/qbz-lyrics/src/model.rs
T
vicrodh d12039371b feat(lyrics): qbz-lyrics engine crate with Qobuz-first chain, LRC parse/emit, providers, cache
S2 of the Lyrics epic: new shared crate crates/qbz-lyrics (headless,
frontend-agnostic per ADR-006), the whole fetch/parse/cache engine in one
testable home for Slint, Tauri and the TUI.

- Domain model: LyricsDoc/LyricsLine/Word (native Qobuz wsync word stamps
  preserved) + the Tauri-wire-compatible LyricsPayload (camelCase serde);
  LyricsProvider gains the qobuz variant and round-trips it.
- LRC parser ported from the Tauri TS semantics (gap markers as end-of-vocal,
  8s MAX_SUNG cap, median last-line end) with the F5 defects fixed forward:
  multi-stamp lines split per stamp, [offset:] honored. Emitter renders wsync
  line bounds as LRC-with-gap-markers (Q5 persistence form, lossy at word
  level only).
- Providers ported verbatim from src-tauri/src/lyrics/providers.rs: LRCLIB
  search-first + scorer and lyrics.ovh, request shapes byte-identical.
- Cache: same per-user SQLite schema/path Tauri uses (WAL per ADR-002,
  no TTL) plus the additive qobuz_wsync_json column (amended Q5) with an
  idempotent in-place migration for Tauri-era DBs; readers prefer wsync.
  Stats read entries AND size from the per-user path (F1 fix).
- Orchestrator LyricsService: cache probe with uniform plain-only soft miss
  (Q4) -> Qobuz primary (wsync authoritative; plain held while LRCLIB is
  probed for synced, the no-sync-regression rule) -> LRCLIB with one retry
  on transport error -> lyrics.ovh; offline = cache-only with typed
  NotAvailableOffline (F3); in-flight dedupe via shared futures (F6);
  request-key echo on every response for the caller stale guard (F2).
- 55 unit tests: parser/emitter round-trips, scorer matrix, cache lifecycle
  + schema migration, chain priority/offline/dedupe with mocked providers.

cc
2026-06-10 16:22:57 -06:00

322 lines
11 KiB
Rust

//! Lyrics domain model.
//!
//! [`LyricsPayload`] keeps the EXACT camelCase serde shape of Tauri's
//! `src-tauri/src/lyrics/mod.rs:15-27` so a later re-pointed `v2_lyrics_get`
//! stays wire-identical for the Svelte store (spec §2.2.2). [`LyricsDoc`] is
//! the structured form both frontends consume — the service parses internally
//! (native wsync or LRC) and returns structured lines, so no frontend
//! re-implements the TS parser.
use serde::{Deserialize, Serialize};
use crate::lrc;
/// Lyrics source provider. Tauri's enum (`src-tauri/src/lyrics/mod.rs:29-50`)
/// plus the new first-party `Qobuz` variant; serialized lowercase
/// (`'lrclib' | 'ovh' | 'qobuz'` on the JS side).
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum LyricsProvider {
Lrclib,
Ovh,
Qobuz,
}
impl LyricsProvider {
pub fn as_str(&self) -> &'static str {
match self {
Self::Lrclib => "lrclib",
Self::Ovh => "ovh",
Self::Qobuz => "qobuz",
}
}
/// Parse a stored provider string. Unknown values collapse to `Lrclib`
/// (parity with Tauri `mod.rs:44-49`); `"qobuz"` round-trips (spec §1.4).
#[allow(clippy::should_implement_trait)]
pub fn from_str(value: &str) -> Self {
match value {
"ovh" => Self::Ovh,
"qobuz" => Self::Qobuz,
_ => Self::Lrclib,
}
}
}
/// Wire-compatible lyrics payload (Tauri `LyricsPayload`, camelCase serde).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(rename_all = "camelCase")]
pub struct LyricsPayload {
pub track_id: Option<u64>,
pub title: String,
pub artist: String,
pub album: Option<String>,
pub duration_secs: Option<u64>,
pub plain: Option<String>,
pub synced_lrc: Option<String>,
pub provider: LyricsProvider,
pub cached: bool,
}
/// One word inside a synced line (Qobuz wsync only; `start`/`end` are ms from
/// track start). Word-level timing is richer than LRC — preserved natively in
/// the model for word-anchored karaoke fill (spec Addendum 2, Q2 enriched).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct Word {
pub start: i64,
pub end: i64,
pub text: String,
}
/// One lyrics line in the domain model.
///
/// - Synced lines carry `time_ms` (and usually `end_ms`); plain lines carry
/// neither.
/// - `words` is `Some` only for Qobuz wsync documents.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
pub struct LyricsLine {
pub time_ms: Option<i64>,
pub end_ms: Option<i64>,
pub text: String,
pub words: Option<Vec<Word>>,
}
/// Parsed, render-ready lyrics document.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct LyricsDoc {
pub lines: Vec<LyricsLine>,
pub synced: bool,
pub provider: LyricsProvider,
/// ISO 639-1 codes Qobuz offers translations for (metadata passthrough;
/// empty for non-Qobuz providers).
pub translation_langs: Vec<String>,
/// Songwriter credits display string (Qobuz metadata passthrough).
pub writers: Option<String>,
}
impl LyricsDoc {
/// Empty document (status "no lyrics").
pub fn empty(provider: LyricsProvider) -> Self {
Self {
lines: Vec::new(),
synced: false,
provider,
translation_langs: Vec::new(),
writers: None,
}
}
/// Build from an LRC text blob (fallback-provider path).
pub fn from_lrc(lrc_text: &str, provider: LyricsProvider) -> Self {
let lines = lrc::parse_lrc(lrc_text);
let synced = !lines.is_empty();
Self {
lines,
synced,
provider,
translation_langs: Vec::new(),
writers: None,
}
}
/// Build from a plain text blob (no timestamps).
pub fn from_plain_text(plain: &str, provider: LyricsProvider) -> Self {
Self {
lines: lrc::parse_plain(plain),
synced: false,
provider,
translation_langs: Vec::new(),
writers: None,
}
}
/// Build from a wire payload. Synced wins over plain: try `synced_lrc`
/// first; fall to `plain` only when the LRC parse produced zero lines
/// (parity with the TS `parsePayload`, `lyricsStore.ts:201-214`).
pub fn from_payload(payload: &LyricsPayload) -> Self {
if let Some(lrc_text) = payload.synced_lrc.as_deref() {
if !lrc_text.trim().is_empty() {
let doc = Self::from_lrc(lrc_text, payload.provider);
if !doc.lines.is_empty() {
return doc;
}
}
}
if let Some(plain) = payload.plain.as_deref() {
if !plain.trim().is_empty() {
return Self::from_plain_text(plain, payload.provider);
}
}
Self::empty(payload.provider)
}
/// Build from a cached row. Readers PREFER the native wsync document when
/// present (amended Q5): word timestamps survive the cache; the LRC column
/// stays the cross-frontend lingua franca.
pub fn from_cached(payload: &LyricsPayload, qobuz_wsync_json: Option<&str>) -> Self {
if payload.provider == LyricsProvider::Qobuz {
if let Some(json) = qobuz_wsync_json {
match serde_json::from_str::<crate::wsync::QobuzWsync>(json) {
Ok(wsync) => {
let doc = wsync.to_doc();
if !doc.lines.is_empty() {
return doc;
}
}
Err(e) => {
log::warn!("[Lyrics] unparsable cached wsync json ({}); falling back to LRC", e);
}
}
}
}
Self::from_payload(payload)
}
/// Join line texts with `\n` (uniform plain rendering / copy-lyrics).
pub fn plain_text(&self) -> String {
self.lines
.iter()
.map(|line| line.text.as_str())
.collect::<Vec<_>>()
.join("\n")
}
}
/// Cache key: `"{norm_artist}::{norm_title}::{duration_or_0}"`
/// (parity: Tauri `mod.rs:98-103`).
pub fn build_cache_key(title: &str, artist: &str, duration_secs: Option<u64>) -> String {
let normalized_title = normalize(title);
let normalized_artist = normalize(artist);
let duration = duration_secs.unwrap_or(0);
format!("{}::{}::{}", normalized_artist, normalized_title, duration)
}
/// Normalize = lowercase + whitespace-collapse (parity: Tauri `mod.rs:105-111`).
pub fn normalize(value: &str) -> String {
value
.to_lowercase()
.split_whitespace()
.collect::<Vec<_>>()
.join(" ")
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn cache_key_normalizes_and_defaults_duration() {
assert_eq!(
build_cache_key(" My Song ", "The ARTIST", Some(215)),
"the artist::my song::215"
);
assert_eq!(build_cache_key("A", "B", None), "b::a::0");
}
#[test]
fn provider_round_trips_qobuz_and_collapses_unknowns() {
for provider in [
LyricsProvider::Lrclib,
LyricsProvider::Ovh,
LyricsProvider::Qobuz,
] {
assert_eq!(LyricsProvider::from_str(provider.as_str()), provider);
}
// Unknown strings collapse to Lrclib (Tauri parity).
assert_eq!(LyricsProvider::from_str("musixmatch"), LyricsProvider::Lrclib);
}
#[test]
fn payload_serde_shape_is_tauri_wire_compatible() {
let payload = LyricsPayload {
track_id: Some(42),
title: "T".into(),
artist: "A".into(),
album: None,
duration_secs: Some(200),
plain: Some("p".into()),
synced_lrc: None,
provider: LyricsProvider::Qobuz,
cached: true,
};
let json = serde_json::to_value(&payload).unwrap();
assert_eq!(json["trackId"], 42);
assert_eq!(json["durationSecs"], 200);
assert_eq!(json["syncedLrc"], serde_json::Value::Null);
assert_eq!(json["provider"], "qobuz");
assert_eq!(json["cached"], true);
}
#[test]
fn from_payload_prefers_synced_falls_back_to_plain() {
let mut payload = LyricsPayload {
track_id: None,
title: "T".into(),
artist: "A".into(),
album: None,
duration_secs: None,
plain: Some("line one\nline two".into()),
synced_lrc: Some("[00:01.00] hello\n[00:03.00] world".into()),
provider: LyricsProvider::Lrclib,
cached: false,
};
let doc = LyricsDoc::from_payload(&payload);
assert!(doc.synced);
assert_eq!(doc.lines.len(), 2);
assert_eq!(doc.lines[0].text, "hello");
// Garbage LRC (zero parsed lines) falls back to plain.
payload.synced_lrc = Some("no timestamps here".into());
let doc = LyricsDoc::from_payload(&payload);
assert!(!doc.synced);
assert_eq!(doc.lines.len(), 2);
assert_eq!(doc.lines[0].text, "line one");
assert_eq!(doc.lines[0].time_ms, None);
// Nothing usable -> empty.
payload.synced_lrc = None;
payload.plain = Some(" ".into());
let doc = LyricsDoc::from_payload(&payload);
assert!(doc.lines.is_empty());
}
#[test]
fn from_cached_prefers_wsync_over_lrc() {
let payload = LyricsPayload {
track_id: Some(1),
title: "T".into(),
artist: "A".into(),
album: None,
duration_secs: None,
plain: Some("hello".into()),
synced_lrc: Some("[00:01.00] hello".into()),
provider: LyricsProvider::Qobuz,
cached: true,
};
let wsync_json = r#"{"type":"wsync","lang":"en","lines":[
{"line":"hello","start":1000,"end":2000,
"words":[{"word":"hello","start":1000,"end":2000}]}
]}"#;
let doc = LyricsDoc::from_cached(&payload, Some(wsync_json));
assert!(doc.synced);
let words = doc.lines[0].words.as_ref().expect("native words preserved");
assert_eq!(words[0].text, "hello");
// Without the column, the LRC path applies (no words).
let doc = LyricsDoc::from_cached(&payload, None);
assert!(doc.synced);
assert!(doc.lines[0].words.is_none());
// Corrupt wsync json degrades to the LRC path instead of erroring.
let doc = LyricsDoc::from_cached(&payload, Some("{not json"));
assert!(doc.synced);
assert!(doc.lines[0].words.is_none());
}
#[test]
fn plain_text_joins_lines() {
let doc = LyricsDoc::from_plain_text("a\n\n b \nc", LyricsProvider::Ovh);
assert_eq!(doc.plain_text(), "a\nb\nc");
}
}