Skip to main content

autoeq_fir/
lib.rs

1//! FIR filter design and optimization
2//!
3//! Provides functionality to generate FIR filters matching a target frequency response,
4//! with support for linear and minimum phase.
5//!
6//! This module wraps the core FIR design functions from `math_audio_iir_fir` and adds
7//! convenience wrappers that work with the `Curve` type.
8
9use autoeq_core::Curve;
10use std::path::Path;
11
12// Re-export core types from math-iir-fir
13pub use math_audio_iir_fir::{
14    FirDesignConfig, FirPhase, WindowType,
15    generate_kirkeby_correction as generate_kirkeby_correction_raw, save_fir_to_wav,
16};
17
18/// Generate an FIR filter to match a target frequency response
19///
20/// This helper supports generic target matching for `FirPhase::Linear` and
21/// `FirPhase::Minimum`. Use `generate_kirkeby_correction*` for Kirkeby
22/// regularized inversion, which requires both a measurement and a target.
23///
24/// # Arguments
25/// * `target_curve` - The target frequency response (magnitude only needed)
26/// * `sample_rate` - Sample rate in Hz
27/// * `n_taps` - Number of taps (coefficients) for the FIR filter
28/// * `phase_type` - Desired phase characteristic
29///
30/// # Returns
31/// * Vector of FIR coefficients
32pub fn generate_fir_from_response(
33    target_curve: &Curve,
34    sample_rate: f64,
35    n_taps: usize,
36    phase_type: FirPhase,
37) -> Vec<f64> {
38    let config = FirDesignConfig {
39        n_taps,
40        sample_rate,
41        phase: phase_type,
42        // A causal minimum-phase impulse begins at tap zero. Symmetric windows
43        // also begin at zero, which erases that leading energy and destroys
44        // the minimum-phase result. Truncation is sufficient here.
45        window: if phase_type == FirPhase::Minimum {
46            WindowType::Rectangular
47        } else {
48            FirDesignConfig::default().window
49        },
50        ..Default::default()
51    };
52
53    // Convert Curve to raw arrays
54    let freqs: Vec<f64> = target_curve.freq.to_vec();
55    let magnitude_db: Vec<f64> = target_curve.spl.to_vec();
56
57    math_audio_iir_fir::generate_fir_from_response(&freqs, &magnitude_db, &config)
58}
59
60/// Generate Kirkeby regularized FIR correction filter from Curve
61///
62/// # Arguments
63/// * `measurement` - Measurement curve (SPL and optionally phase)
64/// * `target` - Target curve (SPL)
65/// * `sample_rate` - Sample rate in Hz
66/// * `n_taps` - Number of taps
67/// * `min_freq` - Minimum frequency for in-band regularization
68/// * `max_freq` - Maximum frequency for in-band regularization
69///
70/// # Returns
71/// * Vector of FIR coefficients
72pub fn generate_kirkeby_correction(
73    measurement: &Curve,
74    target: &Curve,
75    sample_rate: f64,
76    n_taps: usize,
77    min_freq: f64,
78    max_freq: f64,
79) -> Vec<f64> {
80    generate_kirkeby_correction_with_phase(
81        measurement,
82        target,
83        sample_rate,
84        n_taps,
85        min_freq,
86        max_freq,
87        false, // Default: magnitude-only correction
88    )
89}
90
91/// Generate Kirkeby regularized FIR correction filter with optional excess phase correction
92///
93/// # Arguments
94/// * `measurement` - Measurement curve (SPL and optionally phase)
95/// * `target` - Target curve (SPL)
96/// * `sample_rate` - Sample rate in Hz
97/// * `n_taps` - Number of taps
98/// * `min_freq` - Minimum frequency for in-band regularization
99/// * `max_freq` - Maximum frequency for in-band regularization
100/// * `correct_excess_phase` - Whether to correct excess phase (requires phase data in measurement)
101///
102/// # Returns
103/// * Vector of FIR coefficients
104pub fn generate_kirkeby_correction_with_phase(
105    measurement: &Curve,
106    target: &Curve,
107    sample_rate: f64,
108    n_taps: usize,
109    min_freq: f64,
110    max_freq: f64,
111    correct_excess_phase: bool,
112) -> Vec<f64> {
113    generate_kirkeby_correction_with_smoothing(
114        measurement,
115        target,
116        sample_rate,
117        n_taps,
118        min_freq,
119        max_freq,
120        correct_excess_phase,
121        0.167, // Default 1/6 octave smoothing
122    )
123}
124
125/// Generate Kirkeby regularized FIR correction filter with optional excess phase correction and smoothing
126///
127/// # Arguments
128/// * `measurement` - Measurement curve (SPL and optionally phase)
129/// * `target` - Target curve (SPL)
130/// * `sample_rate` - Sample rate in Hz
131/// * `n_taps` - Number of taps
132/// * `min_freq` - Minimum frequency for in-band regularization
133/// * `max_freq` - Maximum frequency for in-band regularization
134/// * `correct_excess_phase` - Whether to correct excess phase (requires phase data in measurement)
135/// * `phase_smoothing_octaves` - Phase smoothing width in octaves (0.0 to disable)
136///
137/// # Returns
138/// * Vector of FIR coefficients
139#[allow(clippy::too_many_arguments)]
140pub fn generate_kirkeby_correction_with_smoothing(
141    measurement: &Curve,
142    target: &Curve,
143    sample_rate: f64,
144    n_taps: usize,
145    min_freq: f64,
146    max_freq: f64,
147    correct_excess_phase: bool,
148    phase_smoothing_octaves: f64,
149) -> Vec<f64> {
150    let config = FirDesignConfig {
151        n_taps,
152        sample_rate,
153        phase: FirPhase::Kirkeby,
154        min_freq,
155        max_freq,
156        correct_excess_phase,
157        phase_smoothing_octaves,
158        ..Default::default()
159    };
160
161    let meas_freqs: Vec<f64> = measurement.freq.to_vec();
162    let meas_db: Vec<f64> = measurement.spl.to_vec();
163    let meas_phase: Option<Vec<f64>> = measurement.phase.as_ref().map(|p| p.to_vec());
164
165    // Interpolate target onto the measurement grid when needed
166    let target_db = resolve_target_db_on_measurement_grid(measurement.freq.clone(), target);
167
168    generate_kirkeby_correction_raw(
169        &meas_freqs,
170        &meas_db,
171        meas_phase.as_deref(),
172        &target_db,
173        &config,
174    )
175}
176
177/// Resolve target SPL values onto the measurement frequency grid.
178///
179/// Grids are compared element-wise (with tolerance): equal lengths alone do
180/// not imply the same grid, and index-aligned copying of a mismatched target
181/// would place corrections at the wrong frequencies.
182pub fn resolve_target_db_on_measurement_grid(
183    measurement_freq: ndarray::Array1<f64>,
184    target: &Curve,
185) -> Vec<f64> {
186    const GRID_TOLERANCE_HZ: f64 = 1e-6;
187    let same_grid = target.freq.len() == measurement_freq.len()
188        && target.freq.iter().zip(measurement_freq.iter()).all(
189            |(&target_frequency, &measurement_frequency)| {
190                (target_frequency - measurement_frequency).abs()
191                    <= GRID_TOLERANCE_HZ * measurement_frequency.max(1.0)
192            },
193        );
194    if same_grid {
195        return target.spl.to_vec();
196    }
197    autoeq_core::interpolate(&measurement_freq, target)
198        .spl
199        .to_vec()
200}
201
202/// Save FIR coefficients to a WAV file (32-bit float mono)
203///
204/// Convenience wrapper that takes a Path reference.
205pub fn save_fir_wav(
206    coeffs: &[f64],
207    sample_rate: u32,
208    path: &Path,
209) -> Result<(), Box<dyn std::error::Error>> {
210    save_fir_to_wav(coeffs, sample_rate, path)
211}
212
213#[cfg(test)]
214mod tests {
215    use super::*;
216    use ndarray::Array1;
217    use tempfile::TempDir;
218
219    /// Helper to create a test curve with given frequencies and SPL values
220    fn create_test_curve(freqs: &[f64], spl_values: &[f64]) -> Curve {
221        Curve {
222            freq: Array1::from(freqs.to_vec()),
223            spl: Array1::from(spl_values.to_vec()),
224            phase: None,
225            ..Default::default()
226        }
227    }
228
229    /// Create a flat response curve at given SPL level
230    fn create_flat_curve(min_freq: f64, max_freq: f64, n_points: usize, spl_db: f64) -> Curve {
231        let freqs: Vec<f64> = (0..n_points)
232            .map(|i| {
233                let t = i as f64 / (n_points - 1) as f64;
234                min_freq * (max_freq / min_freq).powf(t)
235            })
236            .collect();
237        let spl: Vec<f64> = vec![spl_db; n_points];
238        create_test_curve(&freqs, &spl)
239    }
240
241    /// Compute energy in a specific portion of the signal
242    fn compute_energy_in_range(coeffs: &[f64], start_fraction: f64, end_fraction: f64) -> f64 {
243        let n = coeffs.len();
244        let start = (n as f64 * start_fraction) as usize;
245        let end = (n as f64 * end_fraction) as usize;
246        coeffs[start..end].iter().map(|x| x * x).sum()
247    }
248
249    #[test]
250    fn equal_length_but_different_grids_are_interpolated_not_index_aligned() {
251        // Same point count, different frequency axes: index-aligned copying
252        // would place target values at the wrong frequencies.
253        let meas_freqs = [20.0, 100.0, 1000.0, 10_000.0, 20_000.0];
254        let meas_curve = create_test_curve(&meas_freqs, &[80.0; 5]);
255        let target_freqs = [25.0, 150.0, 1500.0, 15_000.0, 19_000.0];
256        let mut target = create_test_curve(&target_freqs, &[80.0; 5]);
257        target.spl[2] = 92.0; // +12 dB bump at its own 1500 Hz point
258
259        let resolved =
260            resolve_target_db_on_measurement_grid(Array1::from(meas_freqs.to_vec()), &target);
261
262        assert_eq!(resolved.len(), 5);
263        // At measurement 1000 Hz the bump must be interpolated from the
264        // target's surrounding points (150/1500 Hz), not copied verbatim.
265        assert!(
266            resolved[2] < 90.0,
267            "index-aligned copy would yield 92.0 at 1000 Hz, got {}",
268            resolved[2]
269        );
270        assert!(
271            resolved[2] > 82.0,
272            "interpolation should retain part of the nearby bump, got {}",
273            resolved[2]
274        );
275        // Away from the bump, values stay near the flat level.
276        assert!((resolved[0] - 80.0).abs() < 1e-9);
277    }
278
279    #[test]
280    fn identical_grids_copy_target_values_directly() {
281        let freqs = [20.0, 100.0, 1000.0];
282        let target = create_test_curve(&freqs, &[81.0, 82.0, 83.0]);
283
284        let resolved = resolve_target_db_on_measurement_grid(Array1::from(freqs.to_vec()), &target);
285
286        assert_eq!(resolved, vec![81.0, 82.0, 83.0]);
287    }
288
289    #[test]
290    fn test_linear_phase_impulse_symmetry() {
291        let sample_rate = 48000.0;
292        let n_taps = 512;
293
294        let target_curve = create_test_curve(
295            &[20.0, 100.0, 1000.0, 5000.0, 20000.0],
296            &[0.0, 2.0, 0.0, -1.0, -2.0],
297        );
298
299        let coeffs =
300            generate_fir_from_response(&target_curve, sample_rate, n_taps, FirPhase::Linear);
301
302        assert_eq!(coeffs.len(), n_taps);
303
304        // Check that the energy is centered
305        let (max_idx, _) = coeffs
306            .iter()
307            .enumerate()
308            .max_by(|a, b| a.1.abs().partial_cmp(&b.1.abs()).unwrap())
309            .unwrap();
310
311        let center = n_taps / 2;
312        let tolerance = n_taps / 10;
313        assert!(
314            (max_idx as isize - center as isize).unsigned_abs() < tolerance,
315            "Linear phase FIR peak should be near center. Peak at {}, center at {}",
316            max_idx,
317            center
318        );
319    }
320
321    #[test]
322    fn test_minimum_phase_energy_concentration() {
323        let sample_rate = 48000.0;
324        let n_taps = 1024;
325
326        let target_curve = create_test_curve(
327            &[20.0, 100.0, 500.0, 1000.0, 5000.0, 20000.0],
328            &[-3.0, 0.0, 2.0, 0.0, -2.0, -5.0],
329        );
330
331        let coeffs =
332            generate_fir_from_response(&target_curve, sample_rate, n_taps, FirPhase::Minimum);
333
334        assert_eq!(coeffs.len(), n_taps);
335
336        // For minimum phase, first half should have more energy than second half
337        // (windowing affects the exact distribution)
338        let first_half_energy = compute_energy_in_range(&coeffs, 0.0, 0.5);
339        let second_half_energy = compute_energy_in_range(&coeffs, 0.5, 1.0);
340
341        assert!(
342            first_half_energy > second_half_energy,
343            "Minimum phase should have more energy in first half: first={:.4}, second={:.4}",
344            first_half_energy,
345            second_half_energy
346        );
347    }
348
349    #[test]
350    fn test_minimum_phase_flat_target_keeps_impulse_at_start() {
351        let target_curve = create_flat_curve(20.0, 20_000.0, 100, 0.0);
352        let coeffs = generate_fir_from_response(&target_curve, 48_000.0, 256, FirPhase::Minimum);
353
354        assert!(
355            (coeffs[0] - 1.0).abs() < 1e-6,
356            "minimum-phase flat response should start with a unit impulse, got {}",
357            coeffs[0]
358        );
359        let tail_energy: f64 = coeffs[1..].iter().map(|value| value * value).sum();
360        assert!(tail_energy < 1e-12, "unexpected tail energy: {tail_energy}");
361    }
362
363    #[test]
364    fn test_flat_target_produces_near_impulse() {
365        let sample_rate = 48000.0;
366        let n_taps = 256;
367
368        let target_curve = create_flat_curve(20.0, 20000.0, 100, 0.0);
369
370        let coeffs =
371            generate_fir_from_response(&target_curve, sample_rate, n_taps, FirPhase::Linear);
372
373        assert_eq!(coeffs.len(), n_taps);
374
375        let (max_idx, max_val) = coeffs
376            .iter()
377            .enumerate()
378            .max_by(|a, b| a.1.abs().partial_cmp(&b.1.abs()).unwrap())
379            .unwrap();
380
381        let center = n_taps / 2;
382        assert!(
383            (max_idx as isize - center as isize).abs() < 10,
384            "Peak should be near center for linear phase"
385        );
386
387        assert!(*max_val > 0.0, "Peak coefficient should be positive");
388    }
389
390    #[test]
391    fn test_save_fir_to_wav_creates_valid_file() {
392        let temp_dir = TempDir::new().expect("Failed to create temp dir");
393        let wav_path = temp_dir.path().join("test_fir.wav");
394
395        let coeffs: Vec<f64> = (0..256).map(|i| (i as f64 * 0.01).sin()).collect();
396
397        let result = save_fir_wav(&coeffs, 48000, &wav_path);
398        assert!(result.is_ok(), "save_fir_wav should succeed");
399        assert!(wav_path.exists(), "WAV file should be created");
400
401        let reader = hound::WavReader::open(&wav_path).expect("Should open WAV file");
402        let spec = reader.spec();
403
404        assert_eq!(spec.channels, 1);
405        assert_eq!(spec.sample_rate, 48000);
406        assert_eq!(spec.bits_per_sample, 32);
407        assert_eq!(reader.len() as usize, coeffs.len());
408    }
409
410    #[test]
411    fn test_fir_phase_types_differ() {
412        let sample_rate = 48000.0;
413        let n_taps = 512;
414
415        let target_curve = create_test_curve(
416            &[20.0, 100.0, 1000.0, 10000.0, 20000.0],
417            &[0.0, 3.0, 0.0, -3.0, -6.0],
418        );
419
420        let linear_coeffs =
421            generate_fir_from_response(&target_curve, sample_rate, n_taps, FirPhase::Linear);
422        let minimum_coeffs =
423            generate_fir_from_response(&target_curve, sample_rate, n_taps, FirPhase::Minimum);
424
425        assert_eq!(linear_coeffs.len(), minimum_coeffs.len());
426
427        let sum_diff: f64 = linear_coeffs
428            .iter()
429            .zip(minimum_coeffs.iter())
430            .map(|(a, b)| (a - b).abs())
431            .sum();
432
433        assert!(
434            sum_diff > 0.1,
435            "Linear and minimum phase should produce different coefficients"
436        );
437    }
438
439    #[test]
440    fn test_kirkeby_correction() {
441        let measurement = create_test_curve(
442            &[20.0, 100.0, 500.0, 1000.0, 5000.0, 20000.0],
443            &[75.0, 82.0, 80.0, 78.0, 72.0, 65.0],
444        );
445        let target = create_test_curve(
446            &[20.0, 100.0, 500.0, 1000.0, 5000.0, 20000.0],
447            &[80.0, 80.0, 80.0, 80.0, 80.0, 80.0],
448        );
449
450        let coeffs =
451            generate_kirkeby_correction(&measurement, &target, 48000.0, 4096, 20.0, 1000.0);
452
453        assert_eq!(coeffs.len(), 4096);
454        assert!(coeffs.iter().any(|&x| x.abs() > 1e-10));
455    }
456}