Struct PreviewPlayer 

pub struct PreviewPlayer { /* private fields */ }

Drives real-time playback of a single media file.

PreviewPlayer decodes a video/audio file, synchronises video frame presentation to an audio master clock, and delivers frames to a registered FrameSink.

Usage

let mut player = PreviewPlayer::open(Path::new("clip.mp4"))?;
player.set_sink(Box::new(MySink::new()));
player.play();
player.run()?;

Implementations

impl PreviewPlayer

pub fn open(path: &Path) -> Result<Self, PreviewError>

Open a media file and prepare for playback.

Probes the file to detect audio presence and frame rate, then opens a DecodeBuffer for the video stream. Returns PreviewError if the file is missing or contains no decodable stream.

Errors

Returns PreviewError if the file cannot be probed or decoded.

pub fn set_sink(&mut self, sink: Box<dyn FrameSink>)

Register the frame sink. Must be called before run.

pub fn play(&mut self)

Start (or resume) playback.

Clears the paused and stopped flags. Must be called before run.

pub fn pause(&mut self)

Pause playback. run will spin-sleep until play is called again.

pub fn stop(&mut self)

Stop playback.

run returns after the current frame completes.

pub fn stop_handle(&self) -> Arc<AtomicBool>

Returns a cloneable handle to the stop signal.

Storing true into the returned Arc<AtomicBool> has the same effect as calling stop and is safe to call from any context, including from within a FrameSink::push_frame callback.

Example

let stop = player.stop_handle();
player.set_sink(Box::new(MySink { stop, max_frames: 10 }));
player.play();
player.run()?;

pub fn pop_frame(&mut self) -> FrameResult

Pop the next decoded video frame.

Delegates to DecodeBuffer::pop_frame. Blocks until a frame is available. Returns FrameResult::Eof at end of file.

pub fn seek(&mut self, target_pts: Duration) -> Result<(), PreviewError>

Frame-accurate seek to target_pts.

Delegates to DecodeBuffer::seek.

Errors

Returns PreviewError if the seek fails.

pub fn use_proxy_if_available(&mut self, proxy_dir: &Path) -> bool

If a proxy file for this media exists in proxy_dir, use it transparently.

Must be called before play. Returns true if a proxy was found and activated; returns false if no proxy exists (original file continues to be used).

Proxy lookup order: half → quarter → eighth; first match wins.

When a proxy is active, FrameSink::push_frame delivers frames at the proxy’s native resolution. Callers should not assume a fixed resolution.

If called after play, logs a warning and returns false.

pub fn active_source(&self) -> &Path

Returns the path currently being decoded — either the original file or the activated proxy.

pub fn set_av_offset(&self, ms: i64)

Set the A/V offset correction in milliseconds.

• Positive value: video is delayed by ms ms relative to the audio clock (video PTS is shifted down in the sync comparison).
• Negative value: audio is delayed by ms ms relative to video (video PTS is shifted up in the sync comparison).

Values outside ±5 000 ms are clamped and a warning is logged. Safe to call from any thread while run is executing.

pub fn av_offset(&self) -> i64

Returns the current A/V offset in milliseconds (default: 0).

Safe to call from any thread while run is executing.

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

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

Intended for use inside an audio output callback:

let samples = player.pop_audio_samples(buffer_size);
output_buffer[..samples.len()].copy_from_slice(&samples);
// fill remainder with silence when samples.len() < buffer_size (underrun)

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

Returns an empty Vec when:

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

pub fn run(&mut self) -> Result<(), PreviewError>

A/V sync presentation loop.

Blocks until stop is called or the end of file is reached. Must be called from the presentation thread.

Video PTS is compared against the master clock:

• Early frames (video PTS > clock + 1 frame period): sleep.
• Late frames (video PTS < clock − 1 frame period): dropped.

For video-only files the System clock (Instant) drives real-time pacing. For files with audio the Audio clock drives sync once pop_audio_samples has been called at least once; before that, frames are presented immediately.

Errors

Returns PreviewError if a frame cannot be presented to the sink.

Trait Implementations

impl Drop for PreviewPlayer

fn drop(&mut self)

Executes the destructor for this type.