fix(loudness): add preamp cut to prevent clipping from compensation boost

[iscle]

Heads-up: This PR and fix was generated by Claude, but I did manually review it and test it! No sloppy unsupervised AI code here :)

Summary

• Adds a preamp gain stage to LoudnessCompensator that attenuates the signal by the peak boost of the realized biquad response before the EQ cascade runs, preventing clipping
• Follows the same BiquadProcessor.preProcess pattern already used by AutoEQProcessor
• Fixes distortion most noticeable on hardware-volume devices (Bluetooth) at low-to-moderate listening levels

Problem

On hardware-volume devices like Bluetooth headphones, the audio signal stays at full amplitude in the processing pipeline (volume is controlled by the device, not digitally). Meanwhile, LoudnessCompensator sees the low device volume, computes a low phon level, and applies large frequency-dependent boosts (10–20 dB bass/treble at low volumes per ISO 226:2023 contours).

This pushes bass/treble peaks well above unity. The downstream SoftLimiter (threshold 0.95, ceiling 1.0 — only 0.05 headroom) then crushes these peaks, causing audible non-linear distortion. The lower the volume, the larger the compensation boost, and the worse the clipping.

Fix

Before the biquad cascade, apply a preamp cut equal to the inverse of the peak realized response:

peakBoostDB = max gain across 96 log-spaced frequencies (20 Hz–20 kHz)
preampGain  = 10^(-peakBoostDB / 20)

This ensures no frequency exceeds the original signal level after compensation. The preProcess hook (vDSP_vsmul) is RT-safe with zero allocations.

Related

Partially addresses #302 — the distortion component of the reported audio issues when loudness features are enabled. The volume-pumping behavior described in #302 is a separate concern in LoudnessEqualizer (dynamic gain leveler) involving over-aggressive boost settings and measurement/smoothing timing, which would need a separate fix.

Test plan

• Project builds cleanly (xcodebuild, CODE_SIGNING_ALLOWED=NO)
• Existing ISO226ContoursTests and ProcessingPipelineTests pass
• Manual: enable Loudness Compensation, play music over Bluetooth at low volume — bass should sound clean without distortion
• Manual: verify no perceptible volume drop at high volume (preamp ≈ 1.0 near reference level)

🤖 Generated with Claude Code

[gtg465x]

This PR is needed badly. I downloaded this app just for the loudness compensation feature and discovered it produced terrible clipping / distortion on both my iMac 5K built-in speakers and wired headphones at low volumes.

[djbob2000]

This PR is needed badly. I downloaded this app just for the loudness compensation feature and discovered it produced terrible clipping / distortion on both my iMac 5K built-in speakers and wired headphones at low volumes.

Please try my fixed version #317