refactor(qconnect): hoist renderer orchestration behind engine trait (slice 6)

Step 6 of the renderer-engine extraction. Moves the renderer orchestration
out of the Tauri adapter UP into frontend-agnostic qconnect-app, rewritten
against &impl QconnectRendererEngine instead of &CoreBridge, so the Slint
adapter reuses the hard-won echo/cursor/materialize/shuffle logic instead of
re-deriving it.

Moved into qconnect_app::renderer (byte-for-byte, bridge -> engine):
apply_renderer_command (incl. the #387 echo-seek gate, the stale-projected-
track guard, force-restart-removed reasoning), materialize_remote_queue (skip-
gate, dedupe+batch hydrate, 3-tier start-index, shuffle deferral
effective_shuffle_enabled = shuffle_mode && order.is_some(), cursor-align +
stale-local-stop), sync_remote_shuffle_projection, align_queue_cursor,
apply_remote_loop_mode, ensure_remote_track_loaded (+ should_reload /
is_recent / queue_state_needs_materialization, LOAD_ATTEMPT_DEDUP_WINDOW,
PLAYING_STATE_* consts). The sync_state lock-drop-across-await discipline is
preserved; last_load_attempt is still recorded before the load.

Stays adapter-side: corebridge.rs is now thin wrappers that unwrap the
Arc<RwLock<Option<CoreBridge>>> guard and delegate (event_sink/service call
sites unchanged). In operation the bridge is populated at startup before any
QConnect session opens, so the guard-before-skip reorder is unreachable;
behavior is byte-identical. ensure_remote_track_loaded now resolves duration
via get_track then calls engine.start_track_stream (which owns get_stream_url +
the protected feeder); the two independent catalog reads swap order, benign.
mod.rs re-exports PLAYING_STATE_* from qconnect-app.

Verified: cargo check -p qbz-nix clean (no warnings); qbz-nix qconnect 42/42 +
qconnect-app 38/38 green; Opus adversarial review CLEAN across byte-identity,
guard-reorder, lock-discipline, ensure-reorder, Send/generics, re-exports.

cc
This commit is contained in:
vicrodh committed 2026-06-02 18:59:34 -06:00
1 parent e8ac6185b6
commit b21d45c2f6
4 files changed
+699 -654

No files matched your search

+652
View File
@@ -7,7 +7,33 @@
//! audio-quality report helpers move here alongside their orchestration /
//! report consumers in the later slice-6 steps.
use std::collections::HashMap;
use std::sync::Arc;
use std::time::{Duration, Instant};
use qbz_models::{QueueTrack, RepeatMode, Track};
use qbz_player::PlaybackState;
use tokio::sync::Mutex;
use crate::queue_resolution::{
dedupe_track_ids, resolve_core_shuffle_order, resolve_remote_start_index,
};
use crate::renderer_engine::QconnectRendererEngine;
use crate::session::quality_from_max_audio_quality;
use crate::{QConnectQueueState, QConnectRendererState, QconnectRemoteSyncState, RendererCommand};
/// QConnect protocol `playing_state` wire values. Single source of truth for the
/// renderer orchestration; the Tauri adapter re-exports these from here.
pub const PLAYING_STATE_UNKNOWN: i32 = 0;
pub const PLAYING_STATE_STOPPED: i32 = 1;
pub const PLAYING_STATE_PLAYING: i32 = 2;
pub const PLAYING_STATE_PAUSED: i32 = 3;
/// Dedup window: an echoed SetState for a track whose load was registered within
/// this window does not re-trigger the load. The audio thread updates
/// `playback_state.track_id` only after the engine appends the source, so a bare
/// `track_id` comparison would re-fire during that buffer/decode gap.
const LOAD_ATTEMPT_DEDUP_WINDOW: Duration = Duration::from_secs(5);
/// Source tag stamped on remote queue tracks materialized from a QConnect cloud
/// queue. Matches the Tauri adapter's prior `QCONNECT_REMOTE_QUEUE_SOURCE`.
@@ -72,3 +98,629 @@ pub fn model_track_to_core_queue_track(track: &Track) -> QueueTrack {
source_item_id_hint: album_id,
}
}
// ===================== Renderer orchestration (slice 6, step 6) =====================
//
// Engine-agnostic: written ONLY against `QconnectRendererEngine` + the shared
// `QconnectRemoteSyncState`. The Tauri/Slint adapters obtain a concrete engine
// (`&CoreBridge` / `&SlintEngine`) — including any "not initialized yet" guard —
// and dispatch here, so the hard-won echo/cursor/materialize/shuffle logic is
// never re-derived per frontend. Ported byte-for-byte from the prior Tauri
// `corebridge.rs` / `track_loading.rs`; only `bridge` -> `engine` and the
// guard-unwrap (which stays adapter-side) changed.
pub fn queue_state_needs_materialization(
previous: Option<&QConnectQueueState>,
next: &QConnectQueueState,
) -> bool {
let Some(previous) = previous else {
return true;
};
previous.version != next.version
|| previous.queue_items != next.queue_items
|| previous.shuffle_mode != next.shuffle_mode
|| previous.shuffle_order != next.shuffle_order
|| previous.autoplay_mode != next.autoplay_mode
|| previous.autoplay_loading != next.autoplay_loading
|| previous.autoplay_items != next.autoplay_items
}
pub fn should_reload_remote_track(playback_state: &PlaybackState, track_id: u64) -> bool {
// Only reload when the track ID actually changed. The previous
// !has_loaded_audio gate fired during the buffering window of an
// initial load (qbz already started fetching but the audio engine
// hasn't reported the track as loaded yet) — when the cloud echo
// SetState arrived for the same track, this caused a redundant
// load that interrupted the in-progress one. That was the residual
// first-track hiccup.
playback_state.track_id != track_id
}
/// Returns true if a load attempt for `track_id` was registered within the
/// dedup window (see `LOAD_ATTEMPT_DEDUP_WINDOW`).
fn is_recent_load_attempt(state: &QconnectRemoteSyncState, track_id: u64) -> bool {
match state.last_load_attempt {
Some((tid, ts)) => tid == track_id && ts.elapsed() < LOAD_ATTEMPT_DEDUP_WINDOW,
None => false,
}
}
/// Load a remote track into the engine, deduped against echoed SetState frames.
/// Records the attempt BEFORE dispatching the load (the audio thread updates
/// `playback_state.track_id` only after the engine appends the source, so the
/// recording must precede the load to close the echo window).
pub async fn ensure_remote_track_loaded(
engine: &impl QconnectRendererEngine,
sync_state: &Arc<Mutex<QconnectRemoteSyncState>>,
track_id: u64,
max_audio_quality: Option<i32>,
) -> Result<(), String> {
{
let state = sync_state.lock().await;
if is_recent_load_attempt(&state, track_id) {
return Ok(());
}
}
let playback_state = engine.get_playback_state();
if !should_reload_remote_track(&playback_state, track_id) {
return Ok(());
}
{
let mut state = sync_state.lock().await;
state.last_load_attempt = Some((track_id, Instant::now()));
}
let quality = quality_from_max_audio_quality(max_audio_quality);
let duration_secs = engine
.get_track(track_id)
.await
.map(|track| u64::from(track.duration))
.unwrap_or(0);
// QConnect tracks always start from 0; resume is local-only. The protected
// bit-perfect seams + the HTTP feeder live behind `start_track_stream`.
engine
.start_track_stream(track_id, quality, duration_secs, 0)
.await
}
pub async fn apply_remote_loop_mode(
engine: &impl QconnectRendererEngine,
loop_mode: i32,
) -> Result<(), String> {
let repeat_mode = qconnect_repeat_mode_from_loop_mode(loop_mode)
.ok_or_else(|| format!("unsupported qconnect loop mode: {loop_mode}"))?;
engine.set_repeat_mode(repeat_mode).await;
Ok(())
}
pub async fn apply_renderer_command(
engine: &impl QconnectRendererEngine,
sync_state: &Arc<Mutex<QconnectRemoteSyncState>>,
command: &RendererCommand,
renderer_state: &QConnectRendererState,
) -> Result<(), String> {
match command {
RendererCommand::SetState {
playing_state,
current_position_ms,
current_track,
next_track,
..
} => {
let resolved_playing_state = renderer_state.playing_state.or(*playing_state);
let mut projection_renderer_state = renderer_state.clone();
if projection_renderer_state.current_track.is_none() {
projection_renderer_state.current_track = current_track.clone();
}
if projection_renderer_state.next_track.is_none() {
projection_renderer_state.next_track = next_track.clone();
}
let resolved_current_track = projection_renderer_state.current_track.as_ref();
if let Some(projected_track) = resolved_current_track {
let queue_state = {
let state = sync_state.lock().await;
state.last_remote_queue_state.clone()
};
let projection_applied = if let Some(queue_state) = queue_state.as_ref() {
sync_remote_shuffle_projection(
engine,
sync_state,
queue_state,
&projection_renderer_state,
)
.await?
} else {
false
};
// Track-manipulation operations (cursor align, force-restart,
// ensure_remote_track_loaded) only run when the COMMAND
// explicitly specifies a current_track. The projection's
// resolved_current_track can be stale: when the cloud sends
// a state-only update (pause/resume) with command.current_track=null,
// the projection falls back to renderer_state.current_track,
// which is the cloud's last-known view of qbz's playback —
// potentially behind qbz's actual local advance. Using that
// stale value to align/load causes spurious track switches
// (e.g., pause from iOS made qbz jump back to a previous
// track). The outer renderer_state-based projection is still
// used for shuffle sync above and downstream playing_state /
// seek operations, which remain safe because they don't
// change the queue cursor or load tracks.
let _ = projected_track; // retained for shuffle projection above
if let Some(command_track) = current_track.as_ref() {
if !projection_applied {
if let Err(err) =
align_queue_cursor(engine, command_track.track_id).await
{
log::warn!(
"[QConnect] Failed to align CoreBridge queue cursor: {err}"
);
}
}
if matches!(
resolved_playing_state,
Some(PLAYING_STATE_PLAYING | PLAYING_STATE_PAUSED)
) {
// Force-restart removed: the cloud routinely re-emits
// SetState with current_position_ms=0 for the same
// track when only secondary fields change (e.g.,
// next_track corrections, queue_item_id refreshes).
// Reloading the stream on every echo caused first-
// track hiccup on album change and "needs several
// taps" on prev/next. Track-change cases are handled
// by align_queue_cursor + ensure_remote_track_loaded
// below; legitimate seek-to-start from a peer
// controller can use the seek path with target>1s.
if let Err(err) = ensure_remote_track_loaded(
engine,
sync_state,
command_track.track_id,
projection_renderer_state.max_audio_quality,
)
.await
{
log::warn!(
"[QConnect] Failed to load remote track {}: {err}",
command_track.track_id
);
}
}
}
}
if let Some(value) = resolved_playing_state {
match value {
PLAYING_STATE_PLAYING => {
engine.resume()?;
}
PLAYING_STATE_PAUSED => {
engine.pause()?;
}
PLAYING_STATE_STOPPED => {
engine.stop()?;
}
PLAYING_STATE_UNKNOWN => {}
_ => {
log::debug!("[QConnect] Unknown playing state received: {value}");
}
}
}
if let Some(position_ms) =
renderer_state.current_position_ms.or(*current_position_ms)
{
let playback_state = engine.get_playback_state();
let current_pos_secs = playback_state.position;
let target_secs = position_ms / 1000;
// Reject echo seeks: when the command targets the same track
// qbz is already playing AND target<=1s while local is well
// ahead, this is the cloud re-emitting a stale SetState
// (frequently fires on next_track corrections and queue_
// item_id refreshes). A real peer "go to start" intent
// would target the same track as the local one but the
// round-trip to qbz is already a few seconds, making this
// case indistinguishable from echo — favor stability.
let is_echo_reset = current_track
.as_ref()
.map(|cmd_track| cmd_track.track_id == playback_state.track_id)
.unwrap_or(false)
&& target_secs <= 1
&& current_pos_secs > 2;
// Issue #387: honor seeks regardless of which device is the
// active renderer. The previous gate (`peer_renderer_active`)
// skipped seeks entirely when local was the active renderer,
// breaking the case where a peer controller (e.g. official
// Qobuz mobile app) sends a real seek to qbz acting as the
// renderer — the audio thread never moved while the cloud
// state advanced, so the controller's progress bar locked.
// The is_echo_reset + abs_diff > 2 gates already filter the
// cloud-echo case the peer_renderer_active check was added
// to defend against in commit 147bcbd7. If hiccups return,
// revert this change and reintroduce a more targeted echo
// detector (UUID-based) instead of the all-or-nothing gate.
if !is_echo_reset && current_pos_secs.abs_diff(target_secs) > 2 {
log::info!(
"[QConnect] SetState seek: current={}s target={}s",
current_pos_secs,
target_secs
);
engine.seek(target_secs)?;
}
}
}
RendererCommand::SetVolume { volume, .. } => {
if let Some(resolved) = renderer_state.volume.or(*volume) {
engine.set_volume(normalize_volume_to_fraction(resolved))?;
}
}
RendererCommand::MuteVolume { value } => {
if *value {
engine.set_volume(0.0)?;
} else if let Some(resolved) = renderer_state.volume {
engine.set_volume(normalize_volume_to_fraction(resolved))?;
}
}
RendererCommand::SetLoopMode { loop_mode } => {
let resolved_loop_mode = renderer_state.loop_mode.unwrap_or(*loop_mode);
let repeat_mode = qconnect_repeat_mode_from_loop_mode(resolved_loop_mode)
.ok_or_else(|| format!("unsupported qconnect loop mode: {resolved_loop_mode}"))?;
engine.set_repeat_mode(repeat_mode).await;
}
RendererCommand::SetActive { active } => {
if *active {
// Becoming the active renderer: preload the current track so
// playback can start immediately on the next SetState.
if let Some(current) = renderer_state.current_track.as_ref() {
if let Err(err) = ensure_remote_track_loaded(
engine,
sync_state,
current.track_id,
renderer_state.max_audio_quality,
)
.await
{
log::warn!("[QConnect] SetActive(true) preload failed: {err}");
}
}
} else {
engine.stop()?;
}
}
RendererCommand::SetMaxAudioQuality { max_audio_quality } => {
// Applied on the next load via renderer_state.max_audio_quality
// (recorded by the core reducer). No immediate re-fetch.
log::info!("[QConnect] SetMaxAudioQuality => {max_audio_quality}");
}
RendererCommand::SetShuffleMode { shuffle_mode } => {
let enabled = renderer_state.shuffle_mode.unwrap_or(*shuffle_mode);
engine.set_shuffle(enabled).await;
}
}
Ok(())
}
async fn sync_remote_shuffle_projection(
engine: &impl QconnectRendererEngine,
sync_state: &Arc<Mutex<QconnectRemoteSyncState>>,
queue_state: &QConnectQueueState,
renderer_state: &QConnectRendererState,
) -> Result<bool, String> {
if !queue_state.shuffle_mode || queue_state.queue_items.is_empty() {
return Ok(false);
}
let start_index = resolve_remote_start_index(
queue_state,
renderer_state
.current_track
.as_ref()
.map(|item| item.queue_item_id),
renderer_state
.current_track
.as_ref()
.map(|item| item.track_id),
);
let Some(start_index) = start_index else {
return Ok(false);
};
let core_shuffle_order = resolve_core_shuffle_order(
queue_state,
renderer_state
.current_track
.as_ref()
.map(|item| item.queue_item_id),
renderer_state
.current_track
.as_ref()
.map(|item| item.track_id),
renderer_state
.next_track
.as_ref()
.map(|item| item.queue_item_id),
renderer_state.next_track.as_ref().map(|item| item.track_id),
);
// Same deferral rule as materialize_remote_queue: do not invent an
// identity shuffle when the cloud hasn't yet sent the authoritative
// shuffle_order. Wait for the second QueueUpdated.
if core_shuffle_order.is_none() {
return Ok(false);
}
let should_apply = {
let state = sync_state.lock().await;
state.last_materialized_start_index != Some(start_index)
|| state.last_materialized_core_shuffle_order != core_shuffle_order
};
if !should_apply {
return Ok(false);
}
let (tracks, _) = engine.get_all_queue_tracks().await;
if tracks.len() != queue_state.queue_items.len() || tracks.is_empty() {
return Ok(false);
}
engine
.set_queue_with_order(
tracks,
Some(start_index),
queue_state.shuffle_mode,
core_shuffle_order.clone(),
)
.await;
let mut state = sync_state.lock().await;
state.last_materialized_start_index = Some(start_index);
state.last_materialized_core_shuffle_order = core_shuffle_order;
Ok(true)
}
pub async fn materialize_remote_queue(
engine: &impl QconnectRendererEngine,
sync_state: &Arc<Mutex<QconnectRemoteSyncState>>,
queue_state: &QConnectQueueState,
) -> Result<(), String> {
let (
renderer_queue_item_id,
renderer_track_id,
renderer_next_queue_item_id,
renderer_next_track_id,
renderer_playing_state,
should_skip,
) = {
let mut state = sync_state.lock().await;
if !queue_state_needs_materialization(state.last_applied_queue_state.as_ref(), queue_state)
{
(
state.last_renderer_queue_item_id,
state.last_renderer_track_id,
state.last_renderer_next_queue_item_id,
state.last_renderer_next_track_id,
state.last_renderer_playing_state,
true,
)
} else {
state.last_applied_queue_state = Some(queue_state.clone());
(
state.last_renderer_queue_item_id,
state.last_renderer_track_id,
state.last_renderer_next_queue_item_id,
state.last_renderer_next_track_id,
state.last_renderer_playing_state,
false,
)
}
};
if should_skip {
log::debug!(
"[QConnect] materialize_remote_queue: skipped (identical snapshot {}.{})",
queue_state.version.major,
queue_state.version.minor
);
return Ok(());
}
log::info!(
"[QConnect] materialize_remote_queue: version={}.{} items={} renderer_qid={:?} renderer_tid={:?} renderer_next_qid={:?} renderer_next_tid={:?} playing_state={:?}",
queue_state.version.major,
queue_state.version.minor,
queue_state.queue_items.len(),
renderer_queue_item_id,
renderer_track_id,
renderer_next_queue_item_id,
renderer_next_track_id,
renderer_playing_state
);
if queue_state.queue_items.is_empty() {
// Preserve legacy behavior: keep current track on qconnect sync clears.
engine.clear_queue(true).await;
engine.set_shuffle(false).await;
let mut state = sync_state.lock().await;
state.last_materialized_start_index = None;
state.last_materialized_core_shuffle_order = None;
return Ok(());
}
let unique_track_ids = dedupe_track_ids(queue_state);
let fetched_tracks = engine
.get_tracks_batch(&unique_track_ids)
.await
.map_err(|err| format!("fetch tracks batch for remote queue: {err}"))?;
let mut tracks_by_id = HashMap::with_capacity(fetched_tracks.len());
for track in fetched_tracks {
tracks_by_id.insert(track.id, model_track_to_core_queue_track(&track));
}
let mut queue_tracks = Vec::with_capacity(queue_state.queue_items.len());
for item in &queue_state.queue_items {
if let Some(queue_track) = tracks_by_id.get(&item.track_id) {
queue_tracks.push(queue_track.clone());
continue;
}
match engine.get_track(item.track_id).await {
Ok(track) => {
let mapped = model_track_to_core_queue_track(&track);
tracks_by_id.insert(item.track_id, mapped.clone());
queue_tracks.push(mapped);
}
Err(err) => {
log::warn!(
"[QConnect] Unable to hydrate remote queue track {}: {}",
item.track_id,
err
);
}
}
}
if queue_tracks.is_empty() {
return Err("remote queue materialization produced zero playable tracks".to_string());
}
// Resolve start index from remote state first, then from the local playback
// cursor only if that track is still part of the remote queue.
let current_playback_track_id = match engine.get_playback_state().track_id {
0 => None,
track_id => Some(track_id),
};
let mut start_index =
resolve_remote_start_index(queue_state, renderer_queue_item_id, renderer_track_id);
if start_index.is_none() {
start_index = resolve_remote_start_index(
queue_state,
renderer_next_queue_item_id,
renderer_next_track_id,
)
.map(|index| index.saturating_sub(1));
}
if start_index.is_none() {
start_index = current_playback_track_id.and_then(|track_id| {
queue_state
.queue_items
.iter()
.position(|item| item.track_id == track_id)
});
}
if start_index.is_none() && !queue_tracks.is_empty() {
start_index = Some(0);
}
let core_shuffle_order = resolve_core_shuffle_order(
queue_state,
renderer_queue_item_id,
renderer_track_id,
renderer_next_queue_item_id,
renderer_next_track_id,
);
// The cloud sends two QueueUpdated events during a shuffle toggle:
// first with shuffle_mode=true and shuffle_order=null (the flag
// broadcasts immediately), then ~400ms later with the computed
// shuffle_order. If we mark shuffle_enabled=true on the first event
// with an absent order, set_queue_with_order falls into its identity
// path (0,1,2,...) — that is qbz inventing a sequence that diverges
// from the order the cloud is about to authorize. Defer the engine
// shuffle activation until the authoritative order is present.
let effective_shuffle_enabled = queue_state.shuffle_mode && core_shuffle_order.is_some();
log::info!(
"[QConnect] materialize_remote_queue: setting queue with {} tracks, start_index={:?}, local_track_id={:?}, remote_shuffle_mode={}, shuffle_order_present={}, engine_shuffle_enabled={}",
queue_tracks.len(),
start_index,
current_playback_track_id,
queue_state.shuffle_mode,
core_shuffle_order.is_some(),
effective_shuffle_enabled,
);
engine
.set_queue_with_order(
queue_tracks,
start_index,
effective_shuffle_enabled,
core_shuffle_order.clone(),
)
.await;
{
let mut state = sync_state.lock().await;
state.last_materialized_start_index = start_index;
state.last_materialized_core_shuffle_order = core_shuffle_order;
}
let local_track_missing_from_remote = current_playback_track_id
.map(|track_id| {
!queue_state
.queue_items
.iter()
.any(|item| item.track_id == track_id)
})
.unwrap_or(true);
if let Some(index) = start_index {
if local_track_missing_from_remote {
log::info!(
"[QConnect] materialize_remote_queue: aligning queue cursor to remote index {}",
index
);
let _ = engine.play_index(index).await;
}
}
if current_playback_track_id.is_some()
&& current_playback_track_id != renderer_track_id
&& local_track_missing_from_remote
&& matches!(
renderer_playing_state,
Some(PLAYING_STATE_STOPPED | PLAYING_STATE_UNKNOWN)
)
{
log::info!(
"[QConnect] materialize_remote_queue: stopping stale local playback track {:?} after remote queue replacement",
current_playback_track_id
);
let _ = engine.stop();
}
Ok(())
}
pub async fn align_queue_cursor(
engine: &impl QconnectRendererEngine,
track_id: u64,
) -> Result<(), String> {
let (tracks, current_index) = engine.get_all_queue_tracks().await;
log::info!(
"[QConnect] align_queue_cursor: track_id={track_id} queue_len={} current_index={:?}",
tracks.len(),
current_index
);
if let Some(target_index) = tracks.iter().position(|track| track.id == track_id) {
if current_index != Some(target_index) {
log::info!(
"[QConnect] align_queue_cursor: moving cursor from {:?} to {target_index}",
current_index
);
let _ = engine.play_index(target_index).await;
}
return Ok(());
}
log::info!(
"[QConnect] align_queue_cursor: track {track_id} not in queue, fetching and creating single-track queue"
);
let track = engine
.get_track(track_id)
.await
.map_err(|err| format!("fetch current remote track {track_id}: {err}"))?;
let queue_track = model_track_to_core_queue_track(&track);
engine.set_queue(vec![queue_track], Some(0)).await;
Ok(())
}