Struct Queue 

pub struct Queue<S>
where
    S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,
{ /* private fields */ }

AVQueuePlayer-analogue orchestration facade.

Owns the resident player and its canonical synchronization state. Runtime commands are exposed through a separate cloneable QueueControl.

Implementations

impl<S> Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

pub fn append<T: Into<TrackSource<S>>>( &self, source: T, ) -> Result<TrackId, QueueError>

Append a track while this concrete queue remains owned by its caller.

Errors

Returns QueueError::Play after the resident player is closed.

pub fn append_with_id<T: Into<TrackSource<S>>>( &self, id: TrackId, source: T, ) -> Result<TrackId, QueueError>

Append a track with a caller-owned stable id.

Errors

Returns QueueError::Play after the resident player is closed.

pub fn insert<T: Into<TrackSource<S>>>( &self, source: T, after: Option<TrackId>, ) -> Result<TrackId, QueueError>

Insert a track after after, or at the head when it is absent.

Errors

Returns QueueError when after is not present.

pub fn insert_with_id<T: Into<TrackSource<S>>>( &self, id: TrackId, source: T, after: Option<TrackId>, ) -> Result<TrackId, QueueError>

Insert a track with a caller-owned stable id.

Errors

Returns QueueError when after is not present.

pub fn next( &self, transition: Transition, ) -> Result<Option<TrackId>, QueueError>

Advance to the next navigation-owned track.

Errors

Returns a queue or player error when the successor cannot be selected.

pub fn previous( &self, transition: Transition, ) -> Result<Option<TrackId>, QueueError>

Return to the previous navigation-owned track.

Errors

Returns a queue or player error when the predecessor cannot be selected.

impl<S> Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

pub fn new(config: QueueConfig<S>) -> Self

Build a queue from a QueueConfig.

The queue takes ownership of the supplied PlayerImpl; all access to the decorated player then goes through this facade.

Methods from Deref<Target = QueueControl<S>>

pub fn action_at_item_end(&self) -> ActionAtItemEnd

pub fn current(&self) -> Option<TrackEntry>

The currently playing track entry, if any.

Sourced from the navigation cursor (not the player) so the queue reports None after advance_to_next runs off the end of the queue (RepeatMode::Off exhaustion). The player’s own current_index stays parked at the last-played slot — read it via Self::current_index when the call site needs the last-played index even after queue-end.

pub fn current_index(&self) -> Option<usize>

The currently playing track’s queue index (player-reported).

pub fn set_action_at_item_end(&self, action: ActionAtItemEnd)

pub fn set_playback_order(&self, order: PlaybackOrder)

pub fn set_repeat(&self, mode: RepeatMode)

Set repeat mode.

pub fn subscribe<E: EventSet>(&self) -> EventReceiver<E>

Subscribe to the unified event stream: QueueEvent + underlying player / audio / hls / file events.

pub fn track(&self, id: TrackId) -> Option<TrackEntry>

Lookup a track entry by id.

pub fn track_source(&self, id: TrackId) -> Option<TrackSource<S>>

The original TrackSource for id, if still queued. Lets callers rebuild a resource by track identity rather than by queue position.

pub fn attach_observer<O: AudioObserver>(&self, id: TrackId, observer: O)

Attach a bounded decoded-audio observer to id’s decoder.

Attachment is nonblocking and works before, during, or after resource loading. Only one observer is active for a track at a time.

pub fn current_abr_handle(&self) -> Option<AbrHandle>

ABR handle of the currently playing adaptive item, if any.

Returned handle drives runtime variant/bandwidth control — FFI and GUI use it for set_abr_mode / set_preferred_peak_bitrate.

pub fn sample_rate(&self) -> u32

Rate the player’s master bus runs at, and therefore the frame axis used by decoded-audio observers attached to this queue.

pub fn current_variant(&self) -> Option<VariantInfo>

Live variant metadata of the currently playing adaptive item. Pulled from the player’s stashed ABR handle on every call so a renderer can poll for the up-to-date label after every frame without depending on event delivery.

pub fn is_empty(&self) -> bool

Whether the queue is empty.

pub fn playback_order(&self) -> PlaybackOrder

Current traversal order.

pub fn len(&self) -> usize

Number of tracks currently in the queue.

pub fn repeat_mode(&self) -> RepeatMode

Current repeat mode.

pub fn tracks(&self) -> Vec<TrackEntry>

Snapshot of all track entries, in queue order.

pub fn append<T: Into<TrackSource<S>>>( &self, source: T, ) -> Result<TrackId, QueueError>

Append a track. Loading starts immediately in the background. The id is allocated from the global counter via TrackId::allocate; use Self::append_with_id when the caller owns the id (FFI item pre-allocation).

Errors

Returns QueueError::Play after the resident player is closed.

pub fn append_with_id<T: Into<TrackSource<S>>>( &self, id: TrackId, source: T, ) -> Result<TrackId, QueueError>

Append a track with a caller-supplied id. The id MUST come from TrackId::allocate so it stays inside the process-wide monotonic address space. Used by the FFI layer where the item reserves its id at construction and surfaces it as audioId before insert.

Errors

Returns QueueError::Play after the resident player is closed.

pub fn clear(&self)

Remove all tracks from the queue. Dropping the records aborts their in-flight loads.

pub fn insert<T: Into<TrackSource<S>>>( &self, source: T, after: Option<TrackId>, ) -> Result<TrackId, QueueError>

Insert a track after the given id, or at the head when after is None. Loading starts immediately.

Errors

Returns QueueError::UnknownTrackId if after does not match any track.

pub fn insert_with_id<T: Into<TrackSource<S>>>( &self, id: TrackId, source: T, after: Option<TrackId>, ) -> Result<TrackId, QueueError>

Insert a track with a caller-supplied id. See Self::append_with_id for why the id MUST come from TrackId::allocate.

Errors

Returns QueueError::UnknownTrackId if after does not match any track.

pub fn remove(&self, id: TrackId) -> Result<(), QueueError>

Remove a track from the queue by id.

If the removed track is currently playing:

• with tracks remaining → switches to the next (or previous if we were at the tail) with an immediate cut.
• with no tracks remaining → pauses the player.

Errors

Returns QueueError::UnknownTrackId if id is not in the queue.

pub fn set_tracks<I, T>(&self, sources: I)

where I: IntoIterator<Item = T>, T: Into<TrackSource<S>>,

Replace the entire queue with the given sources.

pub fn bus(&self) -> &EventBus

Underlying event bus used by queue and player events.

pub fn crossfade_settings(&self) -> CrossfadeSettings

pub fn process_notifications(&self)

Drain pending player-side notifications. Called by FFI tick loops after Self::tick.

pub fn reset_eq(&self) -> Result<(), PlayError>

Reset all EQ bands to 0 dB.

Errors

Forwards PlayError from the underlying player.

pub fn set_crossfade_settings( &self, settings: CrossfadeSettings, ) -> Result<(), PlayError>

Update the profile captured by future transitions.

Errors

Returns an error when any profile value is invalid.

pub fn set_default_rate(&self, rate: f32)

Set the default playback rate.

pub fn set_eq_gain(&self, band: usize, gain_db: f32) -> Result<(), PlayError>

Set gain for an EQ band.

Errors

Forwards PlayError from the underlying player.

pub fn set_eq_layout(&self, layout: Vec<EqBandConfig>) -> Result<(), PlayError>

Replace the live player’s EQ band layout.

Errors

Forwards PlayError from the underlying player.

pub fn set_muted(&self, muted: bool)

Set the mute flag.

pub fn set_rate(&self, rate: f32)

Set the live playback rate (mirrors into the tempo-mode sibling so a running key-locked stretch tracks the move).

pub fn set_volume(&self, volume: f32)

Set the volume (0.0..=1.0).

pub fn is_playing(&self) -> bool

Whether playback is active.

pub fn rate(&self) -> f32

Live engine playback rate (player-reported, 0.0 when paused).

pub fn default_rate(&self) -> f32

Default playback rate.

pub fn volume(&self) -> f32

Current volume (0.0..=1.0).

pub fn is_muted(&self) -> bool

Whether output is muted.

pub fn status(&self) -> PlayerStatus

Live engine playback status.

pub fn engine_load(&self) -> EngineLoadSnapshot

Live audio-engine cost (realtime factor / load / ms).

pub fn eq_band_count(&self) -> usize

Number of EQ bands.

pub fn eq_gain(&self, band: usize) -> Option<f32>

Current gain for an EQ band.

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

Current track duration in seconds.

pub fn notify_audio_route_changed(&self, reason: &str) -> Result<(), QueueError>

Platform audio-route changed while playback may be active.

Recreates the native output stream below the queue without changing queue state, current item, or track loading.

Errors

Returns QueueError when the underlying player cannot restart the active audio route.

pub fn notify_interruption(&self, kind: InterruptionKind)

The platform interrupted, or released, the audio output.

Recording the fact is all this does: an interruption leaves the native output unscheduled, and restoring it is the route-invalidation path.

pub fn pause(&self)

Pause playback and freeze the queue-visible head position.

pub fn play(&self)

Starts playback, marking a consumed slot or retaining the selection until loading finishes. Reconciliation is serialized with load completion.

pub fn playback_view(&self) -> PlaybackView

Single coherent read of the player’s live playback state.

Pollers (the FFI time thread, snapshot) get position, duration, decoded frontier, and the playing flag from one call instead of several separate accessors. The player-sourced fields come from one PlaybackSnapshot via its From conversion; position is then replaced with this queue’s cached, 0.0-smoothed value.

pub fn set_session_ducking( &self, mode: SessionDuckingMode, ) -> Result<(), QueueError>

Lower or restore the whole session output under a competing sound, such as a call or a navigation prompt.

Errors

Returns QueueError when the session rejects the change.

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

Latest monotonic playback position for the current track in seconds. Updated on every Self::tick; skips transient 0.0 samples the engine produces on pause/resume so downstream UIs see stable values.

pub fn seek(&self, seconds: f64) -> Result<SeekOutcome, QueueError>

Seek within the currently-playing track.

Seek-hang detection is not handled here: the audio pipeline’s own #[hang_watchdog] instrumentation (e.g. Audio::read, Stream::read, decode_next_chunk) already panics with a stacktrace and context dump when no progress is observed. Adding a second Queue-level watchdog would just duplicate those panics.

Returns the typed SeekOutcome — either Landed with the requested target (the actual landed position is reconciled by the worker after applying the seek; this call returns the optimistic outcome) or PastEof if the target is beyond the known track duration.

Errors

Returns QueueError::Play if the player reports a seek failure.

pub fn tick(&self) -> Result<(), QueueError>

Periodic tick: drives PlayerImpl::tick and drains queued engine events to act on ItemDidPlayToEnd (filtered) and forward CurrentItemChanged as QueueEvent::CurrentTrackChanged.

Errors

Forwards PlayError from PlayerImpl::tick.

pub fn select( &self, id: TrackId, transition: Transition, ) -> Result<(), QueueError>

Select a track by id, applying the given Transition. If the track is still loading or pending, both the id and the transition are stashed and applied when loading finishes.

Errors

Returns QueueError::UnknownTrackId if id is not in the queue, QueueError::NotReady if the track is in a terminal failed state, or QueueError::Play if the underlying select_item call fails.

pub fn next( &self, transition: Transition, ) -> Result<Option<TrackId>, QueueError>

Advance to the next track per navigation rules. Returns the newly selected id, or None when the queue has ended (and RepeatMode::Off is active).

Errors

Returns a queue or player error when the successor cannot be selected.

pub fn previous( &self, transition: Transition, ) -> Result<Option<TrackId>, QueueError>

Go back to the previous track. Returns the newly selected id, or None at index 0.

Errors

Returns a queue or player error when the predecessor cannot be selected.

pub fn close(&self) -> Result<(), PlayError>

Close the resident player, then irreversibly cancel queue-owned work.

Errors

Returns the player detach failure without cancelling the queue token; the player control gate is reopened so the owner can retry.

pub fn is_closed(&self) -> bool

Trait Implementations

impl<S> BeatGrid for Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

fn id(&self) -> BeatGridId

Returns the stable identity of this grid owner.

fn snapshot(&self) -> BeatGridSnapshot

Returns one immutable snapshot for a complete multi-step calculation.

impl<S> Deref for Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

type Target = QueueControl<S>

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl<S> Drop for Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<S> Player for Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

fn play(&self)

Start or resume playback.

fn pause(&self)

Pause playback.

fn playback_view(&self) -> PlaybackView

Read one coherent playback view.

fn close(&mut self) -> Result<(), PlayError>

Stop owned work and detach the player from its playback session.

fn seek_seconds(&self, seconds: f64) -> Result<SeekOutcome, PlayError>

Seek within the current item.

fn tick(&self) -> Result<(), PlayError>

Advance control-plane and audio-backend work.

fn set_host_level(&self, level: f32)

Commit the host-applied deck level after a validated graph batch.

fn host_level(&self) -> f32

Read the desired host-applied deck level.

impl<S> PlayerControlSource for Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

type Control = QueueControl<S>

Concrete command capability retained by typed host-owned handles.

type Schema = S

Typed pool schema shared with the canonical playback session.

fn close_control(control: &Self::Control) -> Result<(), PlayError>

Closes the resident player through a previously issued capability.

fn control(&self) -> Self::Control

Creates a command capability for this player.

fn prepare_control(control: &Self::Control) -> Result<(), PlayError>

Prepare the attached graph and slot before exposing musical controls.

fn attach_session( &mut self, binding: SessionBinding<S>, ) -> Result<(), PlayError>

Attaches the resident Player to its canonical session exactly once.

impl<S> SyncGroup for Queue<S>

where S: HasPool<u8> + HasPool<f32> + Send + Sync + 'static,

type NestedGroup = PlayerMember

Concrete synchronization-group type accepted as a direct child.

fn status(&self) -> SyncStatusSnapshot

Returns the canonical control-plane view of this group’s sync state.

fn stage_fact(&self, fact: ParentFact) -> Result<SyncStaged, SyncError>

Computes, without mutation, everything a parent fact changes across this subtree, so a parent can refuse the fact before any member changes.

fn apply_staged(&mut self, staged: SyncStaged) -> SyncTransition

Commits a change Self::stage_fact computed on this unchanged subtree, and returns every preparation it issued and withdrew.

fn topology(&self) -> Result<SyncGroupSnapshot, SyncError>

Returns one immutable topology snapshot for a complete calculation.

fn transact( &mut self, operation: SyncOperation<PlayerMember>, ) -> Result<SyncAdmission, SyncRejected<PlayerMember>>

Validates and admits one operation without claiming audible application.

fn acknowledge( &mut self, receipt: SyncReceipt, ) -> Result<SyncStatusSnapshot, SyncError>

Records an executor’s receipt for one preparation in this subtree and returns the resulting state of the group that issued it.