Struct FileStream 

pub struct FileStream { /* private fields */ }

A nonblocking, allocation-free consumer of a fixed PCM ring. Requires file-stream on native targets; mixer integration additionally needs mixer.

Opening waits for header scanning and one prefilled ring, on a loading thread. WAV/FLAC/MP3 files are read through a bounded encoded window, never loaded whole. MP3 opening scans frame headers once; compressed seeks replay from the start on the worker, retaining exact decoder state. They may take time for long files. Metadata is skipped; this API exposes audio shape, not tags. Files must remain unchanged while streaming. Loop restarts are asynchronous and can underrun.

Keep the returned FileStreamHandle on a control thread. Dropping the stream only requests cancellation; dropping the handle cancels and joins the worker. Construction, handle destruction and final stream destruction belong off the callback (the mixer’s returned-sound queue provides this for played sources).

Implementations

impl FileStream

pub fn open(path: impl AsRef<Path>) -> Result<(Self, FileStreamHandle)>

pub fn with_options( path: impl AsRef<Path>, options: &FileStreamOptions, ) -> Result<(Self, FileStreamHandle)>

pub fn sample_rate(&self) -> u32

pub fn channels(&self) -> usize

pub fn frames(&self) -> Option<u64>

pub fn format(&self) -> AudioFormat

pub fn position(&self) -> u64

Index of the next delivered source frame. A seek updates it immediately.

pub fn read(&mut self, out: &mut [f32]) -> Result<usize>

Drain available complete frames. Returns 0 only for actual EOF (or a buffer shorter than one frame). A partial read is returned before any pending/error state. Underrun means retry later; the destination is untouched on that error. Error messages are empty so all read paths, including errors, allocate nothing.

pub fn seek(&mut self, frame: u64) -> Result<()>

Queue a seek without waiting, allocating or touching the file. Old queued frames are discarded by generation. Next read can underrun while seeking.

pub fn rewind(&mut self) -> Result<()>

Trait Implementations

impl Drop for FileStream

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Stream for FileStream

Available on crate feature mixer only.

fn sample_rate(&self) -> u32

fn channels(&self) -> usize

1 or 2.

fn frames(&self) -> Option<u64>

The stream’s length in frames, if known.

fn read(&mut self, out: &mut [f32]) -> Result<usize>

Fills out with interleaved frames and returns how many; 0 at the end. ErrorCode::Underrun is temporary: the mixer emits silence and retries next render segment, preserving source position. Other errors fail the voice.

fn seek(&mut self, frame: u64) -> Result<()>

Moves to frame, for loops.