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 — the raw convenience layer: just the samples, no metadata. With explicit normalization (e.g. for_whisper) the shape is already known and this is the whisper-rs / candle handoff form; with the source-preserving defaults the buffer arrives in the source’s own rate/channel shape, which a bare Vec<f32> does not describe — use collect_audio for the same samples with their sample rate, channel count, and channel layout attached, or stream samples for per-chunk metadata.

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.

pub fn collect_audio(self) -> Result<CollectedAudio>

Runs to completion and returns every exported sample together with the shape metadata that describes the buffer — the self-describing form of collect_samples: same samples, same order, plus the sample rate, channel count, and channel layout they were decoded to.

Metadata is read from the first delivered chunk (one run negotiates one output shape), so it reports what the run actually produced: the source shape under the default passthrough, or the converted shape when sample_rate / channels requested one. When the run delivers no samples at all (an empty audio stream), the buffer is empty and the metadata is zeroed (rate 0, channels 0, empty layout).

The memory bound and error behavior match collect_samples.

use ez_ffmpeg::frame_export::SampleExtractor;

// Source-preserving extraction that still knows its own shape.
let audio = SampleExtractor::new("input.mp4").collect_audio()?;
println!(
    "{} samples @ {} Hz, {} channel(s), layout {}",
    audio.as_slice().len(),
    audio.sample_rate(),
    audio.channels(),
    audio.channel_layout(),
);