Struct AudioProcessing 

pub struct AudioProcessing { /* private fields */ }

Audio processing engine providing echo cancellation, noise suppression, automatic gain control, and other audio processing capabilities.

The engine operates on two audio streams on a frame-by-frame basis. Frames of the capture (near-end / microphone) stream, on which all processing is applied, are passed to process_capture_*. Frames of the render (far-end / playback) stream are passed to process_render_*. The engine should be placed in the signal chain as close to the audio hardware abstraction layer (HAL) as possible.

Frame size

All processing operates on ~10 ms chunks of linear PCM audio. Sample rates from 8 kHz to 384 kHz are accepted. The float interfaces use deinterleaved data (&[&[f32]] per channel, range [-1, 1]), while the i16 interfaces use interleaved data.

Thread safety

AudioProcessing is Send + Sync. However, for lowest overhead, the recommended usage pattern is:

• Call stream setters (set_stream_analog_level, set_stream_delay_ms) and process_capture_* from the same thread.
• Call apply_config from any thread, but never concurrently with config().

Usage

1. Create an instance via AudioProcessing::builder() or AudioProcessing::new().
2. For each audio frame (~10 ms):
   • Call process_render_f32() with the far-end (render/playback) audio.
   • Call process_capture_f32() with the near-end (capture/microphone) audio.
3. Apply configuration changes via apply_config().

Both f32 (deinterleaved) and i16 (interleaved) interfaces are provided.

Implementations

impl AudioProcessing

pub fn new() -> Self

Creates a new instance with default configuration (16 kHz mono).

pub fn builder() -> AudioProcessingBuilder

Returns a builder for constructing an instance with custom configuration.

pub fn apply_config(&mut self, config: Config)

Applies a new processing configuration at runtime.

Selectively reinitializes submodules as needed. May cause brief audio artifacts — prefer setting the initial config via the builder.

pub fn config(&self) -> &Config

Returns the current processing configuration.

pub fn initialize( &mut self, input: StreamConfig, output: StreamConfig, reverse_input: StreamConfig, reverse_output: StreamConfig, )

Reinitializes the processing pipeline with new stream configurations.

This sets all four stream configs (capture input/output, render input/output) at once and reinitializes internal state accordingly. Typically used by the FFI layer; Rust callers should prefer the builder or the _with_config processing method variants.

pub fn set_capture_pre_gain(&mut self, gain: f32)

Sets the capture pre-gain as a linear factor.

Applied at the next process_capture_* call.

pub fn set_capture_post_gain(&mut self, gain: f32)

Sets the capture post-gain as a linear factor.

Applied at the next process_capture_* call.

pub fn set_capture_fixed_post_gain(&mut self, gain_db: f32)

Sets the fixed post-gain in dB (range 0.0..=90.0).

Applied at the next process_capture_* call.

pub fn set_playout_volume(&mut self, volume: i32)

Notifies that the playout (render) volume has changed.

Applied at the next process_capture_* call.

pub fn set_playout_audio_device(&mut self, id: i32, max_volume: i32)

Notifies that the playout (render) audio device has changed.

Applied at the next process_render_* call.

pub fn set_capture_output_used(&mut self, used: bool)

Sets whether the capture output is being used.

When false, some components may optimize by skipping work. Applied at the next process_capture_* call.

pub fn statistics(&self) -> &AudioProcessingStats

Returns current processing statistics.

pub fn set_stream_analog_level(&mut self, level: i32)

Sets the applied input volume (e.g. from the OS mixer).

Must be called before process_capture_f32() if the input volume controller is enabled. Value must be in range [0, 255].

pub fn recommended_stream_analog_level(&self) -> i32

Returns the recommended analog level from AGC.

Should be called after process_capture_f32() to obtain the recommended new analog level for the audio HAL.

pub fn set_stream_delay_ms(&mut self, delay: i32) -> Result<(), Error>

Sets the delay in ms between render and capture.

This must be called if echo cancellation is enabled. On the client-side the delay can be expressed as:

delay = (t_render - t_analyze) + (t_process - t_capture)

where t_analyze is the time a frame is passed to process_render_*, t_render is the time its first sample is rendered by the audio hardware, t_capture is the time a frame’s first sample is captured, and t_process is the time it is passed to process_capture_*.

The delay is clamped to [0, 500]. Returns Err(StreamParameterClamped) if clamping was necessary (processing still proceeds).

pub fn stream_delay_ms(&self) -> i32

Returns the current stream delay in ms.

pub fn proc_sample_rate_hz(&self) -> usize

The internal capture processing sample rate.

pub fn process_capture_f32( &mut self, src: &[&[f32]], dest: &mut [&mut [f32]], ) -> Result<(), Error>

Processes a capture audio frame (float, deinterleaved).

Uses the stream config set via the builder. Each element of src / dest is one channel. Values in [-1.0, 1.0].

pub fn process_capture_f32_with_config( &mut self, src: &[&[f32]], input_config: &StreamConfig, output_config: &StreamConfig, dest: &mut [&mut [f32]], ) -> Result<(), Error>

Processes a capture audio frame with explicit per-call configs.

Use this when input and output formats differ (e.g. resampling).

pub fn process_render_f32( &mut self, src: &[&[f32]], dest: &mut [&mut [f32]], ) -> Result<(), Error>

Processes a render (far-end / playback) audio frame (float, deinterleaved).

Uses the stream config set via the builder.

pub fn process_render_f32_with_config( &mut self, src: &[&[f32]], input_config: &StreamConfig, output_config: &StreamConfig, dest: &mut [&mut [f32]], ) -> Result<(), Error>

Processes a render audio frame with explicit per-call configs.

pub fn process_capture_i16( &mut self, src: &[i16], dest: &mut [i16], ) -> Result<(), Error>

Processes a capture audio frame (int16, interleaved).

Uses the stream config set via the builder.

pub fn process_capture_i16_with_config( &mut self, src: &[i16], input_config: &StreamConfig, output_config: &StreamConfig, dest: &mut [i16], ) -> Result<(), Error>

Processes a capture audio frame (int16) with explicit per-call configs.

pub fn process_render_i16( &mut self, src: &[i16], dest: &mut [i16], ) -> Result<(), Error>

Processes a render (far-end / playback) audio frame (int16, interleaved).

Uses the stream config set via the builder.

pub fn process_render_i16_with_config( &mut self, src: &[i16], input_config: &StreamConfig, output_config: &StreamConfig, dest: &mut [i16], ) -> Result<(), Error>

Processes a render audio frame (int16) with explicit per-call configs.

Trait Implementations

impl Debug for AudioProcessing

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AudioProcessing

fn default() -> Self

Returns the “default value” for a type.