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.

Values ≤ 0.0 are silently ignored by the runner.

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