feat(slint): lyrics sync engine with karaoke fill and auto-center scroll
S4 of the lyrics epic: ms-precision position source, 30Hz sync engine, word-anchored karaoke fill, auto-centered ladder scroll, QConnect peer following. - qbz-player: read-only SharedState::current_position_ms() derived from the existing playback_start_millis/position_at_start anchors (Q1; no stream/seek/format path touched) + unit test - qbz-lyrics: new sync module porting the Tauri active-line math (binary search active index, per-line progress with the 0.99 snap) plus the word-anchored clip fraction for Qobuz wsync lines (char-proportional word width approximation, Q2); unit tests - qbz-slint: lyrics_sync engine - adaptive slint::Timer (33ms while panel open + synced + playing, 250ms gate polling otherwise), equality-guarded pushes, fill animation zeroed across discontinuities (line change / backward seek); kick() on doc commit and panel open - QConnect (Q7): the poll loop controller branch publishes the raw renderer anchor; the engine extrapolates it per tick so lyrics follow the peer (Tauri freezes); local fallthrough clears the anchor - LyricsLinesView: karaoke fill via clipped bright overlay text over the dim base (rect-clip approximation, D5); auto-center scroll from layout-relative active-row geometry, smooth for <=2-line moves and instant for jumps/initial sync, animated via a separate scroll-target property so user wheel input is never animated - LyricsState: line-progress + fill-anim-ms properties cc
This commit is contained in:
9 files changed
+761
-18
No files matched your search
@@ -46,9 +46,10 @@ use qbz_qobuz::{QobuzClient, QobuzLyricsDocument};
|
||||
use crate::{AppWindow, LyricsLineItem, LyricsState};
|
||||
|
||||
// `LyricsState.status` values (keep in sync with `ui/state.slint`).
|
||||
// `READY` is pub(crate): the sync engine (`lyrics_sync`) gates on it.
|
||||
const STATUS_IDLE: i32 = 0;
|
||||
const STATUS_LOADING: i32 = 1;
|
||||
const STATUS_READY: i32 = 2;
|
||||
pub(crate) const STATUS_READY: i32 = 2;
|
||||
const STATUS_NOT_FOUND: i32 = 3;
|
||||
const STATUS_ERROR: i32 = 4;
|
||||
const STATUS_OFFLINE: i32 = 5;
|
||||
@@ -75,6 +76,16 @@ static CURRENT: Mutex<CurrentLyrics> = Mutex::new(CurrentLyrics {
|
||||
/// carries text + line bounds + a has-words flag).
|
||||
static CURRENT_DOC: Mutex<Option<LyricsDoc>> = Mutex::new(None);
|
||||
|
||||
/// Read access to the current parsed document for the sync engine: the
|
||||
/// closure runs under the lock (keep it short — it executes on the UI
|
||||
/// thread at the engine's tick rate). A poisoned lock degrades to `None`.
|
||||
pub(crate) fn with_current_doc<R>(f: impl FnOnce(Option<&LyricsDoc>) -> R) -> R {
|
||||
match CURRENT_DOC.lock() {
|
||||
Ok(guard) => f(guard.as_ref()),
|
||||
Err(_) => f(None),
|
||||
}
|
||||
}
|
||||
|
||||
/// Production providers over the shared core client lock. The lock is read
|
||||
/// at CALL time (never cached), so re-inits of the Qobuz client are always
|
||||
/// picked up; a missing client (pre-login, offline boot) errors out, which
|
||||
@@ -253,6 +264,8 @@ pub fn on_track_changed(weak: slint::Weak<AppWindow>, track: &QueueTrack) {
|
||||
state.set_lines(ModelRc::new(VecModel::default()));
|
||||
state.set_synced(false);
|
||||
state.set_active_index(-1);
|
||||
state.set_line_progress(0.0);
|
||||
state.set_fill_anim_ms(0);
|
||||
state.set_provider("".into());
|
||||
state.set_provider_label("".into());
|
||||
state.set_error("".into());
|
||||
@@ -301,6 +314,8 @@ pub fn on_track_cleared(weak: slint::Weak<AppWindow>) {
|
||||
state.set_lines(ModelRc::new(VecModel::default()));
|
||||
state.set_synced(false);
|
||||
state.set_active_index(-1);
|
||||
state.set_line_progress(0.0);
|
||||
state.set_fill_anim_ms(0);
|
||||
state.set_track_title("".into());
|
||||
state.set_track_artist("".into());
|
||||
state.set_provider("".into());
|
||||
@@ -370,6 +385,13 @@ fn apply_result(weak: slint::Weak<AppWindow>, result: Result<LyricsResponse, Str
|
||||
state.set_provider_label(label.into());
|
||||
state.set_error(error.into());
|
||||
state.set_active_index(-1);
|
||||
state.set_line_progress(0.0);
|
||||
state.set_fill_anim_ms(0);
|
||||
state.set_status(status);
|
||||
// One immediate engine pass so a freshly committed doc lands on the
|
||||
// correct line right away — even while PAUSED (Tauri computes once on
|
||||
// load, lyricsStore.ts:386-389); continuous ticking stays gated on
|
||||
// playing.
|
||||
crate::lyrics_sync::kick();
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,231 @@
|
||||
//! S4 lyrics sync engine — drives `LyricsState.active-index` /
|
||||
//! `line-progress` from the playback position (spec §4).
|
||||
//!
|
||||
//! # Tick / push design
|
||||
//!
|
||||
//! ONE `slint::Timer` on the UI thread, started once for the app lifetime,
|
||||
//! with an ADAPTIVE cadence:
|
||||
//!
|
||||
//! - **active ~30Hz (33ms)** while the gate is open: `lyrics panel open &&
|
||||
//! doc synced+ready && effectively playing` (1:1 to Tauri's rAF gate,
|
||||
//! `+page.svelte:6145-6157`);
|
||||
//! - **idle 250ms** otherwise — the tick then only re-checks the gate (a few
|
||||
//! property reads; something must observe the gate since Slint global
|
||||
//! properties have no Rust-side reactivity. Tauri leans on Svelte
|
||||
//! subscriptions for the same job).
|
||||
//!
|
||||
//! Every active tick recomputes the active index + karaoke fraction from the
|
||||
//! ABSOLUTE position (binary search over `CURRENT_DOC` — `qbz_lyrics::sync`),
|
||||
//! which makes seeks inherently safe: no smoothing ever crosses a
|
||||
//! discontinuity because the engine zeroes `fill-anim-ms` whenever the index
|
||||
//! changes or the fraction moves backward. Pause closes the gate → the last
|
||||
//! pushed state freezes in place (parity). Pushes are equality-guarded so an
|
||||
//! unchanged tick writes nothing.
|
||||
//!
|
||||
//! The 450ms playback poll loop is NOT touched (load-bearing for QConnect
|
||||
//! report cadence + gapless edges); this timer is a parallel ms-precision
|
||||
//! read used only by lyrics.
|
||||
//!
|
||||
//! # Position resolver (Q7 — lyrics FOLLOW the QConnect peer)
|
||||
//!
|
||||
//! - **Local playback**: `SharedState::current_position_ms()` — the
|
||||
//! read-only ms getter on `qbz-player` (Q1; pure derivation from the
|
||||
//! existing `playback_start_millis`/`position_at_start` anchors).
|
||||
//! - **Peer renderer active (controller mode)**: the poll loop's controller
|
||||
//! branch publishes the RAW renderer snapshot anchor here every ~450ms
|
||||
//! ([`publish_remote_anchor`]); each engine tick extrapolates
|
||||
//! `position_ms + (now - updated_at_ms)` while playing — the exact
|
||||
//! controller-branch trick (`playback.rs` peer-position push). Tauri's
|
||||
//! lyrics freeze under a peer; this is the documented D7 improvement.
|
||||
//!
|
||||
//! [`kick`] runs one immediate pass that ignores the playing gate: called on
|
||||
//! doc commit and panel open so the ladder lands on the correct line
|
||||
//! instantly, even while paused (Tauri computes once on load).
|
||||
|
||||
use std::cell::{Cell, RefCell};
|
||||
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
|
||||
use std::sync::Arc;
|
||||
use std::time::Duration;
|
||||
|
||||
use slint::{ComponentHandle, Timer, TimerMode};
|
||||
|
||||
use qbz_app::shell::AppRuntime;
|
||||
|
||||
use crate::adapter::SlintAdapter;
|
||||
use crate::{AppWindow, LyricsState, ShellState};
|
||||
|
||||
type Runtime = Arc<AppRuntime<SlintAdapter>>;
|
||||
|
||||
/// Active cadence ~30Hz — within Tauri's effective granularity class; the
|
||||
/// clip-width animation interpolates between ticks (spec §4.1).
|
||||
const ACTIVE_TICK: Duration = Duration::from_millis(33);
|
||||
/// Idle cadence: gate polling only.
|
||||
const IDLE_TICK: Duration = Duration::from_millis(250);
|
||||
/// Clip-width animation duration while progress is continuous — slightly
|
||||
/// above the tick interval so a late tick doesn't stutter the fill.
|
||||
const FILL_ANIM_MS: i32 = 45;
|
||||
|
||||
// ---- QConnect remote position anchor (Q7) ----------------------------------
|
||||
// Raw renderer snapshot published by the poll loop's controller branch
|
||||
// (~450ms); the engine extrapolates between publishes. Plain atomics — both
|
||||
// sides touch them at low rates and a torn read across fields self-corrects
|
||||
// on the next tick.
|
||||
static REMOTE_ACTIVE: AtomicBool = AtomicBool::new(false);
|
||||
static REMOTE_POSITION_MS: AtomicU64 = AtomicU64::new(0);
|
||||
static REMOTE_UPDATED_AT_MS: AtomicU64 = AtomicU64::new(0);
|
||||
static REMOTE_PLAYING: AtomicBool = AtomicBool::new(false);
|
||||
|
||||
/// Publish the RAW peer-renderer anchor (NOT the already-extrapolated
|
||||
/// position — the engine extrapolates itself at tick time). Called from the
|
||||
/// poll loop's controller branch on every tick while a peer owns playback.
|
||||
pub fn publish_remote_anchor(position_ms: u64, updated_at_ms: u64, playing: bool) {
|
||||
REMOTE_POSITION_MS.store(position_ms, Ordering::Relaxed);
|
||||
REMOTE_UPDATED_AT_MS.store(updated_at_ms, Ordering::Relaxed);
|
||||
REMOTE_PLAYING.store(playing, Ordering::Relaxed);
|
||||
REMOTE_ACTIVE.store(true, Ordering::Release);
|
||||
}
|
||||
|
||||
/// Drop back to the local position source. Called from the poll loop's
|
||||
/// local fallthrough (every tick while no peer is active — cheap).
|
||||
pub fn clear_remote_anchor() {
|
||||
REMOTE_ACTIVE.store(false, Ordering::Release);
|
||||
}
|
||||
|
||||
thread_local! {
|
||||
static TIMER: Timer = Timer::default();
|
||||
static FAST: Cell<bool> = const { Cell::new(false) };
|
||||
static CTX: RefCell<Option<(Runtime, slint::Weak<AppWindow>)>> =
|
||||
const { RefCell::new(None) };
|
||||
}
|
||||
|
||||
/// Start the engine timer. UI-thread only (slint::Timer requirement);
|
||||
/// idempotent — called once from shell setup in `main`.
|
||||
pub fn start(runtime: Runtime, weak: slint::Weak<AppWindow>) {
|
||||
CTX.with(|ctx| {
|
||||
*ctx.borrow_mut() = Some((runtime, weak));
|
||||
});
|
||||
TIMER.with(|timer| {
|
||||
if timer.running() {
|
||||
return;
|
||||
}
|
||||
timer.start(TimerMode::Repeated, IDLE_TICK, || tick(true));
|
||||
});
|
||||
}
|
||||
|
||||
/// One immediate engine pass that bypasses the playing gate (panel-open /
|
||||
/// doc-commit recompute — the view lands on the correct line instantly even
|
||||
/// while paused). No-op before [`start`] or off the UI thread's context.
|
||||
pub fn kick() {
|
||||
tick(false);
|
||||
}
|
||||
|
||||
fn tick(require_playing: bool) {
|
||||
let Some((runtime, weak)) = CTX.with(|ctx| ctx.borrow().clone()) else {
|
||||
return;
|
||||
};
|
||||
let Some(window) = weak.upgrade() else {
|
||||
return;
|
||||
};
|
||||
let fast = compute_and_push(&window, &runtime, require_playing);
|
||||
set_cadence(fast);
|
||||
}
|
||||
|
||||
fn set_cadence(fast: bool) {
|
||||
FAST.with(|flag| {
|
||||
if flag.get() == fast {
|
||||
return;
|
||||
}
|
||||
flag.set(fast);
|
||||
TIMER.with(|timer| {
|
||||
timer.set_interval(if fast { ACTIVE_TICK } else { IDLE_TICK });
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
/// Effective playback position in ms + the effective playing flag (the Q7
|
||||
/// resolver — see module docs).
|
||||
fn resolve_position_ms(runtime: &Runtime) -> (u64, bool) {
|
||||
if REMOTE_ACTIVE.load(Ordering::Acquire) {
|
||||
let playing = REMOTE_PLAYING.load(Ordering::Relaxed);
|
||||
let mut position_ms = REMOTE_POSITION_MS.load(Ordering::Relaxed);
|
||||
let updated_at_ms = REMOTE_UPDATED_AT_MS.load(Ordering::Relaxed);
|
||||
if playing && updated_at_ms > 0 {
|
||||
position_ms = position_ms.saturating_add(now_ms().saturating_sub(updated_at_ms));
|
||||
}
|
||||
(position_ms, playing)
|
||||
} else {
|
||||
let player = runtime.core().player();
|
||||
(
|
||||
player.state.current_position_ms(),
|
||||
player.state.is_playing(),
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
/// Compute the active index + karaoke fraction and push them onto
|
||||
/// `LyricsState` — equality-guarded, animation zeroed across
|
||||
/// discontinuities. Returns whether the gate is fully open (open + synced +
|
||||
/// playing) so the caller can pick the cadence.
|
||||
fn compute_and_push(window: &AppWindow, runtime: &Runtime, require_playing: bool) -> bool {
|
||||
if !window.global::<ShellState>().get_lyrics_open() {
|
||||
return false;
|
||||
}
|
||||
let lyrics = window.global::<LyricsState>();
|
||||
if !lyrics.get_synced() || lyrics.get_status() != crate::lyrics::STATUS_READY {
|
||||
return false;
|
||||
}
|
||||
|
||||
let (position_ms, playing) = resolve_position_ms(runtime);
|
||||
if require_playing && !playing {
|
||||
// Pause freezes the ladder + fill in place (Tauri parity: the rAF
|
||||
// gate stops, getCurrentTime holds — review §8 "Pause").
|
||||
return false;
|
||||
}
|
||||
|
||||
let now = position_ms.min(i64::MAX as u64) as i64;
|
||||
let (index, fraction) = crate::lyrics::with_current_doc(|doc| match doc {
|
||||
Some(doc) if doc.synced && !doc.lines.is_empty() => {
|
||||
let index = qbz_lyrics::sync::find_active_line_index(&doc.lines, now);
|
||||
let fraction = if index >= 0 {
|
||||
qbz_lyrics::sync::line_fill_fraction(&doc.lines, index as usize, now)
|
||||
} else {
|
||||
0.0
|
||||
};
|
||||
(index, fraction)
|
||||
}
|
||||
_ => (-1, 0.0),
|
||||
});
|
||||
|
||||
// Push only on change. The properties themselves are the previous-tick
|
||||
// state (the commit path resets them with the doc), so the engine stays
|
||||
// stateless across track changes / re-opens.
|
||||
let ui_index = lyrics.get_active_index();
|
||||
let ui_progress = lyrics.get_line_progress();
|
||||
let index_changed = index != ui_index;
|
||||
let backward = fraction < ui_progress - 0.0005;
|
||||
// Discontinuity (line change / backward seek): first paint EXACTLY at
|
||||
// the reported progress — no smoothing across it (parity with
|
||||
// LyricsLines.svelte:114-138).
|
||||
let anim_ms = if index_changed || backward { 0 } else { FILL_ANIM_MS };
|
||||
if lyrics.get_fill_anim_ms() != anim_ms {
|
||||
lyrics.set_fill_anim_ms(anim_ms);
|
||||
}
|
||||
if index_changed {
|
||||
lyrics.set_active_index(index);
|
||||
}
|
||||
if index_changed || (fraction - ui_progress).abs() >= 0.001 {
|
||||
lyrics.set_line_progress(fraction);
|
||||
}
|
||||
|
||||
playing
|
||||
}
|
||||
|
||||
/// Wall-clock now in epoch ms — same convention as the poll loop's
|
||||
/// extrapolation (`playback.rs::now_ms`) and the renderer's
|
||||
/// `updated_at_ms`.
|
||||
fn now_ms() -> u64 {
|
||||
std::time::SystemTime::now()
|
||||
.duration_since(std::time::UNIX_EPOCH)
|
||||
.map(|d| d.as_millis() as u64)
|
||||
.unwrap_or(0)
|
||||
}
|
||||
@@ -63,6 +63,7 @@ mod local_library;
|
||||
mod local_playlist;
|
||||
mod local_library_settings;
|
||||
mod lyrics;
|
||||
mod lyrics_sync;
|
||||
mod media_controls;
|
||||
mod locallibrary_prefs;
|
||||
mod tag_editor;
|
||||
@@ -6410,6 +6411,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let weak = window.as_weak();
|
||||
let handle = tokio_rt.handle().clone();
|
||||
window.global::<LyricsState>().on_panel_opened(move || {
|
||||
// Immediate sync pass for an already-loaded doc, so opening
|
||||
// mid-song lands on the correct line instantly (even paused) —
|
||||
// the duplicate-fetch guard below skips the re-fetch then.
|
||||
lyrics_sync::kick();
|
||||
let runtime = runtime.clone();
|
||||
let weak = weak.clone();
|
||||
handle.spawn(async move {
|
||||
@@ -6422,6 +6427,13 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
});
|
||||
}
|
||||
|
||||
// S4 lyrics sync engine — a UI-thread `slint::Timer` driving
|
||||
// `LyricsState.active-index` / `line-progress` at ~30Hz while the panel
|
||||
// is open + the doc is synced + playback is live (idle gate polling
|
||||
// otherwise). Position: local ms getter, or the published QConnect peer
|
||||
// anchor while controlling a remote renderer (Q7).
|
||||
lyrics_sync::start(app_runtime.clone(), window.as_weak());
|
||||
|
||||
// Album track search — client-side filter, no backend round-trip.
|
||||
{
|
||||
let weak = window.as_weak();
|
||||
|
||||
@@ -3064,6 +3064,14 @@ pub fn start_poll_loop(
|
||||
refresh_sidebar(true);
|
||||
last_peer_track_id = remote.track_id;
|
||||
}
|
||||
// Lyrics follow the peer (Q7): publish the RAW renderer
|
||||
// anchor; the 30Hz sync engine extrapolates between poll
|
||||
// ticks exactly like the position extrapolation below.
|
||||
crate::lyrics_sync::publish_remote_anchor(
|
||||
remote.position_ms,
|
||||
remote.updated_at_ms,
|
||||
remote.playing,
|
||||
);
|
||||
// Duration from the core queue's current track (aligned to the
|
||||
// peer's track by the sink). Zero when unknown — clamp is skipped.
|
||||
let duration_secs = runtime
|
||||
@@ -3137,6 +3145,8 @@ pub fn start_poll_loop(
|
||||
// Not in controller mode (no peer / returned to local): reset the
|
||||
// peer-track edge var so re-entering the peer state refreshes meta.
|
||||
last_peer_track_id = 0;
|
||||
// Lyrics position source back to the local player (Q7 resolver).
|
||||
crate::lyrics_sync::clear_remote_anchor();
|
||||
|
||||
let event = runtime.core().player().get_playback_event();
|
||||
|
||||
|
||||
Reference in new issue
Block a user