Struct PlayerHandle 

pub struct PlayerHandle { /* private fields */ }

Shared, cloneable handle to a running PlayerRunner.

All methods are non-blocking. Commands that cannot be queued immediately (channel full) are silently dropped.

Thread safety

PlayerHandle is Clone + Send + Sync and can be shared freely across threads without locking.

Implementations

impl PlayerHandle

pub fn play(&self)

Resume playback.

pub fn pause(&self)

Pause playback.

pub fn stop(&self)

Stop the presentation loop.

pub fn seek(&self, pts: Duration)

Seek to pts.

Consecutive calls before the runner processes them are coalesced — only the most recent pts executes.

pub fn set_rate(&self, rate: f64)

Set the playback rate.

• Positive values play forward at the given speed multiplier (e.g. 2.0 = 2×).
• Negative values play in reverse at abs(rate) speed (e.g. -1.0 = 1× reverse). Audio is muted during reverse playback and automatically resumes on the next positive-rate call.
• 0.0 is ignored.

pub fn set_av_offset(&self, ms: i64)

Set the A/V offset correction in milliseconds.

Positive: video PTS is shifted down relative to audio (video appears delayed). Negative: video PTS is shifted up (audio appears delayed).

pub fn update_timeline(&self, timeline: Timeline)

Replace the running timeline’s clip layout in place.

Sends a PlayerCommand::UpdateLayout to TimelineRunner. The runner updates timeline_start / timeline_end / in_point / out_point for every existing clip, stops audio decode threads, and seeks all decode buffers to the last known media PTS — so the next presented frame is spatially correct after the move.

The MasterClock and paused / stopped atomics are unaffected. Drops silently if the command channel (capacity 64) is full.

No-op when called on a PlayerRunner-backed handle (single-track player). Only TimelineRunner handles this command.

pub fn current_pts(&self) -> Duration

PTS of the most recently presented frame.

Returns Duration::ZERO before the first frame is presented.

pub fn duration(&self) -> Option<Duration>

Container-reported duration, or None for live / streaming sources.

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

Sample rate of the PCM data returned by pop_audio_samples.

Returns Some(48_000) for files that contain an audio stream, and None for video-only files (where pop_audio_samples always returns an empty Vec).

Use this to configure your audio backend without hardcoding a magic constant:

let cfg = cpal::StreamConfig {
    channels: 2,
    sample_rate: cpal::SampleRate(handle.audio_sample_rate().unwrap_or(48_000)),
    ..Default::default()
};

pub fn pop_audio_samples(&self, n: usize) -> Vec<f32>

Pull up to n interleaved stereo f32 PCM samples at 48 kHz.

Returns an empty Vec when:

• playback is paused or stopped,
• n is 0,
• there is no audio track, or
• the ring buffer is empty (underrun — caller should output silence).

Advances the audio master clock by samples.len() / 2 stereo frames.

pub fn pop_audio_samples_for_rate( &self, pop_n: usize, clock_stereo_pairs: u64, ) -> Vec<f32>

Pull up to pop_n interleaved stereo f32 PCM samples at 48 kHz and advance the A/V sync clock by exactly clock_stereo_pairs — independent of how many samples are actually available in the ring buffer.

Use this instead of pop_audio_samples when playing at rates other than 1×. The cpal callback pops out_len * rate decoded samples to drive rate-scaled audio, but the master clock must still advance at the hardware output rate (out_len / 2 per callback) so that MasterClock::Audio’s pts_base + delta / sr * rate formula yields the correct media PTS without double-counting the rate.

Arguments

• pop_n — decoded samples to drain from the ring buffer (output_buf.len() * rate, rounded).
• clock_stereo_pairs — hardware stereo pairs to add to the sync counter (output_buf.len() / 2, constant regardless of rate).

pub fn poll_event(&self) -> Option<PlayerEvent>

Poll for the next PlayerEvent without blocking.

Returns None when no events are pending.

pub fn recv_event(&self) -> Option<PlayerEvent>

Block until the next PlayerEvent arrives or the channel closes.

Returns None when the runner has exited and all events have been drained. Intended for use inside spawn_blocking.

Trait Implementations

impl Clone for PlayerHandle

fn clone(&self) -> PlayerHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.