Struct SampleAccurateSeeker 

pub struct SampleAccurateSeeker {
    pub track: TrackIndex,
    /* private fields */
}

Performs sample-accurate seeking on a single media track.

Wraps a TrackIndex and provides a high-level seek_to_sample method that finds the nearest keyframe at or before a target PTS, returning the exact byte offset and the number of samples that must be decoded and discarded to reach the target position.

Example

use oximedia_container::seek::{SeekIndex, SeekIndexEntry, TrackIndex, SampleAccurateSeeker};

let mut index = SeekIndex::new(90000);
// … populate index …
let track = TrackIndex::new(index);
let seeker = SampleAccurateSeeker::with_track(track);

let result = seeker.seek_to_sample(45000, &seeker.track).expect("seek should succeed");
println!("Seek to file offset {}", result.sample_offset);
println!("Discard {} samples after decoding", result.preroll_samples);

Fields

track: TrackIndex

The primary track index used for single-track seek operations.

This field is set when constructed with SampleAccurateSeeker::with_track. It holds a default empty TrackIndex when constructed with SampleAccurateSeeker::new (multi-stream mode).

Implementations

impl SampleAccurateSeeker

pub fn new() -> Self

Creates a new multi-stream SampleAccurateSeeker with no pre-loaded streams.

Use SampleAccurateSeeker::add_stream to register stream indices, then call SampleAccurateSeeker::plan_preroll_seek to plan seeks.

pub fn with_track(track: TrackIndex) -> Self

Creates a SampleAccurateSeeker from a single pre-built TrackIndex.

This is the single-track constructor. Use new() instead for multi-stream workflows.

pub fn add_stream(&mut self, stream_id: u32, index: SeekIndex)

Registers a per-stream SampleIndex for multi-stream pre-roll seeking.

The stream_id must match the stream identifier used when calling SampleAccurateSeeker::plan_preroll_seek.

pub fn plan_preroll_seek( &self, stream_id: u32, target_pts: i64, max_preroll: Option<u32>, ) -> Option<PreRollSeekPlan>

Plans a pre-roll seek for stream_id to target_pts.

Returns a crate::preroll::PreRollSeekPlan describing the keyframe to start decoding from and the chain of samples to decode (some discarded, some presented) in order to reach target_pts sample-accurately.

max_preroll optionally limits the maximum number of decode-and-discard samples. When the distance from keyframe to target exceeds this limit the chain is truncated.

Returns None if stream_id has not been registered or the index has no keyframe at or before target_pts.

pub fn preroll_count(&self, stream_id: u32, target_pts: i64) -> Option<u32>

Returns the number of samples that must be decoded and discarded (pre-roll count) to achieve sample-accurate positioning at target_pts in stream_id.

Returns None if the stream is not registered or has no suitable keyframe.

pub fn seek_to_sample( &self, target_pts: u64, track: &TrackIndex, ) -> Option<SeekResult>

Seeks to the sample-accurate position for target_pts within track.

The algorithm:

1. Finds the nearest keyframe at or before target_pts using binary search on the track’s seek index.
2. Counts every sample between the keyframe (exclusive) and the target sample (exclusive) — these must be decoded and discarded.
3. Adds the track’s codec_delay_samples to the discard count.

Returns

Some(SeekResult) if a keyframe is found, or None if the index is empty or no keyframe exists before target_pts.

Arguments

• target_pts — desired presentation timestamp in the track’s timescale.
• track — the TrackIndex to search (typically &self.track).

Trait Implementations

impl Default for SampleAccurateSeeker

fn default() -> Self

Returns the “default value” for a type.