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 bump_generation(&self) -> u64

pub fn generation(&self) -> u64

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 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(&self) -> Option<(QueueItemId, PathBuf)>

Advance cursor to the next Ready item. Returns (id, path) if found. Moves the cursor. Used for explicit next-track commands.

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 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 items_before( &self, ids: &[QueueItemId], ) -> Vec<(QueueItemId, Option<QueueItemId>)>

For each ID, get the ID of the item before it (or None if first). Used to snapshot positions before a batch move for undo.

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.