perf+feat(slint): immersive Coverflow jukebox pyramid + kill the per-click CPU spike

Owner rebuild: cheap "rocola" of flat scaled cards, and eliminate the CPU spike
on every navigation click.

CPU spike (root cause): each queue navigation re-ran refresh_async, whose
to_item reset EVERY rebuilt row's artwork to Image::default(), discarding the
already-decoded handles for the 6-of-7 on-screen covers; each was then
re-decoded (the disk cache stored only compressed bytes, so even a hit ran a
full image::load + thumbnail). Dozens of full JPEG/PNG decodes per click.
Fix: (A) artwork.rs decoded-pixel cache (DECODED_PIXEL_CACHE keyed by url+size;
fetch_and_decode_ref consults it before any disk read/decode); (B) queue.rs
to_item_reuse + per-list prior-art id-diff carries unchanged decoded handles
across the model rebuild (no blank, no re-decode); load_artwork short-circuits
on a decoded-cache hit. Net: at most the one newly-revealed cover decodes.

Pyramid (CoverflowPanel.slint rebuilt): 7 flat cards (3 history left + center +
3 upcoming right), center declared last (paints on top), step-down scale
(1.00/0.80/0.64/0.50) + per-depth black-overlay attenuation on an inner Rectangle
(0/0.22/0.40/0.55). NO rotateY/skew/perspective, NO reflection, NO far-edge
gradient, NO root transparency. Removed the 500ms x/width/height reflow (it
re-laid-out clipped images every frame); only a 120ms GPU opacity cross-fade on
the dim overlay remains. Center drop-shadow static. 132px player clearance kept.

Correctness fix (review blocker): the coverflow upcoming cards index the
UNFILTERED next-3 (coverflow-upcoming), so routing their click through the
paged/filtered play-upcoming played the wrong track on a paged/searched sidebar.
Added QueueState.play-coverflow-upcoming -> queue.play_coverflow_upcoming, which
plays the queue-wide upcoming index directly via play_upcoming_at. History
already indexes queue-wide via play-history.

cc
This commit is contained in:
vicrodh committed 2026-06-13 11:34:35 -06:00
1 parent 5146acf286
commit 763df2eab5
6 files changed
+442 -178

No files matched your search

+94 -2
View File
@@ -6,7 +6,8 @@
//! cover is applied to its own `AlbumCardItem` row on the Slint event
//! loop, so artwork arriving never resets a list (POC ADR 16 and 18).
use std::sync::{Arc, Mutex};
use std::collections::HashMap;
use std::sync::{Arc, LazyLock, Mutex};
use qbz_cache::ImageCacheService;
use qbz_models::ArtworkRef;
@@ -422,6 +423,69 @@ fn decode_rgba(bytes: &[u8], decode_size: u32) -> Option<(Vec<u8>, u32, u32)> {
Some((rgba.into_raw(), width, height))
}
/// A decoded cover, ready for `pixels_to_image`. `slint::Image` is `!Send`, so
/// the cache stores the RGBA tuple (which IS `Send`) and the event loop builds
/// the `slint::Image` on demand. `Arc`-wrapped so cache hits clone a pointer,
/// not the ~36KB buffer.
pub type DecodedPixels = (Arc<Vec<u8>>, u32, u32);
/// Decoded-pixel LRU. Repeat decodes of the same `(url, size)` — exactly what
/// the coverflow / queue refresh hammered every click — become a HashMap hit +
/// a cheap pixel upload instead of a full `image::load_from_memory().thumbnail()`.
/// Capped to keep a long session from leaking; insertion order approximates LRU
/// (re-insert on hit moves the entry to the back).
const DECODED_CACHE_CAP: usize = 256;
struct DecodedCache {
/// `(url, size)` -> decoded pixels. Insertion order = eviction order.
map: HashMap<(String, u32), DecodedPixels>,
/// Keys in insertion order; the front is the eviction candidate.
order: Vec<(String, u32)>,
}
static DECODED_PIXEL_CACHE: LazyLock<Mutex<DecodedCache>> = LazyLock::new(|| {
Mutex::new(DecodedCache {
map: HashMap::new(),
order: Vec::new(),
})
});
/// Decoded-pixel cache lookup for `(url, size)`. A hit returns the shared RGBA
/// tuple — callers build the `slint::Image` via [`pixels_to_image`] on the event
/// loop and SKIP the expensive decode entirely.
pub fn decoded_pixels(url: &str, size: u32) -> Option<DecodedPixels> {
let mut cache = DECODED_PIXEL_CACHE.lock().ok()?;
let key = (url.to_string(), size);
let hit = cache.map.get(&key).cloned();
if hit.is_some() {
// Move to the back (most-recently-used).
if let Some(pos) = cache.order.iter().position(|k| k == &key) {
cache.order.remove(pos);
}
cache.order.push(key);
}
hit
}
/// Store decoded pixels for `(url, size)`, evicting the oldest entry past the cap.
fn store_decoded(url: &str, size: u32, pixels: &DecodedPixels) {
let Ok(mut cache) = DECODED_PIXEL_CACHE.lock() else {
return;
};
let key = (url.to_string(), size);
if cache.map.insert(key.clone(), pixels.clone()).is_none() {
cache.order.push(key);
} else if let Some(pos) = cache.order.iter().position(|k| k == &key) {
// Refresh recency on an overwrite.
cache.order.remove(pos);
cache.order.push(key);
}
while cache.order.len() > DECODED_CACHE_CAP {
let oldest = cache.order.remove(0);
cache.map.remove(&oldest);
}
}
/// Resolve an [`ArtworkRef`] to raw RGBA8 pixels, downscaled to
/// `decode_size`, regardless of origin. This is the source-aware entry
/// point that fixes local/Plex artwork never reaching the UI: HTTP and Plex
@@ -436,6 +500,30 @@ pub async fn fetch_and_decode_ref(
if art.is_empty() {
return None;
}
// Decoded-pixel cache key: the stable resolved location for this art at this
// decode size. A hit returns the already-decoded RGBA tuple and skips both
// the disk read AND the `image::load_from_memory().thumbnail()` decode — this
// is what makes a one-position queue/coverflow shift near-free (the 6 covers
// still on screen reuse their decoded pixels instead of being re-decoded).
// `Embedded` has no stable URL, so it is never decode-cached.
let cache_key: Option<String> = match art {
ArtworkRef::None | ArtworkRef::Embedded(_) => None,
ArtworkRef::LocalFile(path) => Some(path.clone()),
ArtworkRef::Remote(url) => Some(url.clone()),
ArtworkRef::PlexThumb {
base_url,
token,
path,
size,
} => Some(qbz_models::plex_thumb_url(base_url, token, path, *size)),
};
if let Some(key) = cache_key.as_deref() {
if let Some((pixels, w, h)) = decoded_pixels(key, decode_size) {
return Some(((*pixels).clone(), w, h));
}
}
let bytes: Vec<u8> = match art {
ArtworkRef::None => return None,
ArtworkRef::Embedded(b) => b.clone(),
@@ -457,7 +545,11 @@ pub async fn fetch_and_decode_ref(
fetch_cached_http(&url, cache, false).await?
}
};
decode_rgba(&bytes, decode_size)
let (pixels, w, h) = decode_rgba(&bytes, decode_size)?;
if let Some(key) = cache_key {
store_decoded(&key, decode_size, &(Arc::new(pixels.clone()), w, h));
}
Some((pixels, w, h))
}
/// Resolve one cover image (by remote URL) to raw RGBA8 pixels. Kept for the
+6
View File
@@ -6597,6 +6597,12 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
let c = controller.clone();
qs.on_play_upcoming(move |index| c.play_upcoming(index.max(0) as usize));
}
{
let c = controller.clone();
qs.on_play_coverflow_upcoming(move |index| {
c.play_coverflow_upcoming(index.max(0) as usize)
});
}
{
let c = controller.clone();
qs.on_play_history(move |index| c.play_history(index.max(0) as usize));
+186 -32
View File
@@ -261,6 +261,22 @@ impl QueueController {
let history_rows: Vec<RowData> =
state.history.iter().map(|t| row_from(t, false)).collect();
// --- COVERFLOW (unfiltered next-3 / prev-3) -----------------------
// Built from the UNFILTERED queue so the immersive pyramid is correct
// regardless of sidebar page/search. Index 0 = next / most-recent.
let coverflow_up_rows: Vec<RowData> = state
.upcoming
.iter()
.take(3)
.map(|t| row_from(t, false))
.collect();
let coverflow_hist_rows: Vec<RowData> = state
.history
.iter()
.take(3)
.map(|t| row_from(t, false))
.collect();
// --- Infinite-play flag ------------------------------------------
let infinite = self
.playback
@@ -286,20 +302,49 @@ impl QueueController {
art_jobs.push((ArtTarget::History(idx), row.artwork_url.clone()));
}
}
for (idx, row) in coverflow_up_rows.iter().enumerate() {
if !row.artwork_url.is_empty() {
art_jobs.push((ArtTarget::CoverflowUpcoming(idx), row.artwork_url.clone()));
}
}
for (idx, row) in coverflow_hist_rows.iter().enumerate() {
if !row.artwork_url.is_empty() {
art_jobs.push((ArtTarget::CoverflowHistory(idx), row.artwork_url.clone()));
}
}
let weak = self.weak.clone();
let _ = weak.upgrade_in_event_loop(move |w| {
let qs = w.global::<QueueState>();
// Snapshot prior decoded handles per list BEFORE replacing the
// models, so unchanged tracks keep their decoded artwork instead of
// blanking to the default (which forced a full re-decode + blink on
// every click). Diffed per-list so a track present in both history
// and upcoming can't cross-map.
let prior_page = prior_art_map(&qs.get_upcoming_page());
let prior_history = prior_art_map(&qs.get_history());
let prior_cf_up = prior_art_map(&qs.get_coverflow_upcoming());
let prior_cf_hist = prior_art_map(&qs.get_coverflow_history());
let np_item = now_playing
.as_ref()
.map(|r| to_item(r))
.map(|r| {
// Reuse the prior now-playing cover only if the same track.
let prior = qs.get_now_playing();
let mut map = std::collections::HashMap::new();
if prior.artwork.size().width > 0 {
map.insert(prior.id.clone(), prior.artwork.clone());
}
to_item_reuse(r, &map)
})
.unwrap_or_default();
qs.set_has_current(now_playing.is_some());
qs.set_now_playing(np_item);
qs.set_now_playing_favorite(now_playing_favorite);
let page_items: Vec<QueueItem> = page_rows.iter().map(to_item).collect();
let page_items: Vec<QueueItem> =
page_rows.iter().map(|r| to_item_reuse(r, &prior_page)).collect();
qs.set_upcoming_page(slint::ModelRc::new(slint::VecModel::from(page_items)));
qs.set_upcoming_total(upcoming_total as i32);
qs.set_upcoming_remaining(remaining as i32);
@@ -308,9 +353,22 @@ impl QueueController {
qs.set_page_start(page_start as i32);
qs.set_page_end(page_end as i32);
let history_items: Vec<QueueItem> = history_rows.iter().map(to_item).collect();
let history_items: Vec<QueueItem> =
history_rows.iter().map(|r| to_item_reuse(r, &prior_history)).collect();
qs.set_history(slint::ModelRc::new(slint::VecModel::from(history_items)));
// Coverflow lists (unfiltered next-3 / prev-3), reusing handles.
let cf_up_items: Vec<QueueItem> = coverflow_up_rows
.iter()
.map(|r| to_item_reuse(r, &prior_cf_up))
.collect();
qs.set_coverflow_upcoming(slint::ModelRc::new(slint::VecModel::from(cf_up_items)));
let cf_hist_items: Vec<QueueItem> = coverflow_hist_rows
.iter()
.map(|r| to_item_reuse(r, &prior_cf_hist))
.collect();
qs.set_coverflow_history(slint::ModelRc::new(slint::VecModel::from(cf_hist_items)));
qs.set_infinite_play(infinite);
// Keep the Slint tab property in sync with the view state so the
// Queue/History body always matches the selected tab.
@@ -350,6 +408,25 @@ impl QueueController {
});
}
/// Play an upcoming track by its QUEUE-WIDE (unfiltered) index. The immersive
/// coverflow lists `state.upcoming.take(3)` regardless of the sidebar's page
/// or search, so its cards must NOT go through `play_upcoming`'s page-local
/// `resolve_upcoming_index` (that would play the wrong track when the sidebar
/// is paged/filtered). History is already queue-wide via `play_history`.
pub fn play_coverflow_upcoming(&self, upcoming_index: usize) {
let this = self.clone();
self.handle.spawn(async move {
let Some(track) = this.runtime.core().play_upcoming_at(upcoming_index).await else {
log::warn!(
"[qbz-slint] queue: play_coverflow_upcoming {upcoming_index} miss"
);
return;
};
crate::playback::after_track_change(&this.runtime, &this.weak, track.id).await;
this.refresh_async().await;
});
}
/// Remove the upcoming entry at `page_index` within the current page.
pub fn remove_upcoming(&self, page_index: usize) {
let this = self.clone();
@@ -633,16 +710,30 @@ enum ArtTarget {
NowPlaying,
Upcoming(usize),
History(usize),
CoverflowUpcoming(usize),
CoverflowHistory(usize),
}
/// Build a `QueueItem` from plain row data (no artwork — that resolves
/// asynchronously and is set onto the row afterward).
fn to_item(row: &RowData) -> QueueItem {
/// Build a `QueueItem` from plain row data, REUSING a prior decoded artwork
/// handle when the same track id was already on screen. This is the core of the
/// CPU-spike fix: a one-position queue shift keeps the decoded `slint::Image`
/// for every unchanged row instead of resetting it to `Image::default()` and
/// forcing a full re-decode (which also caused the empty-then-fill blink).
///
/// `prior` maps track id -> the decoded image from the model being replaced.
/// Unchanged rows reuse their handle; only genuinely-new rows fall back to the
/// default placeholder (their cover is decoded once by the artwork pipeline).
fn to_item_reuse(
row: &RowData,
prior: &std::collections::HashMap<slint::SharedString, slint::Image>,
) -> QueueItem {
let id: slint::SharedString = row.id.clone().into();
let artwork = prior.get(&id).cloned().unwrap_or_default();
QueueItem {
id: row.id.clone().into(),
id: id.clone(),
title: row.title.clone().into(),
artist: row.artist.clone().into(),
artwork: slint::Image::default(),
artwork,
playing: row.playing,
duration: row.duration.clone().into(),
explicit: row.explicit,
@@ -650,6 +741,23 @@ fn to_item(row: &RowData) -> QueueItem {
}
}
/// Snapshot the current id -> decoded-artwork map for a Slint model, so the
/// rebuilt rows can reuse handles for tracks that did not change. Only rows
/// whose artwork is actually resolved (`width > 0`) are recorded.
fn prior_art_map(
model: &slint::ModelRc<QueueItem>,
) -> std::collections::HashMap<slint::SharedString, slint::Image> {
let mut map = std::collections::HashMap::new();
for i in 0..model.row_count() {
if let Some(item) = model.row_data(i) {
if item.artwork.size().width > 0 {
map.insert(item.id.clone(), item.artwork.clone());
}
}
}
map
}
#[cfg(test)]
mod tests {
use super::*;
@@ -759,6 +867,9 @@ fn load_artwork(
plex_base_url: String,
plex_token: String,
) {
/// Decode size for all queue/coverflow covers (matches the artwork pipeline).
const QUEUE_DECODE: u32 = 96;
let Some(cache) = crate::artwork::shared_cache() else {
return;
};
@@ -783,42 +894,85 @@ fn load_artwork(
path: url,
// Queue rows + now-playing item render small; request a
// 96px server-side transcode (the decode size used below).
size: Some(96),
size: Some(QUEUE_DECODE),
}
} else {
qbz_models::ArtworkRef::LocalFile(url)
};
// Decoded-pixel fast path: if this exact cover was already decoded at
// this size (true for the covers still on screen after a one-position
// shift), upload the cached pixels on the event loop and SKIP the tokio
// decode entirely. This is the bulk of the per-click CPU-spike fix.
let cache_key = match &art {
qbz_models::ArtworkRef::Remote(u) => Some(u.clone()),
qbz_models::ArtworkRef::LocalFile(p) => Some(p.clone()),
qbz_models::ArtworkRef::PlexThumb { base_url, token, path, size } => {
Some(qbz_models::plex_thumb_url(base_url, token, path, *size))
}
_ => None,
};
if let Some(key) = cache_key.as_deref() {
if let Some((pixels, w, h)) = crate::artwork::decoded_pixels(key, QUEUE_DECODE) {
let weak = weak.clone();
let _ = weak.upgrade_in_event_loop(move |win| {
let img = crate::artwork::pixels_to_image(&pixels, w, h);
apply_queue_art(&win, target, img);
});
continue;
}
}
tokio::spawn(async move {
let Some((pixels, w, h)) =
crate::artwork::fetch_and_decode_ref(&art, &cache, 96).await
crate::artwork::fetch_and_decode_ref(&art, &cache, QUEUE_DECODE).await
else {
return;
};
let _ = weak.upgrade_in_event_loop(move |win| {
let img = crate::artwork::pixels_to_image(&pixels, w, h);
let qs = win.global::<QueueState>();
match target {
ArtTarget::NowPlaying => {
let mut item = qs.get_now_playing();
item.artwork = img;
qs.set_now_playing(item);
}
ArtTarget::Upcoming(idx) => {
let items = qs.get_upcoming_page();
if let Some(mut item) = items.row_data(idx) {
item.artwork = img;
items.set_row_data(idx, item);
}
}
ArtTarget::History(idx) => {
let items = qs.get_history();
if let Some(mut item) = items.row_data(idx) {
item.artwork = img;
items.set_row_data(idx, item);
}
}
}
apply_queue_art(&win, target, img);
});
});
}
}
/// Apply a resolved cover onto its queue/coverflow row. Runs on the event loop.
fn apply_queue_art(win: &AppWindow, target: ArtTarget, img: slint::Image) {
let qs = win.global::<QueueState>();
match target {
ArtTarget::NowPlaying => {
let mut item = qs.get_now_playing();
item.artwork = img;
qs.set_now_playing(item);
}
ArtTarget::Upcoming(idx) => {
let items = qs.get_upcoming_page();
if let Some(mut item) = items.row_data(idx) {
item.artwork = img;
items.set_row_data(idx, item);
}
}
ArtTarget::History(idx) => {
let items = qs.get_history();
if let Some(mut item) = items.row_data(idx) {
item.artwork = img;
items.set_row_data(idx, item);
}
}
ArtTarget::CoverflowUpcoming(idx) => {
let items = qs.get_coverflow_upcoming();
if let Some(mut item) = items.row_data(idx) {
item.artwork = img;
items.set_row_data(idx, item);
}
}
ArtTarget::CoverflowHistory(idx) => {
let items = qs.get_coverflow_history();
if let Some(mut item) = items.row_data(idx) {
item.artwork = img;
items.set_row_data(idx, item);
}
}
}
}