Struct AudioRenderer 

pub struct AudioRenderer { /* private fields */ }

Mixes a project’s audio tracks into one project-rate block.

Implementations

impl AudioRenderer

pub fn new( snapshot: &EngineProject, channels: usize, max_block: usize, ) -> Result<Self, EngineError>

Builds every track and master processor for a project snapshot. Clip processors are built when the clip is first mixed.

Errors

Returns EngineError::InvalidAudioConfiguration for an unsupported channel count, a zero sample rate, or an oversized block.

pub const fn sample_rate(&self) -> u32

Returns the project sample rate every block uses.

pub const fn channels(&self) -> usize

Returns the channel count of every mixed block.

pub fn track_ids(&self) -> Vec<&TrackId>

Returns the audio tracks this renderer mixes, in bus order.

pub const fn max_block(&self) -> usize

Returns the largest block this renderer accepts.

pub fn channel(&self, index: usize) -> &[f32]

Returns one mixed output channel from the most recent render.

pub fn required_lookahead_samples(&self) -> u32

How far ahead of a block, in samples, the renderer reads its sources.

The renderer reads each path’s input early by its latency to the output (for example a compressor’s lookahead_ms), so the output lines up with the timeline. Use Self::audio_needs for source supply, since a cold seek also needs settling history.

pub fn audio_needs( &self, snapshot: &EngineProject, start_sample: i64, frames: usize, ) -> Result<Vec<AudioNeed>, EngineError>

The source intervals rendering frames samples from start_sample reads, for a host to decode first.

These are exactly what Self::render would read, including any settling replay, so a host that holds them needs no margin. Overlapping or touching intervals of one source are merged; disjoint ones stay separate.

Errors

Returns EngineError::InvalidAudioConfiguration for a negative start, an empty or oversized block, or a span that does not fit in ticks, and an evaluation error when the snapshot cannot be evaluated over a block’s span.

pub const fn required_history_samples(&self) -> i64

Settling history replayed on discontinuities, in samples, excluding latency. At most MAX_SETTLING_SECONDS.

pub fn set_continuity(&mut self, continuity: AudioContinuity)

Sets the AudioContinuity policy (default AudioContinuity::Exact). Changing it resets the renderer.

pub const fn continuity(&self) -> AudioContinuity

The policy Self::set_continuity last chose.

pub fn reset(&mut self)

Clears every processor history without changing authored parameters.

Self::render resets on its own at discontinuities. Call this only to start fresh exactly where the last block ended, such as an export beginning where preview stopped.

pub fn render( &mut self, snapshot: &EngineProject, start_sample: i64, frames: usize, provider: &dyn AudioBlockProvider, transport: TransportState, ) -> Result<AudioRenderStatus, EngineError>

Mixes frames samples starting at an absolute project-rate sample index.

A block that does not continue the previous one (see AudioContinuity) first resets every processor and replays the settling history Self::audio_needs asks for, so its output matches a fresh renderer’s regardless of block size.

Recursive effects settle over a finite horizon (32 exponential time constants plus filter/feedback margins, capped at MAX_SETTLING_SECONDS), not bit-exactly. Each stage joins the replay only at its own horizon, so a long reverb on one track replays only that track.

Errors

Returns EngineError::InvalidAudioConfiguration for a negative start, an oversized block, or a span that does not fit in ticks, and an evaluation error when the snapshot cannot be evaluated over the block’s span.

pub fn set_normalization_gain_db( &mut self, gain_db: f64, ) -> Result<(), EngineError>

Sets the loudness normalization gain in dB, applied between the master gain and the limiter. Zero removes it, as does Self::set_loudness_metering.

Errors

Returns EngineError::InvalidNormalizationGain for a non-finite gain or one whose linear factor is not a normal f32 (beyond about 760 dB either way).

pub const fn set_hold_incomplete_blocks(&mut self, hold: bool)

Whether a block missing a source is held: output as silence with nothing advanced, so rendering it again after the host supplies the source matches an uninterrupted render. Off by default (live playback); exports turn it on.

pub fn set_loudness_metering( &mut self, enabled: bool, ) -> Result<(), EngineError>

Starts (or restarts from empty) measuring the loudness of what reaches the limiter; false stops. Only complete requested blocks are measured, never replayed history.

Starting removes the normalization gain (Self::set_normalization_gain_db) so the authored mix is measured; a gain set afterwards is included.

Errors

Returns EngineError::InvalidAudioConfiguration for an unsupported layout or rate.

pub fn loudness_report(&self) -> Option<LoudnessReport>

What the meter has measured, if metering is on.

pub fn limiter_threshold(&self) -> Option<f64>

The master limiter’s linear threshold, if any. Pass it to alpha2_audio::LoudnessNormalization::plan so the planned gain stops short of the limiter.

pub fn set_output_loudness_metering( &mut self, enabled: bool, ) -> Result<(), EngineError>

Starts (or restarts from empty) measuring the loudness of the final output, after the limiter and normalization gain; false stops. Unlike Self::set_loudness_metering it leaves the gain unchanged.

Errors

Returns EngineError::InvalidAudioConfiguration for an unsupported layout or rate.

pub fn output_loudness_report(&self) -> Option<LoudnessReport>

What the output meter has measured, if output metering is on.

pub fn block(&self, status: &AudioRenderStatus) -> AudioBlock

Copies the most recent render into an owned block for offline sinks.