roomeq-model 0.5.5

RoomEQ configuration, pipeline, and DSP-chain contracts
Documentation
//! Neutral, serializable optimizer settings owned by the RoomEQ contract.
//!
//! Runtime adapters into concrete optimizer and measurement types live in
//! `roomeq-engine`; this module must remain backend- and I/O-independent.

use schemars::JsonSchema;
use serde::{Deserialize, Serialize};

/// Psychoacoustic variable smoothing configuration
///
/// Different frequency ranges benefit from different smoothing levels:
/// - Low frequencies (< 100 Hz): Fine resolution (1/48 octave) to preserve room modes
/// - High frequencies (> 1 kHz): Coarse resolution (1/6 octave) to ignore comb filtering
/// - Transition region (100 Hz - 1 kHz): Gradual interpolation between the two
#[derive(Debug, Clone, Copy, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(default)]
pub struct PsychoacousticSmoothingConfig {
    /// Smoothing resolution below low_freq (bands per octave, e.g., 48 for 1/48 octave)
    pub low_freq_n: usize,
    /// Smoothing resolution above high_freq (bands per octave, e.g., 6 for 1/6 octave)
    pub high_freq_n: usize,
    /// Lower transition frequency in Hz (default: 100 Hz)
    pub low_freq: f64,
    /// Upper transition frequency in Hz (default: 1000 Hz)
    pub high_freq: f64,
}

impl Default for PsychoacousticSmoothingConfig {
    fn default() -> Self {
        Self {
            low_freq_n: 48,
            high_freq_n: 6,
            low_freq: 100.0,
            high_freq: 1_000.0,
        }
    }
}

/// Configuration for asymmetric loss weighting.
///
/// Weights apply per sample as a multiplier on the squared error. The
/// peak / dip split uses a sigmoid crossfade in log frequency around
/// `transition_freq` so the transition from bass weighting to mid/treble
/// weighting is smooth. Narrow-null suppression is a separate mask passed
/// to the loss function at call time (see
/// [`crate::roomeq::impulse_analysis::build_null_suppression_mask`]).
#[derive(Debug, Clone, Copy, Serialize, Deserialize, JsonSchema, PartialEq)]
#[serde(default)]
pub struct AsymmetricLossConfig {
    /// Weight for positive errors (peaks above `transition_freq`). Default: 2.0
    pub peak_weight: f64,
    /// Weight for negative errors (dips above `transition_freq`). Default: 1.0
    pub dip_weight: f64,
    /// Weight for bass peaks (below `transition_freq`). Default: 5.0
    pub bass_peak_weight: f64,
    /// Weight for bass dips (below `transition_freq`). Default: 1.0
    ///
    /// Historically this defaulted to 0.2 (near-ignore) as a crude
    /// proxy for "do not fight acoustic nulls". With explicit narrow-null
    /// suppression in place, broad bass dips (SBIR, baffle step) become
    /// legitimate correction targets and the dip weight is aligned with
    /// the mid/treble default.
    pub bass_dip_weight: f64,
    /// Transition frequency between bass and mid/treble weighting. Default: 300.0 Hz
    pub transition_freq: f64,
}

impl Default for AsymmetricLossConfig {
    fn default() -> Self {
        Self {
            peak_weight: 2.0,
            dip_weight: 1.0,
            bass_peak_weight: 5.0,
            bass_dip_weight: 1.0,
            transition_freq: 300.0,
        }
    }
}

/// Frequency band configuration for weighted loss
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(default)]
pub struct FrequencyBandWeights {
    /// Bass band minimum frequency (Hz)
    pub bass_min: f64,
    /// Bass band maximum frequency (Hz)
    pub bass_max: f64,
    /// Midrange band minimum frequency (Hz)
    pub mid_min: f64,
    /// Midrange band maximum frequency (Hz)
    pub mid_max: f64,
    /// Treble band minimum frequency (Hz)
    pub treble_min: f64,
    /// Treble band maximum frequency (Hz)
    pub treble_max: f64,
    /// Weight for bass band (default: 2.0 - bass is more critical for room correction)
    pub bass_weight: f64,
    /// Weight for midrange band (default: 1.0)
    pub mid_weight: f64,
    /// Weight for treble band (default: 0.8 - less critical for room issues)
    pub treble_weight: f64,
}

impl Default for FrequencyBandWeights {
    fn default() -> Self {
        Self {
            bass_min: 20.0,
            bass_max: 200.0,
            mid_min: 200.0,
            mid_max: 4_000.0,
            treble_min: 4_000.0,
            treble_max: 20_000.0,
            bass_weight: 2.0,
            mid_weight: 1.0,
            treble_weight: 0.8,
        }
    }
}

#[cfg(test)]
mod frequency_band_weights_tests {
    use super::*;

    #[test]
    fn partial_frequency_band_weights_inherit_defaults() {
        let parsed: FrequencyBandWeights = serde_json::from_str(r#"{"bass_weight": 3.5}"#).unwrap();
        assert_eq!(parsed.bass_weight, 3.5);
        assert_eq!(
            parsed.mid_weight,
            FrequencyBandWeights::default().mid_weight
        );
        assert_eq!(
            parsed.treble_max,
            FrequencyBandWeights::default().treble_max
        );
    }
}

/// Program-material bias for temporal masking.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum TemporalMaskingProfile {
    /// Percussive material: modal ringing is least masked and should be cut
    /// more decisively.
    Transient,
    /// General music / film content.
    #[default]
    Mixed,
    /// Sustained material: late modal decay is partly masked by ongoing tone.
    Sustained,
}

fn default_temporal_masking_enabled() -> bool {
    true
}
fn default_temporal_masking_weight() -> f64 {
    0.15
}
fn default_ir_temporal_masking_enabled() -> bool {
    true
}
fn default_ir_temporal_masking_weight() -> f64 {
    0.05
}
fn default_pre_mask_ms() -> f64 {
    3.0
}
fn default_post_mask_ms() -> f64 {
    120.0
}
fn default_pre_ringing_weight() -> f64 {
    2.0
}
fn default_post_ringing_weight() -> f64 {
    1.0
}
fn default_ir_audibility_threshold_db() -> f64 {
    -45.0
}

/// Experimental EPA temporal-diagnostic configuration.
///
/// Modal controls are retained for report compatibility and offline analysis;
/// they do not steer the active spectral-flatness-only EPA optimizer.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
pub struct TemporalMaskingConfig {
    /// Enable the legacy modal temporal diagnostic when modal data is available.
    #[serde(default = "default_temporal_masking_enabled")]
    pub enabled: bool,
    /// Legacy diagnostic weight; it does not steer EPA optimizer fitness.
    #[serde(default = "default_temporal_masking_weight")]
    pub weight: f64,
    /// Diagnostic programme-profile label for modal-ringing reporting.
    #[serde(default)]
    pub profile: TemporalMaskingProfile,
    /// Enable true FIR impulse-response pre/post masking analysis when FIR
    /// coefficients are available.
    #[serde(default = "default_ir_temporal_masking_enabled")]
    pub ir_enabled: bool,
    /// Weight applied to the IR masking penalty metric.
    #[serde(default = "default_ir_temporal_masking_weight")]
    pub ir_weight: f64,
    /// Pre-masking window before the main impulse. Pre-ringing inside this
    /// window is partially masked; earlier energy is fully audible.
    #[serde(default = "default_pre_mask_ms")]
    pub pre_mask_ms: f64,
    /// Post-masking window after the main impulse. Ringing grows more audible
    /// as it decays beyond this window.
    #[serde(default = "default_post_mask_ms")]
    pub post_mask_ms: f64,
    /// Relative weight for audible pre-ringing. Usually higher than post
    /// because pre-echo before a transient is especially objectionable.
    #[serde(default = "default_pre_ringing_weight")]
    pub pre_ringing_weight: f64,
    /// Relative weight for audible post-ringing.
    #[serde(default = "default_post_ringing_weight")]
    pub post_ringing_weight: f64,
    /// Audibility floor for weighted pre/post ringing energy, in dB relative
    /// to the main impulse peak.
    #[serde(default = "default_ir_audibility_threshold_db")]
    pub ir_audibility_threshold_db: f64,
}

impl Default for TemporalMaskingConfig {
    fn default() -> Self {
        Self {
            enabled: default_temporal_masking_enabled(),
            weight: default_temporal_masking_weight(),
            profile: TemporalMaskingProfile::Mixed,
            ir_enabled: default_ir_temporal_masking_enabled(),
            ir_weight: default_ir_temporal_masking_weight(),
            pre_mask_ms: default_pre_mask_ms(),
            post_mask_ms: default_post_mask_ms(),
            pre_ringing_weight: default_pre_ringing_weight(),
            post_ringing_weight: default_post_ringing_weight(),
            ir_audibility_threshold_db: default_ir_audibility_threshold_db(),
        }
    }
}

fn default_flatness_erb_weight() -> f64 {
    1.0
}

/// Experimental EPA diagnostics and optimizer flatness configuration.
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(default)]
pub struct EpaConfig {
    /// Listening level in phon for diagnostic loudness computation.
    pub listening_level_phon: f64,
    /// Diagnostic target sharpness in acum (1.0 = natural broadband noise character).
    pub target_sharpness: f64,
    /// Diagnostic roughness threshold; transfer-only roughness does not steer optimization.
    pub max_roughness: f64,
    /// Diagnostic weights for the three reported EPA dimensions.
    pub evaluation_weight: f64,
    pub potency_weight: f64,
    pub activity_weight: f64,
    /// Band weights used for the flatness component of the EPA loss.
    /// Only consulted when `flatness_band_weight > 0`.
    #[serde(default)]
    pub flatness_band_weights: FrequencyBandWeights,
    /// ERB-rate weight for the active optimizer flatness component.
    /// The default is 1.0 (pure ERB-rate flatness).
    #[serde(default = "default_flatness_erb_weight")]
    pub flatness_erb_weight: f64,
    /// Band weight for the flatness component of the EPA loss.
    /// Default 0.0 (see `flatness_erb_weight`).
    #[serde(default)]
    pub flatness_band_weight: f64,
    /// Experimental temporal diagnostics for modal decay and FIR phase behavior.
    /// These settings do not steer EPA optimization. Confident measured
    /// band-limited SSIR decay is preferred for modal reporting; magnitude Q is
    /// only a fallback, and realized FIR pre/post ringing is analyzed separately.
    #[serde(default)]
    pub temporal_masking: TemporalMaskingConfig,
}

impl Default for EpaConfig {
    fn default() -> Self {
        Self {
            listening_level_phon: 75.0,
            target_sharpness: 1.2,
            max_roughness: 0.5,
            evaluation_weight: 0.6,
            potency_weight: 0.2,
            activity_weight: 0.2,
            flatness_band_weights: FrequencyBandWeights::default(),
            flatness_erb_weight: 1.0,
            flatness_band_weight: 0.0,
            temporal_masking: TemporalMaskingConfig::default(),
        }
    }
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
pub enum MultiMeasurementStrategy {
    #[default]
    Average,
    WeightedSum,
    Minimax,
    VariancePenalized,
    SpatialRobustness,
    MinimaxUncertainty,
}

#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub enum CrossoverType {
    Butterworth2,
    #[serde(alias = "BW24", alias = "Butterworth24")]
    Butterworth4,
    LinkwitzRiley2,
    #[default]
    #[serde(alias = "LR24")]
    LinkwitzRiley4,
    #[serde(alias = "LR48")]
    LinkwitzRiley8,
    #[serde(alias = "LinearPhase")]
    LinearPhase,
    None,
}

impl std::str::FromStr for CrossoverType {
    type Err = String;

    fn from_str(value: &str) -> Result<Self, Self::Err> {
        match value.to_lowercase().as_str() {
            "butterworth2" | "bw2" | "butterworth12" | "bw12" => Ok(Self::Butterworth2),
            "butterworth4" | "bw4" | "butterworth24" | "bw24" => Ok(Self::Butterworth4),
            "lr2" | "lr12" | "linkwitzriley2" | "linkwitzriley12" => Ok(Self::LinkwitzRiley2),
            "lr4" | "lr24" | "linkwitzriley4" | "linkwitzriley24" => Ok(Self::LinkwitzRiley4),
            "lr8" | "lr48" | "linkwitzriley8" | "linkwitzriley48" => Ok(Self::LinkwitzRiley8),
            "linearphase" | "linear_phase" | "linear-phase" | "linearphasefir" | "fir"
            | "lpfir" => Ok(Self::LinearPhase),
            "none" => Ok(Self::None),
            _ => Err(format!("Unknown crossover type: {value}")),
        }
    }
}