audiobook-creation-exchange 0.1.0

//! ACX-compliant audio post-processing pipeline for speech audio.
//!
//! Validates and repairs raw L16 mono PCM against the ACX audiobook specification
//! (−23…−18 dBFS RMS, −3 dBFS true-peak, −60 dBFS noise floor) per
//! <https://www.acx.com/help/acx-producer-standards/201456300>.
//!
//! # Pipeline (applied in order by [`process`])
//!
//! 1. **Click suppression** — removes sub-10 ms transient spikes via cubic Hermite interpolation.
//! 2. **DC offset removal** — subtract the mean sample value.
//! 3. **Noise reduction** — Wiener spectral subtraction profiled from the leading silence
//!    (disabled by default; requires a silent lead-in — see [`AcxConfig::denoise_enabled`]).
//! 4. **EQ warmth** — low-shelf (+2 dB @ 180 Hz) + high-shelf (+1.5 dB @ 5 kHz) biquad IIR.
//! 5. **De-essing** — OLA STFT; reduces 5–8 kHz sibilance band by up to −6 dB.
//! 6. **Plosive suppression** — OLA STFT; attenuates sub-150 Hz bins on plosive windows.
//! 7. **Multiband compression** — 3-band LR4 crossover compressor (250 Hz / 3 kHz crossovers);
//!    runs before normalisation so the level step sees the compressed spectrum.
//! 8. **Normalise** — linear gain to −20.5 dBFS, pre-compensated for bookend energy dilution.
//! 9. **Limit** — 5 ms lookahead brickwall limiter; no peak (including 4× interpolated) exceeds −3 dBFS.
//! 10. **Breath removal** — breath-band windows replaced with room tone (disabled by default).
//! 11. **Pause normalisation** — caps over-long inter-sentence pauses to natural targets
//!     (sentence 120 ms, paragraph 400 ms, scene break 700 ms); skips leading/trailing silence.
//! 12. **Gate** — sub-threshold 50 ms windows replaced with 1/f pink noise room tone.
//! 13. **Bookend padding** — first 1 s and last 3 s forced to room tone with 10 ms crossfades.
//! 14. **Verify** — second analysis pass; returns `Err(AcxError::StillNonCompliant)` only when audio is irrecoverably broken.
//!
//! # Standalone utilities
//!
//! - [`crossfade()`] — equal-power segment transition
//! - [`consistency_check`] — batch RMS variance check across multiple segments
//! - [`LoudnessPreset`] — pre-built [`AcxConfig`] variants for different delivery loudness levels

pub mod analyse;
pub mod bitstream;
pub mod breath;
pub mod click;
pub mod consistency;
pub mod crossfade;
pub mod dc_offset;
pub mod deess;
pub mod denoise;
pub mod eq;
pub mod error;
pub mod gate;
pub mod limiter;
pub mod loudness_preset;
pub mod lufs;
pub mod multiband;
pub mod normalise;
pub mod pause_norm;
pub mod plosive;
pub mod room_tone;
pub mod spectral;
pub mod temporal;

pub use analyse::{AcxReport, analyse};
pub use bitstream::{CbrReport, Id3Report, check_cbr, check_id3_tags};
pub use consistency::{ConsistencyReport, consistency_check};
pub use crossfade::crossfade;
pub use error::AcxError;
pub use loudness_preset::LoudnessPreset;
pub use lufs::{LufsReport, integrated_lufs, loudness_range};
pub use multiband::MultibandParams;
pub use spectral::{SpectralViolation, SpectralViolationKind, scan as spectral_scan};
pub use temporal::{
    DeadAirViolation, check_bookends, count_digital_zero_runs, detect_dead_air, max_dead_air,
};

/// Audio processing configuration.
///
/// Defaults match the published ACX audiobook specification (−20.5 dBFS target,
/// −23…−18 dBFS RMS window, −3 dBFS peak, −60 dBFS noise floor). Construct with
/// [`AcxConfig::default`] and override individual fields as needed, or use
/// [`LoudnessPreset::config`] to get a pre-built variant for a specific loudness level.
#[derive(Debug, Clone)]
pub struct AcxConfig {
    /// Target RMS to normalise to.
    pub rms_target_db: f32,
    /// Lower bound of the acceptable RMS range.
    pub rms_min_db: f32,
    /// Upper bound of the acceptable RMS range.
    pub rms_max_db: f32,
    /// True-peak ceiling — no sample (incl. inter-sample peaks) may exceed this.
    pub peak_ceiling_db: f32,
    /// Noise floor must not exceed this value.
    pub noise_floor_max_db: f32,
    /// Windows below this RMS are replaced with room tone by the gate.
    pub silence_threshold_db: f32,
    /// RMS level for synthesised room tone — must be below `noise_floor_max_db`.
    pub room_tone_db: f32,
    /// Maximum contiguous silence allowed inside a chapter.
    pub dead_air_limit: time::Duration,
    /// Sibilance band-energy ratio above which a window is flagged.
    pub sibilance_ratio_threshold: f32,
    /// Plosive band-energy ratio above which a window is flagged.
    pub plosive_ratio_threshold: f32,

    // ── pipeline feature flags ─────────────────────────────────────────────
    /// Remove sub-10 ms click artifacts before spectral processing.
    pub click_suppression_enabled: bool,
    /// Apply Wiener spectral subtraction noise reduction.
    ///
    /// Disabled by default. The profiling window is the first `denoise_profile_ms`
    /// milliseconds of the signal; if that region contains speech instead of room
    /// tone the speech itself will be treated as noise and attenuated.
    pub denoise_enabled: bool,
    /// Length of the noise-profile segment at the head of the signal (ms).
    pub denoise_profile_ms: u32,
    /// Oversubtraction factor for noise reduction (>1 compensates for estimation error).
    pub denoise_oversubtraction: f32,
    /// Spectral floor for noise reduction — bins are never reduced below this gain.
    pub denoise_spectral_floor: f32,
    /// Apply warmth shelving EQ (low-shelf body + high-shelf presence) in the pipeline.
    pub eq_enabled: bool,
    /// Low-shelf gain in dB (positive = boost).
    pub eq_low_shelf_db: f32,
    /// High-shelf gain in dB (positive = boost).
    pub eq_high_shelf_db: f32,
    /// Apply frequency-selective de-essing (5–8 kHz gain reduction) in the pipeline.
    pub deess_enabled: bool,
    /// Sibilance energy ratio above which de-essing begins (0.0–1.0).
    pub deess_threshold_ratio: f32,
    /// Maximum dB reduction applied by the de-esser (positive value = attenuation).
    pub deess_max_reduction_db: f32,
    /// Apply plosive suppression (sub-150 Hz shelving on plosive windows) in the pipeline.
    pub plosive_suppression_enabled: bool,
    /// Attenuation applied to the plosive band when suppression fires (dB, positive = cut).
    pub plosive_attenuation_db: f32,
    /// Apply 3-band multiband compression after normalisation.
    pub multiband_enabled: bool,
    /// Remove breath sounds (replace with room tone) in the pipeline.
    /// Disabled by default — preserving breaths keeps narration feeling natural.
    pub breath_removal_enabled: bool,
    /// Cap over-long pauses to natural sentence/paragraph/scene-break targets.
    pub pause_norm_enabled: bool,
    /// Target length for sentence-level pauses (< 200 ms) after capping, in ms.
    pub pause_sentence_target_ms: u32,
    /// Target length for paragraph-level pauses (200–800 ms) after capping, in ms.
    pub pause_paragraph_target_ms: u32,
    /// Target length for scene-break pauses (> 800 ms) after capping, in ms.
    pub pause_scene_target_ms: u32,
}

impl Default for AcxConfig {
    fn default() -> Self {
        Self {
            rms_target_db: -20.5,
            rms_min_db: -23.0,
            rms_max_db: -18.0,
            peak_ceiling_db: -3.0,
            noise_floor_max_db: -60.0,
            silence_threshold_db: -65.0,
            room_tone_db: -62.0, // 2 dB below limit — inaudible but non-zero
            dead_air_limit: temporal::DEAD_AIR_LIMIT,
            sibilance_ratio_threshold: spectral::SIBILANCE_RATIO_THRESHOLD,
            plosive_ratio_threshold: spectral::PLOSIVE_RATIO_THRESHOLD,
            click_suppression_enabled: true,
            denoise_enabled: false,
            denoise_profile_ms: denoise::DEFAULT_PROFILE_MS,
            denoise_oversubtraction: denoise::DEFAULT_OVERSUBTRACTION,
            denoise_spectral_floor: denoise::DEFAULT_SPECTRAL_FLOOR,
            eq_enabled: true,
            eq_low_shelf_db: eq::DEFAULT_LOW_SHELF_DB,
            eq_high_shelf_db: eq::DEFAULT_HIGH_SHELF_DB,
            deess_enabled: true,
            deess_threshold_ratio: deess::DEFAULT_THRESHOLD_RATIO,
            deess_max_reduction_db: deess::DEFAULT_MAX_REDUCTION_DB,
            plosive_suppression_enabled: true,
            plosive_attenuation_db: plosive::DEFAULT_ATTENUATION_DB,
            multiband_enabled: true,
            breath_removal_enabled: false,
            pause_norm_enabled: true,
            pause_sentence_target_ms: pause_norm::DEFAULT_SENTENCE_TARGET_MS,
            pause_paragraph_target_ms: pause_norm::DEFAULT_PARAGRAPH_TARGET_MS,
            pause_scene_target_ms: pause_norm::DEFAULT_SCENE_TARGET_MS,
        }
    }
}

/// Full diagnostic report produced by [`validate`].
///
/// Covers every ACX/EBU/ITU quality axis in a single pass over the PCM buffer.
/// This is read-only — none of the fields imply automatic repair.
#[derive(Debug, Clone)]
pub struct DiagnosticReport {
    // --- ACX core ---
    /// Overall RMS in dBFS.
    pub rms_db: f32,
    /// True-peak in dBFS (4× oversampled).
    pub peak_db: f32,
    /// Noise floor in dBFS (quietest 10 % of 50 ms windows).
    pub noise_floor_db: f32,
    /// Whether all ACX core metrics are in spec.
    pub acx_compliant: bool,

    // --- DC offset ---
    /// DC offset as a fraction of full scale (−1.0…1.0).
    pub dc_offset: f32,
    /// Whether DC offset exceeds 1 % of full scale.
    pub has_dc_offset: bool,

    // --- Spectral ---
    /// Windows with excessive high-frequency energy (sibilance or plosives).
    pub spectral_violations: Vec<SpectralViolation>,

    // --- Temporal ---
    /// Contiguous silence blocks longer than the dead-air limit.
    pub dead_air_violations: Vec<DeadAirViolation>,
    /// Whether the head (first 1 s) is at room-tone level or below.
    pub head_ok: bool,
    /// Whether the tail (last 3 s) is at room-tone level or below.
    pub tail_ok: bool,
    /// Number of digital-zero runs (≥ 1 ms of consecutive zeros).
    pub digital_zero_runs: usize,

    // --- LUFS / LRA ---
    /// Integrated LUFS per ITU-R BS.1770-4.
    pub integrated_lufs: f32,
    /// Loudness range in LU per EBU R 128.
    pub loudness_range: f32,
}

/// Run a full diagnostic pass on raw L16-LE PCM bytes without modifying them.
///
/// Use this before [`process`] to decide whether repair is needed and to
/// surface any quality issues to the caller.
pub fn validate(pcm_bytes: &[u8], sample_rate: u32) -> Result<DiagnosticReport, AcxError> {
    validate_with_config(pcm_bytes, sample_rate, &AcxConfig::default())
}

/// Like [`validate`] but with a custom [`AcxConfig`].
pub fn validate_with_config(
    pcm_bytes: &[u8],
    sample_rate: u32,
    cfg: &AcxConfig,
) -> Result<DiagnosticReport, AcxError> {
    if pcm_bytes.is_empty() {
        return Err(AcxError::EmptyInput);
    }

    let samples = bytes_to_samples(pcm_bytes)?;

    let acx = analyse::analyse(&samples, sample_rate, cfg);
    let dc = dc_offset::measure(&samples);
    let spectral_violations = spectral::scan(&samples, sample_rate);
    let dead_air_violations =
        temporal::detect_dead_air(&samples, sample_rate, cfg.silence_threshold_db);
    let (head_ok, tail_ok) = temporal::check_bookends(&samples, sample_rate);
    let digital_zero_runs = temporal::count_digital_zero_runs(&samples);
    let il = lufs::integrated_lufs(&samples, sample_rate);
    let lr = lufs::loudness_range(&samples, sample_rate);

    Ok(DiagnosticReport {
        rms_db: acx.rms_db,
        peak_db: acx.peak_db,
        noise_floor_db: acx.noise_floor_db,
        acx_compliant: acx.compliant,
        dc_offset: dc,
        has_dc_offset: dc_offset::has_offset(&samples),
        spectral_violations,
        dead_air_violations,
        head_ok,
        tail_ok,
        digital_zero_runs,
        integrated_lufs: il,
        loudness_range: lr,
    })
}

/// Convert raw L16-LE bytes to i16 samples.
///
/// Returns `Err(AcxError::OddByteLength)` if `bytes.len()` is not even.
pub fn bytes_to_samples(bytes: &[u8]) -> Result<Vec<i16>, AcxError> {
    if bytes.len() % 2 != 0 {
        return Err(AcxError::OddByteLength);
    }
    Ok(bytes
        .chunks_exact(2)
        .map(|c| i16::from_le_bytes([c[0], c[1]]))
        .collect())
}

/// Convert i16 samples back to L16-LE bytes.
pub fn samples_to_bytes(samples: &[i16]) -> Vec<u8> {
    samples.iter().flat_map(|&s| s.to_le_bytes()).collect()
}

/// Run the full ACX post-processing pipeline on raw L16-LE PCM bytes.
///
/// # Errors
///
/// Returns [`AcxError::OddByteLength`] if input length is odd.
/// Returns [`AcxError::EmptyInput`] if input is empty.
/// Returns [`AcxError::StillNonCompliant`] if the audio cannot be brought into
/// compliance after all processing steps (extremely rare — indicates a segment
/// that is almost entirely silence).
pub fn process(pcm_bytes: &[u8], sample_rate: u32) -> Result<Vec<u8>, AcxError> {
    process_with_config(pcm_bytes, sample_rate, &AcxConfig::default())
}

/// Like [`process`] but with a custom [`AcxConfig`].
pub fn process_with_config(
    pcm_bytes: &[u8],
    sample_rate: u32,
    cfg: &AcxConfig,
) -> Result<Vec<u8>, AcxError> {
    if pcm_bytes.is_empty() {
        return Err(AcxError::EmptyInput);
    }

    let mut samples = bytes_to_samples(pcm_bytes)?;

    // 1. Click suppression — remove sub-10 ms transient spikes before any
    //    spectral processing (clicks would smear across STFT frames).
    if cfg.click_suppression_enabled {
        click::suppress_clicks(&mut samples, sample_rate);
    }

    // 2. DC offset removal — before any gain changes to avoid skewing RMS target.
    if dc_offset::has_offset(&samples) {
        dc_offset::remove(&mut samples);
    }

    // 3. Noise reduction — profile from the head of the signal (pre-processing),
    //    then subtract spectrally across all frames.
    if cfg.denoise_enabled {
        denoise::denoise_with_params(
            &mut samples,
            sample_rate,
            cfg.denoise_profile_ms,
            cfg.denoise_oversubtraction,
            cfg.denoise_spectral_floor,
        );
    }

    // 4. Warmth EQ — shape the spectrum before spectral cleanup so the de-esser
    //    and plosive suppressor see the boosted spectrum and compensate correctly.
    if cfg.eq_enabled {
        eq::apply_warmth_with_params(
            &mut samples,
            sample_rate,
            cfg.eq_low_shelf_db,
            eq::DEFAULT_LOW_SHELF_HZ,
            cfg.eq_high_shelf_db,
            eq::DEFAULT_HIGH_SHELF_HZ,
        );
    }

    // 5 & 6. Spectral cleanup BEFORE normalisation so the level-setting step sees
    //     the final spectral shape.  De-essing and plosive suppression are
    //     amplitude-agnostic (they operate on energy ratios); running them here
    //     avoids a second limiter pass and keeps the RMS target accurate.
    if cfg.deess_enabled {
        deess::deess_with_params(
            &mut samples,
            sample_rate,
            cfg.deess_threshold_ratio,
            cfg.deess_max_reduction_db,
        );
    }
    if cfg.plosive_suppression_enabled {
        plosive::suppress_plosives_with_attenuation(
            &mut samples,
            sample_rate,
            cfg.plosive_attenuation_db,
        );
    }

    // 7a. Multiband compression BEFORE normalise — so the normaliser sees the
    //     compressed spectral energy and can reach the RMS target accurately.
    //     Running after normalise would undercut the target by the compression gain.
    if cfg.multiband_enabled {
        multiband::compress(&mut samples, sample_rate);
    }

    // 7. Normalise to target RMS — pre-compensated for bookend energy loss.
    //
    // pad_bookends (step 3) replaces HEAD + TAIL with room tone at room_tone_db,
    // diluting the overall RMS.  We adjust the normalise target so the FINAL
    // post-pad RMS equals cfg.rms_target_db.
    //
    // Derivation: after pad_bookends the middle portion has been scaled by the
    // normalise gain g (= N_linear / R_in), so its RMS is g·R_middle.
    // Energy conservation:
    //   target² = (S-B)/S · (g·R_middle)²  +  B/S · tone²
    //   g        = sqrt[(target² - B/S·tone²) · S / ((S-B)·R_middle²)]
    //   N        = g · R_in
    //            = target · sqrt[S/(S-B)] · (R_in/R_middle)   [tone² negligible]
    //   N_db     = target_db + 10·log₁₀(S/(S-B)) + (R_in_db − R_middle_db)
    //
    // If the bookend regions are already silence, R_in < R_middle, the ratio
    // term is negative and exactly cancels the S/(S-B) boost — no compensation
    // is needed and the formula self-corrects.
    let normalise_target = {
        let head_s =
            (sample_rate as usize * temporal::HEAD_DURATION.whole_milliseconds() as usize) / 1000;
        let tail_s =
            (sample_rate as usize * temporal::TAIL_DURATION.whole_milliseconds() as usize) / 1000;
        let speech_start = head_s.min(samples.len());
        let speech_end = samples.len().saturating_sub(tail_s).max(speech_start);

        if speech_start < speech_end {
            let overall_rms_db = analyse::rms_db(&samples);
            let middle_rms_db = analyse::rms_db(&samples[speech_start..speech_end]);
            let s = samples.len() as f32;
            let b = (head_s + tail_s).min(samples.len()) as f32;
            // N = target + 10·log10(S/(S-B)) + (R_overall - R_middle)
            cfg.rms_target_db + 10.0 * (s / (s - b)).log10() + (overall_rms_db - middle_rms_db)
        } else {
            cfg.rms_target_db
        }
    };
    normalise::normalise(&mut samples, normalise_target);

    // 9. Brickwall peak limiter — safety net after compression; also absorbs any
    //    peaks introduced by OLA or EQ processing.
    limiter::limit(&mut samples, sample_rate, cfg.peak_ceiling_db);

    // 10. Breath removal after normalisation so room-tone fill sits at the correct
    //     level relative to the normalised signal.
    if cfg.breath_removal_enabled {
        breath::remove_breaths(&mut samples, sample_rate, cfg.room_tone_db);
    }

    // 11. Pause normalisation — cap over-long TTS pauses before the gate runs,
    //     so the gate fills correctly-sized silence windows.
    if cfg.pause_norm_enabled {
        samples = pause_norm::normalize_pauses_with_targets(
            &samples,
            sample_rate,
            cfg.pause_sentence_target_ms,
            cfg.pause_paragraph_target_ms,
            cfg.pause_scene_target_ms,
        );
    }

    // 12. Gate sub-threshold windows → room tone + enforce head/tail bookends
    let tone_samples = sample_rate as usize / 2; // 500 ms is enough to tile from
    let tone = room_tone::generate_room_tone(tone_samples, cfg.room_tone_db);
    gate::gate_to_room_tone(&mut samples, sample_rate, cfg.silence_threshold_db, &tone);
    gate::pad_bookends(&mut samples, sample_rate, &tone);

    // 14. Verify
    let report = analyse::analyse(&samples, sample_rate, cfg);
    if !report.compliant {
        return Err(AcxError::StillNonCompliant {
            rms_db: report.rms_db,
            rms_min: cfg.rms_min_db,
            rms_max: cfg.rms_max_db,
            peak_db: report.peak_db,
            peak_ceiling: cfg.peak_ceiling_db,
            noise_floor_db: report.noise_floor_db,
            noise_floor_max: cfg.noise_floor_max_db,
        });
    }

    Ok(samples_to_bytes(&samples))
}

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

    const SAMPLE_RATE: u32 = 24_000;

    fn sine_wave(freq_hz: f32, duration_secs: f32, amplitude: f32, sample_rate: u32) -> Vec<i16> {
        let n = (sample_rate as f32 * duration_secs) as usize;
        (0..n)
            .map(|i| {
                let t = i as f32 / sample_rate as f32;
                let v = amplitude * (2.0 * std::f32::consts::PI * freq_hz * t).sin();
                v.clamp(i16::MIN as f32, i16::MAX as f32) as i16
            })
            .collect()
    }

    fn to_bytes(samples: &[i16]) -> Vec<u8> {
        samples_to_bytes(samples)
    }

    /// Alternating 300 ms sine + 50 ms silence — mimics narration pauses.
    fn speech_like(amplitude: f32, total_secs: f32, sample_rate: u32) -> Vec<i16> {
        let speech_ms = 300usize;
        let pause_ms = 50usize;
        let period_samples = (sample_rate as usize * (speech_ms + pause_ms)) / 1000;
        let total_samples = (sample_rate as f32 * total_secs) as usize;
        let speech_samples = (sample_rate as usize * speech_ms) / 1000;

        let mut out = Vec::with_capacity(total_samples);
        let mut t = 0usize;
        while out.len() < total_samples {
            let pos = t % period_samples;
            if pos < speech_samples {
                let sine_t = pos as f32 / sample_rate as f32;
                let v = amplitude * (2.0 * std::f32::consts::PI * 440.0 * sine_t).sin();
                out.push(v.clamp(i16::MIN as f32, i16::MAX as f32) as i16);
            } else {
                out.push(0i16);
            }
            t += 1;
        }
        out.truncate(total_samples);
        out
    }

    #[test]
    fn normalise_brings_quiet_track_into_window() {
        // 10 s: pad_bookends consumes 1 s head + 3 s tail, leaving 6 s of speech.
        let samples = speech_like(1000.0, 10.0, SAMPLE_RATE);
        let bytes = to_bytes(&samples);
        let out = process(&bytes, SAMPLE_RATE).unwrap();
        let out_samples = bytes_to_samples(&out).unwrap();
        let report = analyse::analyse(&out_samples, SAMPLE_RATE, &AcxConfig::default());
        assert!(
            report.rms_db >= -23.0 && report.rms_db <= -18.0,
            "RMS out of ACX window: {:.1} dB",
            report.rms_db
        );
    }

    #[test]
    fn limiter_prevents_clipping() {
        let samples = speech_like(i16::MAX as f32 * 0.99, 10.0, SAMPLE_RATE);
        let bytes = to_bytes(&samples);
        let out = process(&bytes, SAMPLE_RATE).unwrap();
        let out_samples = bytes_to_samples(&out).unwrap();
        let report = analyse::analyse(&out_samples, SAMPLE_RATE, &AcxConfig::default());
        assert!(
            report.peak_db <= -3.0,
            "Peak exceeded ACX ceiling: {:.1} dB",
            report.peak_db
        );
    }

    #[test]
    fn gate_replaces_digital_silence() {
        // 1 s zeros + 8 s speech = 9 s total; pad_bookends takes 4 s leaving 5 s of speech.
        let mut samples = vec![0i16; SAMPLE_RATE as usize];
        samples.extend(sine_wave(440.0, 8.0, 3000.0, SAMPLE_RATE));
        let bytes = to_bytes(&samples);
        let out = process(&bytes, SAMPLE_RATE).unwrap();
        let out_samples = bytes_to_samples(&out).unwrap();
        let silent_half = &out_samples[..SAMPLE_RATE as usize];
        let floor = analyse::noise_floor_db(silent_half, SAMPLE_RATE);
        assert!(floor > -144.0, "Gate did not replace digital silence");
    }

    #[test]
    fn odd_byte_length_returns_error() {
        let bytes = vec![0u8; 101];
        assert!(matches!(
            process(&bytes, SAMPLE_RATE),
            Err(AcxError::OddByteLength)
        ));
    }

    #[test]
    fn empty_input_returns_error() {
        assert!(matches!(
            process(&[], SAMPLE_RATE),
            Err(AcxError::EmptyInput)
        ));
    }

    #[test]
    fn room_tone_hits_target_db() {
        let tone = room_tone::generate_room_tone(SAMPLE_RATE as usize, -62.0);
        let measured = analyse::rms_db(&tone);
        assert!(
            (measured - (-62.0)).abs() < 1.5,
            "Room tone RMS {:.1} dB too far from −62 dB",
            measured
        );
    }

    #[test]
    fn analyse_report_is_accurate() {
        let samples = sine_wave(440.0, 2.0, i16::MAX as f32, SAMPLE_RATE);
        let cfg = AcxConfig::default();
        let report = analyse::analyse(&samples, SAMPLE_RATE, &cfg);
        assert!(!report.compliant);
        assert!(report.peak_db > cfg.peak_ceiling_db);
    }

    #[test]
    fn validate_detects_dc_offset() {
        // Shift all samples by +1000 — ~3 % of full scale
        let samples: Vec<i16> = speech_like(2000.0, 2.0, SAMPLE_RATE)
            .into_iter()
            .map(|s| s.saturating_add(1000))
            .collect();
        let bytes = to_bytes(&samples);
        let report = validate(&bytes, SAMPLE_RATE).unwrap();
        assert!(report.has_dc_offset, "Expected DC offset to be detected");
    }

    #[test]
    fn validate_returns_lufs_for_speech_signal() {
        let samples = speech_like(3000.0, 5.0, SAMPLE_RATE);
        let bytes = to_bytes(&samples);
        let report = validate(&bytes, SAMPLE_RATE).unwrap();
        // LUFS should be a finite negative number for audible content
        assert!(
            report.integrated_lufs < 0.0 && report.integrated_lufs > -144.0,
            "Unexpected LUFS: {:.1}",
            report.integrated_lufs
        );
    }

    #[test]
    fn process_removes_dc_before_normalise() {
        // A DC-shifted signal should still produce a compliant output
        let samples: Vec<i16> = speech_like(1000.0, 10.0, SAMPLE_RATE)
            .into_iter()
            .map(|s| s.saturating_add(500))
            .collect();
        let bytes = to_bytes(&samples);
        let out = process(&bytes, SAMPLE_RATE).unwrap();
        let out_samples = bytes_to_samples(&out).unwrap();
        // DC offset should be gone
        assert!(
            dc_offset::measure(&out_samples).abs() < dc_offset::DC_OFFSET_THRESHOLD,
            "DC offset remains after processing"
        );
    }
}