Crate math_audio_iir_fir

Expand description

IIR and FIR filter library for audio processing.

This crate provides digital filter implementations for audio signal processing, including biquad IIR filters, FIR filters, SVF filters, and crossovers.

§Generic precision

All filter types are generic over FilterFloat (f32 or f64), defaulting to f64 for backward compatibility. Use f32 when throughput matters more than precision (e.g., real-time processing of many channels). Convenience aliases like BiquadF32, SvfFilterF32, etc. are provided.

§Features

Biquad IIR filters: Peak, Lowpass, Highpass, Lowshelf, Highshelf, Bandpass, Notch
SVF filters: Zero-delay feedback topology for artifact-free parameter changes
FIR filters: Windowed sinc filters with various window types
Crossovers: Linkwitz-Riley IIR and linear-phase FIR crossovers
Offline filtering: Zero-phase filtfilt for analysis (no phase distortion)
Frequency response computation: For both IIR and FIR filters
Multiple output formats: APO, RME, AU Preset

§Example

use math_audio_iir_fir::{Biquad, BiquadFilterType};

// f64 (default)
let filter = Biquad::new(BiquadFilterType::Peak, 1000.0, 48000.0, 2.0, 3.0);
let response_db: f64 = filter.log_result(1000.0);
assert!((response_db - 3.0_f64).abs() < 0.1);

// f32 — same API, lower precision, higher throughput
let filter_f32 = Biquad::<f32>::new(BiquadFilterType::Peak, 1000.0, 48000.0, 2.0, 3.0);
let response_f32: f32 = filter_f32.log_result(1000.0);
assert!((response_f32 - 3.0_f32).abs() < 0.5);

§math-iir-fir (lib: `math_audio_iir_fir`)

IIR, FIR, and SVF filter implementations for audio processing, generic over f32 and f64.

Version: 0.5.13

§Generic precision

All filter types (Biquad, SvfFilter, Fir, BiquadBank) are generic over FilterFloat and default to f64. Use f32 when throughput matters more than precision (e.g., real-time multi-channel processing). Convenience aliases like BiquadF32, SvfFilterF32, etc. are provided.

§Features

Biquad Filters: Peak, Lowpass, Highpass, Lowshelf, Highshelf, Bandpass, Notch, AllPass
SVF (State Variable Filter): Zero-delay feedback topology (Zavalishin TPT) for artifact-free parameter changes
FIR Filters: Windowed sinc filter bank for linear-phase filtering, FIR design from frequency response, Kirkeby correction, pre-ringing suppression
Crossovers: Linkwitz-Riley 4th-order IIR and linear-phase FIR crossovers
Offline filtering: Zero-phase filtfilt and sosfilt for analysis
PEQ (Parametric Equalizer): Multi-band parametric equalization with SPL response computation, loudness compensation, and 9 export formats (APO, RME, AU Preset, CamillaDSP, EasyEffects, PipeWire, Roon, Wavelet)
Filter Design: Butterworth and Linkwitz-Riley lowpass/highpass
Phase Smoothing: Phase unwrapping, smoothing via group delay, complex interpolation
Warped LPC and Kautz filters: Advanced filter design for room acoustics

§Filter Types

§Biquad Filter Types

BiquadFilterType::Lowpass
BiquadFilterType::Highpass
BiquadFilterType::HighpassVariableQ
BiquadFilterType::Bandpass
BiquadFilterType::Peak
BiquadFilterType::Notch
BiquadFilterType::Lowshelf
BiquadFilterType::Highshelf

§Usage Examples

§Basic Biquad Filter

use math_audio_iir_fir::{Biquad, BiquadFilterType};

// f64 (default)
let filter = Biquad::new(
    BiquadFilterType::Peak,
    1000.0,  // frequency
    48000.0, // sample rate
    1.0,     // Q factor
    3.0      // gain in dB
);
let response_db = filter.log_result(1000.0);

// f32 — same API, less precision, higher throughput
let mut filter_f32 = Biquad::<f32>::new(BiquadFilterType::Peak, 1000.0, 48000.0, 1.0, 3.0);
let output = filter_f32.process(0.5f32);

§Parametric EQ (PEQ)

use math_audio_iir_fir::{Biquad, BiquadFilterType, Peq, peq_spl, peq_preamp_gain, peq_format_apo};
use ndarray::Array1;

let mut peq: Peq = Vec::new();

let hp = Biquad::new(BiquadFilterType::Highpass, 80.0, 48000.0, 0.707, 0.0);
peq.push((1.0, hp));

let peak = Biquad::new(BiquadFilterType::Peak, 1000.0, 48000.0, 1.5, 4.0);
peq.push((1.0, peak));

let hs = Biquad::new(BiquadFilterType::Highshelf, 8000.0, 48000.0, 0.8, -2.0);
peq.push((1.0, hs));

let freqs = Array1::logspace(10.0, 20.0_f64.log10(), 20000.0_f64.log10(), 1000);
let response = peq_spl(&freqs, &peq);
let preamp = peq_preamp_gain(&peq);

let apo_config = peq_format_apo("My Custom EQ", &peq);

§Filter Design

use math_audio_iir_fir::{peq_butterworth_lowpass, peq_linkwitzriley_highpass};

let lp_filter = peq_butterworth_lowpass(4, 2000.0, 48000.0);
let hp_filter = peq_linkwitzriley_highpass(4, 2000.0, 48000.0);

§Key Types

Peq<T> — Vec<(T, Biquad<T>)> where the first element is the weight/amplitude multiplier
BiquadBank<T> — Pack 2 or 4 biquad operations per clock depending on hardware
SvfFilter<T> — Zero-delay feedback state variable filter
Fir<T> / FirCrossover — Linear-phase FIR filtering

§Dependencies

ndarray, num-traits — Numerical arrays
rustfft, num-complex — FFT for FIR design
serde — Serialization
hound — WAV I/O for filter testing

§Testing

cargo test -p math-iir-fir --lib
cargo check -p math-iir-fir && cargo clippy -p math-iir-fir

§License

See the root workspace LICENSE file.

Re-exports§

pub use svf::SvfFilter;
pub use svf::SvfFilterType;
pub use fir_crossover::DEFAULT_FIR_CROSSOVER_TAPS;
pub use fir_crossover::FirCrossover;
pub use fir_crossover::MultibandFirCrossover;
pub use lr4_crossover::CROSSOVER_PRESETS;
pub use lr4_crossover::Lr4Crossover;
pub use lr4_crossover::MultibandLr4Crossover;
pub use lr8_crossover::Lr8Crossover;
pub use lr8_crossover::MultibandLr8Crossover;

Modules§

denormals: Utilities for handling floating-point denormals (subnormals).
filtfilt: Forward-reverse (zero-phase) filtering for offline signal processing. Forward-reverse (zero-phase) filtering for offline signal processing.
fir_crossover: Linear-phase FIR crossover (windowed sinc).
lr4_crossover: Linkwitz-Riley 4th-order IIR crossover.
lr8_crossover: Linkwitz-Riley 8th-order IIR crossover (48 dB/octave).
svf: Zero-Delay Feedback State Variable Filter (Zavalishin TPT topology). Zero-Delay Feedback State Variable Filter (ZDF/SVF)

Structs§

Biquad: Represents a single biquad IIR filter.
BiquadBank: A bank of biquad filters sharing coefficients but with independent per-channel state.
BiquadCoefficients: Biquad filter coefficients for external interpolation.
FilterRow: Represents a single filter in a parametric equalizer.
Fir: Represents a single FIR filter.
FirDesignConfig: Configuration for FIR filter generation
KautzFilter: Complete Kautz filter: parallel bank of KautzSections.
KautzSection: A second-order Kautz section with pole tuned to a specific frequency.
PreRingingAnalysis: Analysis results for pre-ringing in an FIR filter.
PreRingingConfig: Configuration for pre-ringing suppression on FIR filters.
WarpedBiquad: Warped biquad IIR filter.

Enums§

BiquadFilterType: Filter types for biquad filters
FirFilterType: FIR filter types
FirPhase: Phase type for FIR generation
IirError: Errors that can occur during IIR filter operations.
WindowType: Window function types for FIR filter design

Constants§

AUDIBLE_MAX_FREQ: Upper bound of human hearing (Hz).
AUDIBLE_MIN_FREQ: Lower bound of human hearing (Hz).
DEFAULT_Q_HIGH_LOW_PASS: Default Q factor for high/low pass filters
DEFAULT_Q_HIGH_LOW_SHELF: Default Q factor for high/low shelf filters

Traits§

FilterFloat: Trait bound for the numeric type used throughout the filter crate.

Functions§

analyze_pre_ringing: Analyze pre-ringing in an FIR impulse response.
bark_lambda: Compute the Bark-scale warping coefficient for a given sample rate.
bw2q: Converts bandwidth in octaves to a Q factor.
compute_fir_bank_response: Compute the combined FIR bank response (in dB) on a given frequency grid.
compute_peq_response: Compute the combined PEQ response (in dB) on a given frequency grid for a Peq.
fir_bank_preamp_gain: Calculate the recommended preamp gain to avoid clipping for a FIR bank.
fir_bank_spl: Compute the FIR bank SPL response at given frequencies.
generate_fir_from_response: Generate an FIR filter to match a target frequency response
generate_kirkeby_correction: Generate Kirkeby regularized FIR correction filter
generate_window: Generates a window function for FIR filter design.
interpolate_phase_complex: Interpolate phase in the complex domain to avoid wrap artifacts
peq_allpass: Create All-Pass filter
peq_butterworth_highpass: Create Butterworth highpass filter
peq_butterworth_lowpass: Create Butterworth lowpass filter
peq_butterworth_q: Compute Q values for Butterworth filters
peq_equal: Check if two PEQs are equal
peq_format_apo: Format PEQ as APO configuration string
peq_format_aupreset: Format PEQ as Apple AUNBandEQ preset (aupreset) plist XML
peq_format_camilladsp: Format a PEQ as a CamillaDSP YAML configuration.
peq_format_easyeffects: Format a PEQ as an EasyEffects JSON preset.
peq_format_pipewire: Format a PEQ as a PipeWire filter-chain SPA-JSON configuration.
peq_format_rme_channel: Format PEQ as RME TotalMix channel preset XML
peq_format_rme_room: Format PEQ as RME TotalMix room EQ preset XML (dual channel)
peq_format_roon: Format a PEQ as a Roon DSP parametric EQ preset (JSON).
peq_format_wavelet: Format a PEQ as a Wavelet GraphicEQ string.
peq_linkwitzriley_highpass: Create Linkwitz-Riley highpass filter
peq_linkwitzriley_lowpass: Create Linkwitz-Riley lowpass filter
peq_linkwitzriley_q: Compute Q values for Linkwitz-Riley filters
peq_loudness_gain: Compute loudness-weighted gain adjustment for PEQ to maintain spectral balance
peq_preamp_gain: Compute preamp gain for a PEQ: well adapted to computers
peq_preamp_gain_max: Compute preamp gain for a PEQ and look at the worst case
peq_print: Print a formatted table of the parametric EQ filters from a Peq.
peq_spl: Compute SPL for each frequency given a PEQ
q2bw: Converts a Q factor to bandwidth in octaves.
save_fir_to_wav: Save FIR coefficients to a WAV file (32-bit float mono)
smooth_phase_via_group_delay: Smooth phase via group delay smoothing
suppress_pre_ringing: Suppress pre-ringing in an FIR impulse response.
unwarp_frequency: Map a warped frequency back to the physical frequency domain.
unwrap_phase: Unwrap phase by removing 2π discontinuities
warp_frequency: Map a physical frequency to the warped frequency domain.

Type Aliases§

BiquadBankF32: 32-bit biquad bank.
BiquadCoefficientsF32: 32-bit biquad coefficients.
BiquadF32: 32-bit biquad filter.
FirBank: Type alias for a collection of weighted FIR filters
FirBankF32: 32-bit FIR filter bank.
FirCrossoverF32: 32-bit FIR crossover.
FirF32: 32-bit FIR filter.
Lr4CrossoverF32: 32-bit LR4 crossover.
Lr8CrossoverF32: 32-bit LR8 crossover.
MultibandFirCrossoverF32: 32-bit multiband FIR crossover.
MultibandLr4CrossoverF32: 32-bit multiband LR4 crossover.
MultibandLr8CrossoverF32: 32-bit multiband LR8 crossover.
Peq: Parametric EQ filter chain: a vector of (gain, Biquad) pairs.
PeqF32: 32-bit parametric EQ chain.
Result: A specialized Result type for IIR operations.
SvfFilterF32: 32-bit SVF filter.