secs_engine/
lib.rs

1#![forbid(unsafe_code)]
2#![deny(unsafe_op_in_unsafe_fn)]
3//! The correction design of SECS 2, translated function by function.
4//!
5//! Upstream sources: `correction_engine.py`, the compute half of
6//! `calibration.py`, `mimo.py`, `mimo_iir.py`, `scorecard.py`.
7//!
8//! The interface is one call: measurements, settings, tuning and a compute
9//! context in, an immutable result out. Internally the work is cut into deep
10//! modules (docs/ARCHITECTURE.md, "Engine"):
11//!
12//! - **measurement**: the one time-axis convention (earliest arrival at the
13//!   main position is zero, lift, shift), windows, a proper low-rate
14//!   projection for MIMO.
15//! - **target**: target curve and level reference, evaluated once per grid.
16//! - **filters**: RBJ/LR/BW/all-pass responses and the single PEQ fitter with
17//!   named limit bundles (RC, sub bus, bundle, XO, MIMO path).
18//! - **ba**: bass alignment (auto, fixed, bundles, DBA and multi-sub layouts,
19//!   infra sub, two-way level match, bus level, bus PEQ, bus delay/polarity).
20//! - **xo**: crossover groups, XO target PEQ, the recommendation.
21//! - **rc**: per-channel room correction (magnitude design, common excess
22//!   phase, FIR realisation ladder, PEQ refit, touch-up), Schroeder range.
23//! - **decay**: late-energy windows, mode T60, late peaks, "do no harm" guards.
24//! - **chain**: the DSP topology as one value; the response simulator here and
25//!   the CamillaDSP writer in `secs-camilla` read the same value.
26//! - **mimo**: support planning, regularised ideal supports (the λ search of
27//!   the ideal FIR goes through the `RidgeBackend` seam: CPU `RidgeSweep`
28//!   here, CUDA f64 in `secs-gpu`, ADR 0008), IIR or FIR realisation (IIR
29//!   always runs on the CPU).
30//! - **scorecard**: typed metrics before and after.
31//!
32//! Engine knobs that SECS 2 hid in environment variables are fields of an
33//! explicit tuning value. Defects fixed on the way are listed in
34//! docs/DEVIATIONS.md.
35
36pub mod grid;
37pub mod input;
38
39// The stages are private: `design` is the one entry point and the values it
40// returns are re-exported below. Helpers only the oracle tests call yet keep
41// the dead-code allowance.
42#[allow(dead_code)]
43mod ba;
44#[allow(dead_code)]
45mod calibration;
46#[allow(dead_code)]
47mod chain;
48#[allow(dead_code)]
49mod decay;
50#[allow(dead_code)]
51mod design;
52pub mod display;
53pub mod export_view;
54#[allow(dead_code)]
55mod fit;
56#[allow(dead_code)]
57mod levels;
58mod low_protect;
59#[allow(dead_code)]
60mod measurement;
61mod memory;
62#[allow(dead_code)]
63pub mod mimo;
64mod normalize;
65#[allow(dead_code)]
66mod notes;
67pub mod preview;
68#[allow(dead_code)]
69mod rc;
70mod replay;
71mod replay_mimo;
72#[allow(dead_code)]
73mod scorecard;
74#[allow(dead_code)]
75mod setup;
76#[allow(dead_code)]
77pub mod xo;
78
79mod error;
80#[cfg(test)]
81pub mod test_support;
82#[cfg(feature = "test-support")]
83#[doc(hidden)]
84pub mod testkit;
85#[cfg(test)]
86mod tests;
87
88pub use ba::{LayoutInfo, ManualPlan};
89pub use calibration::{
90    Calibration, CalibrationRequest, EngineInputs, ProjectView, calibrate, calibrate_with,
91    engine_inputs,
92};
93pub use chain::{BaRow, StageResponses, input_response, stage_responses};
94pub use design::{
95    Design, DesignRequest, DesignSpectra, FitStage, FitterFactory, MainDesign, RoleLateEnergy,
96    RoleScores, SubDesign, design, late_energy, production_fitters, production_fitters_with,
97};
98pub use error::EngineError;
99pub use export_view::{ExportView, export_view};
100pub use fit::{FitRequest, Fitter, PeqDerivatives, fit_peq_with};
101pub use input::{EngineConfig, Measurement, MeasurementSet, Samples, Tuning};
102pub use measurement::{Spectra, long_spectra};
103pub use mimo::{
104    IirDerivatives, IirSolveOptions, IirSolver, IirSupport, MimoDesign, MimoIir, MimoKey,
105    MimoRequest, MimoRoleLateEnergy, MimoRoleScore, MimoRun, design_mimo, design_mimo_iir,
106    design_mimo_iir_with_options,
107};
108pub use normalize::normalize_measurements;
109pub use notes::{GuardCause, MimoNote, Note};
110pub use replay::{DesignReplay, ExportAxis};
111pub use scorecard::Metrics;
112pub use secs_dsp::resample::{MAX_RESAMPLE_RATE, MIN_RESAMPLE_RATE};
113pub use setup::SubFilter;
114
115/// Complex spectrum value.
116pub type C = secs_dsp::Complex64;
secs_engine/lib.rs

secs_engine/
lib.rs
