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 is_waiting(&self) -> bool

Whether the player is waiting for a track it was asked for to arrive. Stopped while waiting, the track opens playing; paused, it opens paused.

pub fn wants_to_play(&self) -> bool

Playing, or waiting for a track that will open playing: what a play/pause toggle pauses.

pub fn is_idle(&self) -> bool

Nothing loaded and nothing waited for: where adding tracks starts them.

pub fn set_transport(&self, state: PlaybackState, waiting: bool)

Publish the playback state and the wait together.

pub fn position_ms(&self) -> u64

Where the playhead is, read off the samples the output has played, so it is right whenever it is asked and nothing has to keep it up to date.

pub fn set_position_ms(&self, pos: u64)

pub fn playhead_moving(&self) -> bool

Set by the player while a renderer is the output. A change to it is a change clients are told about: the clock only moves when the renderer is heard from, or when a command moved it. Whether the playhead is advancing on its own. Playing, but held, while a renderer has been told to play and has not yet started: a client counting on from the command would run ahead of the sound.

A renderer playing a file keeps its clock here; one playing a stream processed here keeps it on the timeline, in time into the stream.

pub fn renderer(&self) -> Option<Output>

The renderer this koan is playing to, when it is not its own output.

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

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

pub fn seekable_ms(&self) -> u64

How far into the currently playing track a seek can land.

A track on disk is seekable end to end. One still downloading is seekable only as far as its bytes reach: bytes map to time by the average bitrate, exact for lossless and CBR and drifting on VBR, which is what SEEK_SAFETY_MS covers. Zero when nothing is playing.

The one value both the clamp in Player::seek and the extent front ends draw on the seek bar come from — a bar that shows a reachable position the player then refuses is worse than no bar.

pub fn duration_ms(&self) -> u64

The duration to show for what is playing.

The container’s own answer wherever it gave one. A partial file that could not be read far enough to state a duration has none, and the library’s figure stands in — it came from the server, it is right, and a transport that reads 0:00 for nine hours of music is worse than one reading a figure the container has not caught up with yet.

pub fn seek_ceiling_ms(&self) -> Option<u64>

seekable_ms, but None when the whole track is reachable — which is every track that is not mid-download. What a front end draws a boundary from: no boundary is the normal case and should cost no mark.

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 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 dsp(&self) -> Option<DspStatus>

pub fn set_dsp(&self, status: Option<DspStatus>)

pub fn play_mode(&self) -> PlayMode

pub fn set_play_mode(&self, mode: PlayMode)

The player’s publish, and nothing else — but for a front end that mirrors another process’s player into a state of its own, as it mirrors the playback state. The mode is saved with the queue, so a change moves the content version.

pub fn playlist_version(&self) -> u64

pub fn content_version(&self) -> u64

pub fn pending_version(&self) -> u64

See the field. Moves with every content change, and when an item goes back to Pending.

pub fn downloads(&self) -> &Arc<DownloadStore>

The transfers this player’s items are fetched by.

pub fn changed(&self)

Say that something here moved, without saying what.

Every version and atomic in this struct stays exactly as it was — they are what a watcher consults to find out what changed. This is what spares it looking when nothing did. See crate::signal.

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 is_empty(&self) -> bool

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

pub fn cursor_path(&self) -> Option<PathBuf>

The path of the item under the cursor, without copying the playlist.

pub fn replace_playlist( &self, items: Vec<PlaylistItem>, ) -> (Vec<PlaylistItem>, Option<QueueItemId>)

Clear the entire playlist + cursor. Swap the whole playlist for items, with no cursor, as one change. Returns what it held, for undo.

One write and one version bump, not a clear and an add. The download queue reads the playlist on its own thread whenever it changes, and an empty playlist between the two would read as nothing wanted: every transfer for a track in both the old queue and the new one let go, cancelled, and started again.

pub fn clear_playlist(&self)

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, from the top again when the queue repeats — and return its ID. An advance is a move on, so repeating one item wraps the queue here as repeating the queue does; playing the item again at its end is the player’s call.

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 lookahead_after(&self, after_id: QueueItemId) -> Option<Lookahead>

One step of the decoder’s gapless lookahead from after_id. Does not move the cursor; update_playback_state does that when the playhead gets there.

Failed items are passed over, as advance_cursor_loadable passes over them. A track still arriving is not: the decoder stops at it, the session drains, and the advance that follows waits for it. Passing over it would play the track after it and move the cursor beyond it, so it would never be heard.

The play mode decides what follows: the queue’s next item, the first again at its end when the queue repeats, or the same item when one repeats — gapless all three.

None when after_id has been removed: the lookahead then has nothing to follow, and starting from the top would gaplessly replay the queue.

pub fn still_follows(&self, step: &Lookahead) -> bool

Whether the decoder would still take step: under the play mode now, next still follows after. A track it stopped at landing since is not a change, since the advance at the end of the session plays it in order; an edit that puts another track first is, and so is a change of mode that sends the queue elsewhere — a wrap once repeat is off, or a track appended after the one a wrap left from.

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, and from the first to the last while repeat is on.

pub fn update_item_state(&self, id: QueueItemId, new_state: ItemState)

Update the load state of a playlist item.

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

An item’s own state, without the rest of it.

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

Take what a finished download’s own tags can add.

Streaming starts on partial Symphonia tags, so an item with nothing behind it takes the lot once the whole file is there. An item that came out of the library does not: the record is what the queue was built from and what every other track on it carries, and a file whose tags disagree — a server album titled one way, the file inside titled another — would split its album in two the moment it finished downloading. The duration is the file’s to know either way.

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 reset_items_with_missing_files(&self) -> Vec<(i64, QueueItemId)>

Put back to Pending every queue item whose file has gone, and say which they were so they can be fetched again.

The queue holds paths, and clearing downloads deletes the files under them. An item left claiming Ready opens nothing when it is played — it is not broken, it is a remote track that has to be fetched a second time. Only items with a database row behind them: one without has nowhere to be fetched from, and parking the cursor on it would be worse than letting it fail honestly.

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

The item’s path if it is Ready. A caller that can stream wants item_playback_source.

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

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)>

Every playlist item still waiting for its file that has a track to fetch, as (db_id, QueueItemId), in the order the player will reach it: from the cursor to the end, then from the top. What the download queue fetches, and in that order — the tracks before the cursor are the ones least likely to be played next.

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

Every entry with a library track, in the order pending_downloads gives, whatever its state: what the cache has to hold, downloaded or not, for the player to reach it.

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])

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 shuffle_order(&self) -> Vec<(QueueItemId, Option<u32>)>

Every item’s id and where it stood before shuffling, in queue order: what undoing a shuffle puts back.

pub fn restore_shuffle_order(&self, order: &[(QueueItemId, Option<u32>)])

Put back an order shuffle_order read, positions before shuffling included. Items not named keep theirs and follow, as in reorder_to.

pub fn shuffle_after_cursor(&self)

Note where every item stands, then put the items after the cursor in a random order — all of them with no cursor. The playing item stays where it is, so nothing that is heard changes.

pub fn shuffle_from(&self, start: QueueItemId)

A queue arriving whole while shuffle is on — replaced, or added to an empty one — plays shuffled: start first, the rest in a random order after it, each item noting where it was given so turning shuffle off puts the queue back as it came. A queue that already carries those notes, a shuffled session restored, is left as it was saved.

pub fn unshuffle(&self)

Put the items shuffle moved back in the order they had before it, in the places such items occupy now. An item added since keeps its place.

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

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.