Struct PcmSession

pub struct PcmSession { /* private fields */ }

A continuous output processor for successive naturally ending tracks.

Input PCM has already been decoded and optionally downmixed. Compatible tracks share the converter, fractional frame accounting and tone-filter state. Gain is selected separately for each track after rate conversion. Output frame boundaries are ceil(cumulative source frames × rate ratio). A discontinuity, format or tone change requires a new session.

Call end_track only after the source was completely decoded, then start the next compatible track or call finish once at the end of the group. Returned views remain valid until the next mutable session call. Incomplete frames, non-finite input and lifecycle requests leave state unchanged; after a processing, conversion or timeline failure, the driver must discard the session rather than retrying partially consumed PCM.

Implementations

impl PcmSession

pub fn new( input: PcmFormat, output_rate: u32, tone: ToneControls, ) -> Result<Self, SessionError>

Prepare a fixed PCM format, optional rate conversion and persistent tone shelves outside the output callback.

pub fn input_format(&self) -> PcmFormat

Source PCM format after any downmix and before rate conversion.

pub fn output_format(&self) -> PcmFormat

Guarded PCM format accepted by the output sink.

pub fn compatible( &self, input: PcmFormat, output_rate: u32, tone: ToneControls, ) -> bool

Whether the next naturally advancing track can share this unfinished processing session. Channel positions are part of compatibility.

pub fn begin_track( &mut self, token: usize, gain_db: f32, ) -> Result<(), SessionError>

Start a new source track using a fixed final gain in dB. The driver includes any normalization and tone headroom reserve in this gain. Pending output from earlier tracks retains their own gains.

pub fn push_source( &mut self, samples: &[f32], ) -> Result<SessionBlock<'_>, SessionError>

Supply complete finite source frames. A converter may retain source frames and return no output until more PCM arrives or the group ends.

pub fn end_track(&mut self) -> Result<SessionBlock<'_>, SessionError>

Seal the active track’s source boundary without flushing the converter or resetting filters. Completion is emitted only once every output frame assigned to this track has been produced.

pub fn finish(&mut self) -> Result<SessionBlock<'_>, SessionError>

Flush the converter once after every source track has been sealed. Repeated calls return an empty block without duplicate completions.