Struct SharedPlayerState 

pub struct SharedPlayerState { /* private fields */ }

Shared player state — atomics for lock-free reads from UI thread.

The engine writes these, the UI reads them. No mutexes in the hot path.

Implementations

impl SharedPlayerState

pub fn new() -> Arc<Self>

pub fn playback_state(&self) -> PlaybackState

pub fn set_playback_state(&self, state: PlaybackState)

pub fn position_ms(&self) -> u64

pub fn set_position_ms(&self, pos: u64)

pub fn track_info(&self) -> Option<TrackInfo>

pub fn set_track_info(&self, info: Option<TrackInfo>)

pub fn current_download_fraction(&self) -> Option<f64>

Download fraction (0.0..1.0) for the currently playing track, if streaming. Returns None for fully-downloaded or non-playing tracks.

pub fn request_quit(&self)

pub fn quit_requested(&self) -> bool

pub fn signal_metadata_refresh(&self)

Signal that metadata has been refreshed mid-stream (e.g. download completed). The UI loop calls take_metadata_refresh() to consume this flag and force a souvlaki/cover-art update without waiting for a track change.

pub fn take_metadata_refresh(&self) -> bool

Returns true and clears the flag if a metadata refresh is pending.

pub fn radio_mode(&self) -> bool

pub fn set_radio_mode(&self, enabled: bool)

pub fn output_sample_rate(&self) -> Option<u32>

None until a track has started and the device rate is known.

pub fn set_output_sample_rate(&self, rate: u32)

pub fn clear_output_sample_rate(&self)

Back to “not known yet”, for the window where the device is between rates. A switch takes as long as the hardware needs to reclock — the better part of a second on USB — and the previous track’s rate is not an answer for this one.

pub fn playlist_version(&self) -> u64

pub fn add_items(&self, items: Vec<PlaylistItem>)

Append items to the playlist.

pub fn insert_items_after(&self, items: Vec<PlaylistItem>, after: QueueItemId)

Insert items after a specific queue item.

pub fn update_paths(&self, updates: &[(QueueItemId, PathBuf)])

Update file paths for playlist items (after organize moves files).

pub fn remove_item(&self, id: QueueItemId)

Remove an item by ID.

pub fn move_item(&self, id: QueueItemId, target: QueueItemId, after: bool)

Move an item relative to another entry.

pub fn move_items(&self, ids: &[QueueItemId], target: QueueItemId, after: bool)

Batch move: extract items by ID, reinsert them at target position. Preserves the relative order of the moved items.

pub fn set_cursor(&self, id: Option<QueueItemId>)

Set the cursor (what’s playing / should play).

pub fn cursor(&self) -> Option<QueueItemId>

Get the current cursor ID.

pub fn clear_playlist(&self)

Clear the entire playlist + cursor.

pub fn advance_cursor_loadable(&self) -> Option<QueueItemId>

Move the cursor to the next item that can still play — the first item after the cursor that is not Failed — and return its ID.

An item that is still downloading parks the cursor rather than being skipped, so playback resumes from it when its data lands. Skipping it would drop it from the queue for good.

With no cursor set, starts from the top. A cursor pointing at an item that is no longer in the playlist yields None — restarting from the top would silently replay the queue.

pub fn peek_next_ready_after( &self, after_id: QueueItemId, ) -> Option<(QueueItemId, PathBuf)>

Peek at the next Ready item after a given item ID WITHOUT moving the cursor. Used by the decode thread for gapless lookahead — the cursor is moved later by update_playback_state when playback actually reaches the track.

pub fn retreat_cursor(&self) -> Option<(QueueItemId, PathBuf)>

Retreat cursor to the previous item. Returns (id, path) if found. For prev_track — goes to the item before cursor regardless of load state.

pub fn update_load_state(&self, id: QueueItemId, new_state: LoadState)

Update the load state of a playlist item. Safe — just a field update under lock.

pub fn update_item_metadata( &self, id: QueueItemId, title: String, artist: String, album_artist: String, album: String, duration_ms: Option<u64>, )

Update playlist item metadata after a full download completes. Used for progressive enhancement: streaming started with partial Symphonia tags, now the full file is available so we can refresh with complete lofty metadata.

pub fn item_playback_source(&self, id: QueueItemId) -> Option<PlaybackSource>

Get the playback source for an item if it’s ready to play. Returns None if not enough data is available yet.

pub fn item_path_if_ready(&self, id: QueueItemId) -> Option<PathBuf>

Get the path of an item if it’s Ready (legacy convenience — use item_playback_source for streaming).

pub fn is_cursor(&self, id: QueueItemId) -> bool

Check if the cursor is on the given item.

pub fn same_album_item_ids(&self, id: QueueItemId) -> Vec<QueueItemId>

Get QueueItemIds of all playlist items sharing the same album as the given item. Matches on both album name and album artist to avoid false positives (e.g. two different “Greatest Hits” by different artists).

pub fn pending_downloads(&self) -> Vec<(i64, QueueItemId)>

Get all playlist items that are Pending and have a db_id. Returns (db_id, QueueItemId) pairs suitable for the download queue.

pub fn downloads_in_flight(&self) -> Vec<(QueueItemId, u64, u64)>

Every item mid-transfer, with the bytes it has and the bytes it expects.

Progress moves without the playlist version moving — the download thread writes the byte counter directly — so anything following the version alone shows a frozen bar. This is how a watcher sees it move.

pub fn item_db_id(&self, id: QueueItemId) -> Option<i64>

Get the db_id for a specific playlist item.

pub fn item_load_state(&self, id: QueueItemId) -> Option<LoadState>

Get the load state of a specific playlist item.

pub fn snapshot_playlist(&self) -> (Vec<PlaylistItem>, Option<QueueItemId>)

Get the full playlist snapshot (items + cursor) for undo of ClearPlaylist.

pub fn get_item(&self, id: QueueItemId) -> Option<PlaylistItem>

Get an item by ID (for undo of RemoveFromPlaylist).

pub fn item_before(&self, id: QueueItemId) -> Option<QueueItemId>

Get the ID of the item immediately before the given ID (None if first).

pub fn reorder_to(&self, order: &[QueueItemId])

For each ID, the ID of the item before it (or None if first), returned in playlist order regardless of the order ids arrives in.

Undo replays these left to right, so an item whose recorded predecessor is also in ids must come after it — otherwise the predecessor is missing at replay time and the item lands at the end of the playlist instead. Put the items in exactly this order.

Items not named keep their relative order and follow at the end, so a stale order cannot lose anything. The items themselves are moved, not rebuilt: their ids, load states and download progress are what the rest of the player is holding on to.

pub fn items_before( &self, ids: &[QueueItemId], ) -> Vec<(QueueItemId, Option<QueueItemId>)>

pub fn surviving_item_before( &self, id: QueueItemId, removed: &[QueueItemId], ) -> Option<QueueItemId>

The nearest item before id that is not itself being removed — where playback resumes from after a batch delete that takes out the cursor. None means resume from the top of what survives.

pub fn restore_playlist( &self, items: Vec<PlaylistItem>, cursor: Option<QueueItemId>, )

Restore a full playlist from snapshot (for redo of ClearPlaylist undo).

pub fn remove_items(&self, ids: &[QueueItemId])

Remove multiple items by IDs.

pub fn insert_item_at(&self, item: PlaylistItem, after: Option<QueueItemId>)

Insert a single item after a given ID (or at front if None).

pub fn move_item_to(&self, id: QueueItemId, after: Option<QueueItemId>)

Move a single item to after after (or to front if None).

pub fn move_items_to(&self, entries: &[(QueueItemId, Option<QueueItemId>)])

Batch move: reposition each item to after its given predecessor. Processes in order so earlier insertions don’t corrupt later positions.

pub fn derive_visible_queue(&self) -> VisibleQueueSnapshot

Derive the visible queue from the playlist + cursor. O(n). Called once per UI tick.

Trait Implementations

impl Debug for SharedPlayerState

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.