Struct SampleExtractor 

pub struct SampleExtractor { /* private fields */ }

Decodes an input’s audio into owned, interleaved f32 PCM in one pass, for ASR / audio-ML pipelines.

Build one with SampleExtractor::new, chain options, then call samples for a streaming iterator or collect_samples for one flat buffer.

Defaults preserve the source: the source sample rate and channel layout pass through untouched, and only the sample format is pinned (packed f32) — so the default output is whatever rate/channel shape the source has, NOT a model-ready 16 kHz mono stream. Normalization is opt-in — sample_rate and channels insert a resample / channel-layout conversion — so music and analysis users get no silent rate surprise. Use for_whisper (a thin preset over those two setters) when a speech model expects 16 kHz mono.

use ez_ffmpeg::frame_export::SampleExtractor;

// 16 kHz mono f32 — the whisper-rs / candle handoff shape.
let pcm: Vec<f32> = SampleExtractor::for_whisper("input.mp4").collect_samples()?;

Threading & teardown

A run drives the normal scheduler with the sample sink mounted on the audio output pipeline. The returned SampleIter is Send and fused (exactly one terminal error, then None forever); dropping it early aborts the run cleanly (see SampleIter for the teardown ordering).

Implementations

impl SampleExtractor

pub fn new(input: impl Into<Input>) -> Self

Creates an extractor over input (a path, URL, or anything convertible into an Input). Defaults: best audio stream, source rate, source layout, packed f32, channel capacity 4.

pub fn for_whisper(input: impl Into<Input>) -> Self

Creates an extractor preset for whisper-style ASR: 16 kHz, mono, f32.

Thin convenience over new followed by .sample_rate(16000).channels(Channels::Mono); every other option still applies and can be overridden afterwards.

pub fn audio_stream_index(self, index: usize) -> Self

Selects an explicit audio stream by absolute index (default: best audio stream).

pub fn sample_rate(self, hz: u32) -> Self

Resamples to this output rate in Hz (default: source rate). 0 is rejected at samples time.

pub fn channels(self, channels: Channels) -> Self

Converts to this channel layout (default: source layout). The conversion downmixes, upmixes, or passes through depending on the source layout.

pub fn start_time_us(self, us: i64) -> Self

Seeks to this start time (microseconds) before extracting.

pub fn duration_us(self, us: i64) -> Self

Limits extraction to this many microseconds of content past the start.

pub fn channel_capacity(self, capacity: usize) -> Self

Sets the prefetch channel capacity (default 4, minimum 1). Chunks are small (a few KiB each), so a slightly deeper queue is nearly free.

pub fn samples(self) -> Result<SampleIter>

Starts the run and returns a streaming iterator over the exported chunks.

Option and stream-resolution errors surface here, before any chunk is produced; runtime failures surface as the iterator’s terminal Err.

pub fn collect_samples(self) -> Result<Vec<f32>>

Runs to completion and flattens every exported chunk into one interleaved f32 buffer. With explicit normalization (e.g. for_whisper) this is the whisper-rs / candle handoff shape; with the source-preserving defaults it is simply the source’s own rate/channel shape, and the flat buffer carries no rate/channel metadata — stream samples when you need it per chunk.

Memory is duration_s × rate × channels × 4 bytes (1 h @ 16 kHz mono ≈ 230 MB); use samples to stream when that is too large. On a terminal error the partial samples are dropped and the error is returned.