roomeq-model 0.5.5

RoomEQ configuration, pipeline, and DSP-chain contracts
Documentation
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// SPL calibration anchor captured from a pre-sweep reference tone.
///
/// Maps the peak sample value observed on the recording ADC during a
/// reference tone to a dBSPL reading taken by the user at the listening
/// position with an external meter. Once captured, the sweep playback
/// level is chosen so the in-band energy at the listening position hits
/// [`RecordingConfiguration::sweep_level_db_spl`](RecordingConfiguration::sweep_level_db_spl)
/// deterministically — avoiding the subwoofer driver over-excursion
/// that would otherwise contaminate bass phase with harmonic distortion.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
pub struct SplCalibration {
    /// User-reported dBSPL at the listening position during calibration.
    pub reported_db_spl: f32,
    /// Frequency of the calibration tone in Hz (default 1000).
    pub reference_freq_hz: f32,
    /// Peak sample value observed on the recording ADC during the tone,
    /// in the range `[0.0 .. 1.0]`.
    pub peak_sample_level: f32,
    /// Offset mapping ADC peak level to dBSPL at the mic:
    /// `dbspl_at_mic = 20 * log10(peak_sample_value) + spl_offset_db`.
    pub spl_offset_db: f32,
}

impl SplCalibration {
    /// Convenience: compute the expected dBSPL at the mic for a given
    /// peak sample value, using this calibration's offset.
    pub fn dbspl_for_peak_level(&self, peak_sample_value: f32) -> f32 {
        20.0 * peak_sample_value.max(f32::EPSILON).log10() + self.spl_offset_db
    }

    /// Convenience: compute the peak sample value required to hit a
    /// target dBSPL at the mic. Returns `0.0` if the target is below
    /// the representable range.
    pub fn peak_level_for_dbspl(&self, target_db_spl: f32) -> f32 {
        10.0f32
            .powf((target_db_spl - self.spl_offset_db) / 20.0)
            .clamp(0.0, 1.0)
    }
}