Files
qbz/crates/qconnect-app/src/renderer_engine.rs
T
vicrodh 1f1d7303ef fix(qconnect): badge clear, multi-track enqueue, shuffle WS-authoritative, cursor/history/pause
- badge: gate is-remote on transport_connected so it clears on every session-end
  path (transport drop / watchdog / reconnect-exhausted), not only toggle-off
- multi-track: route a whole album/playlist/favorites enqueue to the peer in one
  QueueAddTracks/QueueInsertTracks (all-or-nothing admission), not single-track only
- shuffle inbound: SetShuffleMode renderer arm is flag-only (set_shuffle_flag) so the
  renderer never invents a local order; the cloud's echoed order is authoritative
- shuffle outbound: send shuffle_seed + shuffle_pivot_queue_item_id (the cloud needs
  the seed to build the order); hoist resolve_qconnect_shuffle_pivot to qconnect-app
- start index: resolve_remote_start_index validates the track_id before trusting a
  qid, so a freshly-pushed album no longer inherits a stale cursor (wrong NowPlayingBar track)
- history: play_index records history only when actually moving, so the current track
  is no longer duplicated in the History tab
- pause-to-peer: resolve current_queue_item from the core-aligned cursor instead of the
  stale renderer snapshot, so pausing an iOS renderer (reports null qid) is accepted

cc
2026-06-04 21:59:58 -06:00

107 lines
5.7 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! Engine seam for QConnect renderer-side playback (slice 6).
//!
//! The hard-won renderer orchestration (echo-seek rejection, cursor align,
//! queue materialize, shuffle deferral, load dedup window) lives ABOVE this
//! trait in `qconnect-app` and is written ONLY against these methods plus
//! `QconnectRemoteSyncState`. It must never be re-derived per frontend.
//!
//! Implemented by:
//! - src-tauri: `CoreBridge` (forwards to `QbzCore` + `Player`)
//! - qbz-slint: a thin adapter over `runtime.core()` (`QbzCore` + `Player`)
//!
//! Errors are `String` (CoreBridge already returns `String`; the Slint impl maps
//! `CoreError::to_string()`). The two protected bit-perfect audio seams
//! (`play_data` / `play_streaming_dynamic`) are reached ONLY through
//! [`QconnectRendererEngine::start_track_stream`]; they are never modified, only
//! called, and the probe-derived sample_rate/channels/bit_depth must pass
//! straight through (defaulting them silently resamples hi-res).
use async_trait::async_trait;
use qbz_models::{Quality, QueueTrack, RepeatMode, Track};
use qbz_player::PlaybackState;
/// The renderer-side engine surface. Both frontends implement it with zero-cost
/// one-line forwards to their `QbzCore` / `Player`; the async/sync split mirrors
/// `QbzCore`/`CoreBridge` verbatim (queue/catalog are async; raw transport is
/// sync). Keep this MINIMAL — exactly these methods. A unified controller engine
/// is a separate trait; do not pollute this one.
#[async_trait]
pub trait QconnectRendererEngine: Send + Sync {
// ---- transport (sync on the engine) ----
fn resume(&self) -> Result<(), String>;
fn pause(&self) -> Result<(), String>;
fn stop(&self) -> Result<(), String>;
/// Seek in WHOLE SECONDS (matches `QbzCore::seek` / `CoreBridge::seek`).
fn seek(&self, position_secs: u64) -> Result<(), String>;
/// Volume as a 0.0–1.0 fraction (caller normalizes via `normalize_volume_to_fraction`).
fn set_volume(&self, fraction: f32) -> Result<(), String>;
/// Fresh, synchronous snapshot of the audio thread (track_id/position/...).
/// MUST NOT be cached/stale — the echo filter and the #387 seek-diff gate
/// depend on its freshness.
fn get_playback_state(&self) -> PlaybackState;
/// Whether the audio thread currently holds decodable audio for the loaded
/// track. Distinct from `get_playback_state().track_id`: `stop()` clears the
/// audio buffer + flips this false but LEAVES `current_track_id` untouched,
/// so after a controller->renderer handoff (which stopped local playback) the
/// track id can still match the target while NO audio is buffered. The
/// takeback force-stream reads this to know a reload is required even when the
/// track id matches (`should_reload_remote_track` alone would skip it and the
/// following resume would fail with "no audio data available").
fn has_loaded_audio(&self) -> bool;
// ---- queue / mode (async) ----
async fn set_repeat_mode(&self, mode: RepeatMode);
async fn set_shuffle(&self, enabled: bool);
/// Set the shuffle FLAG only, WITHOUT generating any local order. QConnect is
/// WS-authoritative for shuffle: the renderer must never invent a random
/// order; the cloud's authoritative order is applied separately via
/// `set_queue_with_order` (`sync_remote_shuffle_projection` /
/// `materialize_remote_queue`). Forwards to
/// `QbzCore::set_shuffle_with_order(enabled, None)` -> identity order on
/// enable (current order preserved, NO RNG), clear on disable.
async fn set_shuffle_flag(&self, enabled: bool);
async fn get_all_queue_tracks(&self) -> (Vec<QueueTrack>, Option<usize>);
async fn set_queue(&self, tracks: Vec<QueueTrack>, start_index: Option<usize>);
/// The deferred-shuffle core: a real shuffle order, never an invented
/// identity order (Slint must call this, not fake it via `set_queue`).
async fn set_queue_with_order(
&self,
tracks: Vec<QueueTrack>,
start_index: Option<usize>,
shuffle_enabled: bool,
shuffle_order: Option<Vec<usize>>,
);
async fn clear_queue(&self, keep_current: bool);
async fn play_index(&self, index: usize) -> Option<QueueTrack>;
// ---- catalog (async) ----
async fn get_track(&self, track_id: u64) -> Result<Track, String>;
async fn get_tracks_batch(&self, track_ids: &[u64]) -> Result<Vec<Track>, String>;
// ---- protected audio seam, behind one high-level method ----
/// Resolve the stream URL at `quality`, probe the FLAC format, start a
/// progressive stream into the player and SPAWN the HTTP feeder; on a
/// streaming error, fall back to a full download + `play_data`. The impl owns
/// `reqwest`, the `BufferWriter`, and the detached spawn — none of which
/// crosses this crate boundary. `start_position_secs` is the seek target
/// (QConnect callers pass 0; resume is local-only).
///
/// This is the ONLY method that touches the protected bit-perfect seams
/// (`play_data` / `play_streaming_dynamic`). It MUST pass the probed
/// sample_rate/channels/bit_depth straight through — never default them, or
/// hi-res remote playback silently resamples.
async fn start_track_stream(
&self,
track_id: u64,
quality: Quality,
duration_secs: u64,
start_position_secs: u64,
) -> Result<(), String>;
// ---- report-back source (the single per-frontend "engine read") ----
/// The ACTUAL DAC output format `(sample_rate, bit_depth)` under bit-perfect
/// passthrough — read from `player().state`. Drives the file/device
/// audio-quality reports. Read-only; never device init.
fn current_output_format(&self) -> Option<(u32, u32)>;
}