DecayCore DSP Guards Reference
In brief
Principled guards define acceptable acoustic behavior. Technical guards prevent invalid math, unsafe array state, and unstable FIR output. This page is the complete guard reference, not a tuning guide.
This document defines all major guard mechanisms in the DSP pipeline and classifies them as either:
- Principled Guard → Part of DSP philosophy (defines intended acoustic behavior)
- Technical Guard → Implementation safety mechanism (prevents instability, invalid math, or edge-case failure)
Each guard includes:
- Location (module level)
- Typical config keys (if applicable)
- Pipeline stage
- Why it exists (design intent)
- What failure it prevents (engineering perspective)
PRINCIPLED GUARDS
These define how DecayCore is intended to behave acoustically. They shape correction philosophy, realism, and robustness.
1. Mixed Excess Mask (LF-only phase blending)
Location: dsp_phase / mixed-phase logic Stage: Phase construction
Why: Restricts excess-phase correction primarily to low frequencies with a soft transition band.
Prevents:
- Unrealistic full-band phase manipulation
- Audible timing artifacts in mid/high frequencies
- Excessive group delay distortion
2. Pre-Energy / Pre-Ringing Guard
Location: dsp/phase_ir_guards.py Stage: Post phase-IR generation
Config (typical):
- enable_ir_pre_energy_guard
- pre_energy_ratio_max
- max_pre_ringing_db
Why: Limits excessive energy before the main impulse peak to preserve transient realism.
Prevents:
- Strong pre-ringing
- Non-physical impulse shapes
- Audible temporal smearing
3. Max Boost / Max Cut Limits
Location: dsp/correction_mag.py, dsp/limits.py Stage: Magnitude correction
Config (typical):
- max_boost_db
- max_cut_db
- bass_boost_cap_* (optional LF refinement)
Why: Prevents unrealistic amplification demands on the system.
Prevents:
- Clipping
- Driver overload
- Unrealistic correction into deep nulls
4. Peak Priority Shaping
Location: dsp/correction_mag.py Stage: Error shaping
Config (typical):
- peak_priority_enable
- peak_priority_strength
Why: Reduces boost into narrow dips/nulls where correction is physically ineffective.
Prevents:
- Aggressive null-filling
- Excessive localized boost
5. Regularization
Location: dsp/correction_mag.py Stage: Target shaping
Config (typical):
- reg_strength
Why: Globally pulls correction toward 0 dB to improve robustness.
Prevents:
- Over-aggressive full-band correction
- Excess reliance on hard caps
6. Smoothing (Magnitude Domain)
Location: dsp/correction_mag.py Stage: Target conditioning
Why: Smooths the correction curve to improve spatial robustness and perceptual stability.
Prevents:
- Sawtooth filters
- Overfitting to measurement noise
7. Confidence-Based Weighting / Target Pull
Location: dsp/correction_mag.py, dsp/decaycore_dsp.py Stage: Target blending
Config (typical):
- conf_floor / conf_ceil
- gamma_cut / gamma_boost
Why: Reduces correction strength in low-confidence regions.
Prevents:
- Overcorrection in unreliable measurement areas
- Excess boost in cancellation-dominated regions
8. Auto Headroom / Auto Gain
Location: dsp/phase_ir_autogain.py Stage: Final normalization
Config (typical):
- auto_headroom_enable
- auto_gain_spike_threshold_db
Why: Ensures safe global output level.
Prevents:
- Clipping after filter export
- Hidden overload caused by combined boosts
9. GD Gradient Limiter
Location: dsp/decaycore_dsp.py Stage: Phase-domain limiting
Why: Constrains extreme group delay slope (ms/octave), especially in LF.
Prevents:
- Unrealistic timing behavior
- Excessively steep excess-phase transitions
TECHNICAL GUARDS
These ensure numerical and structural stability. They must remain always-on and are not part of user-facing philosophy.
1. IR Shift / Alignment Bounds
Location: dsp/phase_ir_align.py Stage: IR alignment
Why: Prevents illegal impulse shifts beyond window boundaries.
Prevents:
- Lost impulse peaks
- Index overflow
- Truncated IR
2. Alignment Fallback Logic
Location: dsp/phase_ir_align.py Stage: Alignment target computation
Why: Ensures safe defaults if centroid/peak detection fails.
Prevents:
- Undefined alignment targets
- Broken timing
3. Window Auto-Asymmetry Cap
Location: dsp/phase_ir_window.py Stage: Windowing
Why: Limits extreme asymmetric window selections.
Prevents:
- Impulse truncation
- Edge instability
4. NaN / Inf Sanitization
Location: Multiple modules Stage: Throughout pipeline
Why: Ensures stable numerical behavior.
Prevents:
- FFT explosions
- Derivative instability
- Invalid magnitude/phase arrays
5. Frequency Axis Sanitization
Location: dsp_preprocess / dsp_correction Stage: Preprocessing
Why: Guarantees monotonic and unique frequency axis.
Prevents:
- Derivative math failure
- Interpolation instability
Dependency Map (Dominance Overview)
This section describes which mechanisms typically dominate when multiple guards affect the same risk.
Legend:
- A → B : If A is strong, B becomes mostly a safety net.
- A ⇄ B : Partial overlap or tuning interaction.
Boost / Headroom Cluster
Regularization → Peak Priority → Max Boost/Cut → Auto Headroom
Upstream shaping should reduce how often hard caps are needed.
Overfitting / Sawtooth Cluster
Smoothing → (reduces need for) Slope Limits Smoothing ⇄ Regularization Confidence Weighting ⇄ Regularization
Slope limiting should rarely dominate if smoothing is well tuned.
Mixed-Phase Stability Cluster
Mixed Excess Mask → (reduces need for) GD Gradient Limiter
If GD limiter activates frequently, the excess mask is too permissive.
Time-Domain Stability Cluster
Alignment Bounds → Window Cap → Pre-Energy Guard
If pre-energy guard activates often, upstream alignment/window policy should be revised.
Trigger Matrix (Operational Monitoring)
Healthy system expectations:
Often active but gentle:
- Confidence weighting
- Smoothing
- Regularization
- Auto headroom
Occasional safety nets:
- Max boost/cut
- Peak priority
- Alignment clamp
Rare last-resort guards:
- Slope limit
- Pre-energy guard
- GD gradient limiter
- Spike guard
- NaN sanitization
If a rare guard triggers frequently, treat it as an upstream design issue rather than a tuning feature.
Design Rule
Principled guards define intended acoustic behavior. Technical guards ensure mathematical and structural stability.
Principled guards may be user-adjustable. Technical guards must never be disabled.
1. Overview
