S191: add engine_safaa_v5.py (continuous DF3 blend, S190 WPE guard, /app/deep-filter path)

engine_safaa_v5.py

@@ -0,0 +1,1263 @@
+#!/usr/bin/env python3
+"""
+الصفاء v5  —  Dedicated Dereverberation Engine
+إزالة الصدى والريفيرب
+
+FIXES vs v4 (v5):
+  B6  DF3 blending: replaced hard zone assignment + boundary-only crossfades
+      with continuous soft-weight blend (Gaussian-smoothed across ~300ms).
+      Root cause of "يروح ويجي" (comes-and-goes effect) was that attenuation
+      was constant inside each LOUD/MID/QUIET zone — only the boundary had a
+      crossfade. Now every sample gets its own uniquely blended attenuation
+      level that tracks signal RMS continuously. Zero zone steps.
+
+FIXES vs v2:
+  B1  _jalaa() late window: 150ms → 450ms (was reading 50-200ms; §3.3 says 50-500ms)
+  B2  _decode() now uses pcm_f32le → float32; soundfile when available (no 16-bit truncation)
+  B3  _band_energy() samples across full file (was FFT of first 1024 samples only)
+  B4  G4 Ra-trill: scans full audio in overlapping 1s windows (was first 1s only)
+  B5  _rt60() fallback slope condition was malformed (med-4 guard logic fixed)
+
+IMPROVEMENTS vs v2:
+  I1  DF3 three passes now run in parallel (ThreadPoolExecutor) — 3× faster
+  I2  _enc() intermediates are mono; only final output is stereo
+  I3  _tailnr() reduces nr by 1 when JALAA already ran (avoid double-attenuation)
+  I4  DF3 speech-pass attenuation capped to §79 per-style limits:
+        Murattal ≤ 18 dB  /  Mujawwad ≤ 6 dB
+  I5  WPE LRA check uses 50% overlapping frames (was non-overlapping → noisy)
+  I6  SafaaState gains guard_pass/guard_warn lists (structured; JSON report improved)
+  I7  LF EQ: LF band RT60 scaled by 1.3× per §3.4 (LF decays slower than broadband)
+  I8  process() tracks all temp paths; single cleanup on exit (no leaks)
+  I9  _decode() try/finally ensures temp file removed on exception
+  I10 DRR-weighted JALAA: skip when DRR already > 6 dB (room is already reasonably dry)
+
+PIPELINE  (unchanged order)
+  S1  RT60 estimation (Schroeder backward integration)
+  S2  Sub-band LF room mode removal (3 bands, LF-scaled depth) [B5/I7]
+  S3  WPE dereverberation RT60 > 1.0s
+  S4  DF3 reverb-adapted (4 passes parallel, continuous soft-weight blend) [I1/I4/B6]
+  S5  JALAA per-frame DRR gate [B1/I10]
+  S6  Tail floor NR (afftdn calibrated) [I3]
+  S7  Arabic phoneme guards [B3/B4]
+  S8a dynaudnorm level evenness (f=500ms, m=10, p=0.92) — kills DF3 adaptation bumps
+  S8b Volume boost: standard=1.85, aggressive=7.40 (4x)
+
+USAGE
+  python3 engine_safaa_v3.py input.wav output.wav [--tier X] [--mujawwad 0.0] [--rt60 0.0]
+
+KB REFS: §3 §28 §35 §36 §52 §79 §109 §138 §140 §143 §145 §151 §152 §154
+"""
+from __future__ import annotations
+
+__version__ = 'v5'
+
+import os, shutil, subprocess, tempfile, warnings, multiprocessing as _mp
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List, Optional, Tuple
+warnings.filterwarnings('ignore')
+
+_TMP = tempfile.gettempdir()
+
+try:
+    import numpy as np
+    NUMPY_OK = True
+except ImportError:
+    NUMPY_OK = False
+
+try:
+    import soundfile as SF
+    SF_OK = True
+except ImportError:
+    SF_OK = False
+
+try:
+    from scipy.io import wavfile as _scipy_wavfile
+    SCIPY_WAV_OK = True
+except ImportError:
+    SCIPY_WAV_OK = False
+
+# DF3 binary — search order: HF Space path first, then local dev paths
+_DF3_CLI_BIN = ''
+for _c in [
+    '/app/deep-filter',          # HuggingFace Space (Docker WORKDIR /app)
+    '/home/claude/deep-filter',  # local Termux/Claude dev
+    'deep-filter',               # in PATH
+    'deepfilter',
+    'deep_filter',
+]:
+    # shutil.which handles both absolute paths (existence+exec check) and PATH search
+    if shutil.which(_c) or (os.path.isfile(_c) and os.access(_c, os.X_OK)):
+        _DF3_CLI_BIN = _c; break
+DF3_OK = bool(_DF3_CLI_BIN)
+
+# nara_wpe
+WPE_OK = False
+try:
+    from nara_wpe.wpe import wpe_v8
+    from nara_wpe.utils import stft as _wpe_stft, istft as _wpe_istft
+    WPE_OK = True
+except ImportError:
+    pass
+
+# ─── Constants ────────────────────────────────────────────────────────────────
+SR             = 48000
+WAV_CODEC      = 'pcm_s24le'
+RT60_MIN       = 0.15    # below: nothing to do
+RT60_WPE_MIN   = 1.00    # §109.6
+RT60_TAILNR    = 0.30
+RT60_AGGR      = 1.50
+MUJ_RT60_FLOOR = 1.20    # §145.3
+
+# §79 per-style DF attenuation hard limits — v4: raised for deeper cleaning
+_DF3_LIM_MURATTAL  = 24   # dB maximum (was 18)
+_DF3_LIM_MUJAWWAD  =  8   # dB maximum (was 6)
+_DF3_SPEECH        = 15   # was 12
+_DF3_TRANS         = 24   # was 20
+_DF3_TAIL          = 32   # was 28
+
+_CHUNK_S       = 0.100
+_XFADE_N       = 960
+
+_RMS_MAX_DELTA = 1.0
+_LRA_MAX_DELTA = 0.5     # §109.4
+
+DRR_ALREADY_DRY = 3.0   # v4: lower threshold → JALAA runs on more material (was 6.0)
+
+
+# ─── State ────────────────────────────────────────────────────────────────────
+@dataclass
+class SafaaState:
+    input_path:    str   = ''
+    source_tier:   str   = 'TIER_UNKNOWN'
+    mujawwad_conf: float = 0.0
+    rt60_initial:  float = 0.0
+    drr_before:    float = 0.0
+    drr_after:     float = 0.0
+    lf_eq:         bool  = False
+    wpe:           bool  = False
+    df3:           bool  = False
+    jalaa:         bool  = False
+    tail_nr:       bool  = False
+    guard_reverts: int   = 0
+    guard_pass:    List[str] = field(default_factory=list)   # [I6]
+    guard_warn:    List[str] = field(default_factory=list)   # [I6]
+    log:           List[str] = field(default_factory=list)
+    _tmps:         List[str] = field(default_factory=list, repr=False)
+
+def _L(st, msg):
+    st.log.append(msg); print(msg)
+
+def _track(st, path):
+    """Register a temp path for cleanup. Returns path."""
+    if path and path not in (st.input_path,):
+        st._tmps.append(path)
+    return path
+
+def _cleanup_all(st):
+    for p in st._tmps:
+        try:
+            if p and os.path.exists(p): os.unlink(p)
+        except Exception:
+            pass
+    st._tmps.clear()
+
+
+# ─── FFmpeg helpers ───────────────────────────────────────────────────────────
+def _run(cmd, timeout=600):
+    r = subprocess.run(cmd, capture_output=True, timeout=timeout)
+    return r.returncode, r.stdout, r.stderr
+
+def _tmp(tag, st=None):
+    p = os.path.join(_TMP, f'safaa3_{tag}_{os.getpid()}.wav')
+    if st is not None:
+        st._tmps.append(p)
+    return p
+
+def _cleanup(*paths):
+    for p in paths:
+        try:
+            if p and os.path.exists(p): os.unlink(p)
+        except Exception:
+            pass
+
+def _decode(path, st=None):
+    """
+    Float32 mono at SR. [B2/I9]
+    Uses soundfile when available (faster, native float32).
+    Falls back to ffmpeg pcm_f32le + wave read.
+    try/finally ensures temp file removed on exception.
+    """
+    if not NUMPY_OK:
+        return None
+    t = None
+    try:
+        if SF_OK:
+            # ffmpeg → pcm_f32le temp, then soundfile reads it natively
+            t = os.path.join(_TMP, f'safaa3_dec_{os.getpid()}.wav')
+            rc, _, _ = _run(['ffmpeg', '-y', '-i', path,
+                             '-acodec', 'pcm_f32le',
+                             '-ar', str(SR), '-ac', '1',
+                             '-loglevel', 'error', t])
+            if rc or not os.path.exists(t):
+                return None
+            data, _ = SF.read(t, dtype='float32', always_2d=False)
+            return data
+        elif SCIPY_WAV_OK:
+            # scipy.io.wavfile can read pcm_f32le natively
+            t = os.path.join(_TMP, f'safaa3_dec_{os.getpid()}.wav')
+            rc, _, _ = _run(['ffmpeg', '-y', '-i', path,
+                             '-acodec', 'pcm_f32le',
+                             '-ar', str(SR), '-ac', '1',
+                             '-loglevel', 'error', t])
+            if rc or not os.path.exists(t):
+                return None
+            _, data = _scipy_wavfile.read(t)
+            if data.dtype != np.float32:
+                data = data.astype(np.float32) / np.iinfo(data.dtype).max
+            return data.copy()
+        else:
+            # Final fallback: pcm_s16le → int16 → float32 normalised
+            t = os.path.join(_TMP, f'safaa3_dec_{os.getpid()}.wav')
+            rc, _, _ = _run(['ffmpeg', '-y', '-i', path,
+                             '-acodec', 'pcm_s16le',
+                             '-ar', str(SR), '-ac', '1',
+                             '-loglevel', 'error', t])
+            if rc or not os.path.exists(t):
+                return None
+            import wave as _w
+            with _w.open(t, 'rb') as f:
+                raw = f.readframes(f.getnframes())
+            return np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
+    except Exception:
+        return None
+    finally:
+        if t and os.path.exists(t):
+            try: os.unlink(t)
+            except Exception: pass
+
+def _enc_mono(src, dst):
+    """Intermediate encode: mono 24-bit. [I2]"""
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', src,
+                     '-acodec', WAV_CODEC,
+                     '-ar', str(SR), '-ac', '1',
+                     '-loglevel', 'error', dst])
+    return rc == 0 and os.path.exists(dst)
+
+def _enc_stereo(src, dst):
+    """Final output encode: stereo 24-bit. [I2]"""
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', src,
+                     '-acodec', WAV_CODEC,
+                     '-ar', str(SR), '-ac', '2',
+                     '-loglevel', 'error', dst])
+    return rc == 0 and os.path.exists(dst)
+
+def _rmsdb(s):
+    return float(20 * np.log10(np.sqrt(np.mean(s ** 2)) + 1e-10))
+
+def _band_energy(s, flo, fhi, n_fft=2048, n_samples=8):
+    """
+    Band energy estimate sampled across the full signal. [B3]
+    Averages n_samples evenly-spaced windows rather than only the first n_fft samples.
+    """
+    if len(s) < n_fft:
+        return 0.0
+    step = max(n_fft, len(s) // (n_samples + 1))
+    positions = range(0, len(s) - n_fft, step)
+    energies = []
+    fr = np.fft.rfftfreq(n_fft, 1.0 / SR)
+    mask = (fr >= flo) & (fr <= fhi)
+    for pos in positions:
+        sp = np.abs(np.fft.rfft(s[pos:pos + n_fft], n=n_fft))
+        energies.append(float(np.mean(sp[mask] ** 2) + 1e-20))
+    return float(np.mean(energies)) if energies else 0.0
+
+
+# ─── Stage 1: RT60 (Schroeder backward integration) ──────────────────────────
+def _rt60(samples, sr=SR):
+    """
+    Schroeder backward integration (§3.1).
+    Find -5 dB and -25 dB crossings of backward energy → T20 × 3 = T60.
+    Fallback: linear regression on the decay region. [B5]
+    """
+    if not NUMPY_OK or samples is None or len(samples) < sr * 3:
+        return 0.0
+    fn = int(0.020 * sr)
+    n = len(samples) // fn
+    if n < 30:
+        return 0.0
+
+    energy = np.array([float(np.mean(samples[i * fn:(i + 1) * fn] ** 2)) for i in range(n)])
+    energy = np.maximum(energy, 1e-20)
+    sch = np.cumsum(energy[::-1])[::-1]
+    sch_db = 10 * np.log10(sch / (sch[0] + 1e-20))
+
+    t5 = t25 = None
+    for i, v in enumerate(sch_db):
+        if t5  is None and v <= -5.0:  t5  = i * 0.020
+        if t25 is None and v <= -25.0: t25 = i * 0.020; break
+    if t5 is not None and t25 is not None and t25 > t5:
+        return float(np.clip((t25 - t5) * 3.0, 0.0, 6.0))
+
+    # Fallback: slope estimation on the decay tail [B5]
+    edb = 10 * np.log10(energy)
+    med = float(np.median(edb))
+    # Find the decay region: frames below median but above noise floor
+    decay_mask = (edb > med - 30) & (edb < med - 2)
+    if decay_mask.sum() < 6:
+        return 0.0
+    t_arr = np.where(decay_mask)[0] * 0.020
+    e_arr = edb[decay_mask]
+    slope = float(np.polyfit(t_arr, e_arr, 1)[0])
+    if slope >= -1.0:
+        return 0.0
+    return float(np.clip(60.0 / abs(slope), 0.0, 4.0))
+
+
+def _drr(samples, sr=SR):
+    """
+    DRR: energy ratio early(0-50ms) vs late(50-500ms) (§3.3/§28.6).
+    """
+    if not NUMPY_OK or samples is None:
+        return 0.0
+    en = int(0.050 * sr)
+    ln = int(0.450 * sr)           # late window: 50-500ms
+    step = int(0.200 * sr)
+    vals = []
+    for s in range(0, len(samples) - en - ln, step):
+        er = float(np.sqrt(np.mean(samples[s:s + en] ** 2)) + 1e-10)
+        lr = float(np.sqrt(np.mean(samples[s + en:s + en + ln] ** 2)) + 1e-10)
+        if er > 1e-5 and lr > 1e-5:
+            vals.append(20.0 * np.log10(er / lr))
+    return float(np.median(vals)) if vals else 0.0
+
+
+# ─── Stage 2: Sub-band LF EQ (§3.4) ─────────────────────────────────────────
+def _lf_eq(wav, samples, rt60, st):
+    """
+    Three EQ bands with LF-scaled depth. [I7]
+    §3.4: LF bands have longer RT60 (empirically ~1.3× broadband).
+    Apply the LF multiplier before computing per-band depth.
+    Mujawwad: reduce depth and enforce RT60 floor (§145.3).
+    """
+    if rt60 < RT60_MIN:
+        return wav
+    lf_rt60  = rt60 * 1.30        # §3.4: LF decays ~30% slower [I7]
+    scale    = float(np.clip(lf_rt60 / 0.5, 1.0, 6.0))
+    d_sub    = float(np.clip(scale * 1.0, 1.0, 6.0))
+    d_lo     = float(np.clip(scale * 0.7, 0.7, 4.2))
+    d_room   = float(np.clip(scale * 0.4, 0.4, 2.4))
+
+    if st.mujawwad_conf > 0.6:
+        d_sub *= 0.5; d_lo *= 0.5; d_room *= 0.5
+        if rt60 < MUJ_RT60_FLOOR * 1.5:
+            r = float(np.clip((rt60 - MUJ_RT60_FLOOR) / (MUJ_RT60_FLOOR * 0.5 + 0.001), 0, 1))
+            d_sub *= r; d_lo *= r; d_room *= r
+            _L(st, f'  [S2-LF] Mujawwad floor limiter ratio={r:.2f}')
+
+    flt = []
+    if d_sub  > 0.2: flt.append(f'equalizer=f=150:width_type=o:width=1.4:g=-{d_sub:.1f}')
+    if d_lo   > 0.2: flt.append(f'equalizer=f=300:width_type=o:width=1.2:g=-{d_lo:.1f}')
+    if d_room > 0.2: flt.append(f'equalizer=f=500:width_type=o:width=1.0:g=-{d_room:.1f}')
+    if not flt:
+        return wav
+
+    out = _tmp('s2', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav, '-af', ','.join(flt),
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',  # mono [I2]
+                     '-loglevel', 'error', out])
+    if rc or not os.path.exists(out):
+        return wav
+
+    post = _decode(out)
+    if post is not None and samples is not None:
+        d = _rmsdb(post) - _rmsdb(samples)
+        if abs(d) > 3.0:   # relaxed: LF EQ at high RT60 can legitimately remove >1dB
+            _cleanup(out); st.guard_reverts += 1
+            _L(st, f'  [S2-LF] RMS Δ={d:+.2f}dB — REVERT'); return wav
+
+    st.lf_eq = True
+    _L(st, f'  [S2-LF] ✓ lf_rt60={lf_rt60:.2f}s sub={d_sub:.1f} lo={d_lo:.1f} room={d_room:.1f} dB')
+    return out
+
+
+# ─── Stage 3: WPE (threshold 1.0s, §109.6) ───────────────────────────────────
+def _lra_overlapping(s, frame_s=0.4, hop_s=0.2, sr=SR):
+    """LRA estimate using 50% overlapping frames. [I5]"""
+    fn = int(frame_s * sr)
+    hn = int(hop_s * sr)
+    if len(s) < fn:
+        return 0.0
+    db = [float(20 * np.log10(np.sqrt(np.mean(s[i:i + fn] ** 2)) + 1e-10))
+          for i in range(0, len(s) - fn, hn)]
+    return float(np.percentile(db, 95) - np.percentile(db, 10)) if len(db) >= 4 else 0.0
+
+# S190: hard cap — wall-clock cap on WPE so a slow/atypical file (e.g. RT60=6s,
+# taps=12) can't eat the entire 600s job budget and get SIGKILL'd.
+# WPE runs in a forked child; if it exceeds WPE_TIMEOUT_S we kill just
+# that worker and continue to S4-DF3 with the un-dereverbed audio.
+WPE_TIMEOUT_S = 240
+
+def _wpe_compute_worker(mi, mo, rt60, mujawwad_conf, sr, lra_max, q):
+    """Forked worker: runs wpe_v8 + writes result wav; sends small dict back via queue."""
+    try:
+        if SF_OK:
+            y, _ = SF.read(mi, dtype='float32', always_2d=False)
+        else:
+            import wave as _w
+            with _w.open(mi, 'rb') as f: raw = f.readframes(f.getnframes())
+            y = np.frombuffer(raw, dtype=np.float32).copy()
+
+        if   mujawwad_conf > 0.6: taps, iters = 5, 2
+        elif rt60 > 4.0:           taps, iters = 12, 3
+        elif rt60 > 2.0:           taps, iters = 10, 3
+        else:                      taps, iters = 8, 3
+        delay = 3
+
+        Y = _wpe_stft(y, size=512, shift=128)
+        Z = wpe_v8(Y[..., np.newaxis], taps=taps, delay=delay, iterations=iters)
+        z = _wpe_istft(Z[..., 0], size=512, shift=128)
+        z = z[:len(y)] if len(z) > len(y) else np.pad(z, (0, len(y) - len(z)))
+
+        ld = abs(_lra_overlapping(y) - _lra_overlapping(z))
+        if ld > lra_max:
+            Z2 = wpe_v8(Y[..., np.newaxis], taps=taps, delay=delay, iterations=max(1, iters-1))
+            z2 = _wpe_istft(Z2[..., 0], size=512, shift=128)
+            z2 = z2[:len(y)] if len(z2) > len(y) else np.pad(z2, (0, len(y)-len(z2)))
+            ld2 = abs(_lra_overlapping(y) - _lra_overlapping(z2))
+            if ld2 > lra_max:
+                q.put({'ok': False, 'reason': f'LRA {ld2:.2f}LU after retry — REVERT'})
+                return
+            z = z2; ld = ld2
+
+        if SF_OK:
+            SF.write(mo, z.astype(np.float32), sr, subtype='FLOAT')
+        else:
+            import wave as _w
+            b16 = (np.clip(z, -1, 1) * 32767).astype(np.int16)
+            with _w.open(mo, 'wb') as f:
+                f.setnchannels(1); f.setsampwidth(2); f.setframerate(sr)
+                f.writeframes(b16.tobytes())
+        q.put({'ok': True, 'taps': taps, 'delay': delay, 'iters': iters, 'ld': float(ld)})
+    except Exception as e:
+        q.put({'ok': False, 'reason': f'exception: {e}'})
+
+
+def _wpe(wav, rt60, st):
+    if not WPE_OK:
+        _L(st, '  [S3-WPE] nara_wpe not installed → pip install nara_wpe soundfile')
+        return wav
+    if rt60 < RT60_WPE_MIN:
+        _L(st, f'  [S3-WPE] RT60={rt60:.2f}s < {RT60_WPE_MIN}s — skip (§109.6)')
+        return wav
+
+    _L(st, f'  [S3-WPE] RT60={rt60:.2f}s — running WPE (cap={WPE_TIMEOUT_S}s) [S190]')
+    d = tempfile.mkdtemp(prefix='safaa3_wpe_')
+    try:
+        mi = os.path.join(d, 'in.wav')
+        rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                         '-acodec', 'pcm_f32le', '-ar', str(SR), '-ac', '1',
+                         '-loglevel', 'error', mi])
+        if rc or not os.path.exists(mi):
+            return wav
+
+        mo = os.path.join(d, 'out.wav')
+        ctx = _mp.get_context('fork')
+        q   = ctx.Queue()
+        proc = ctx.Process(
+            target=_wpe_compute_worker,
+            args=(mi, mo, rt60, st.mujawwad_conf, SR, _LRA_MAX_DELTA, q))
+        proc.start()
+        proc.join(WPE_TIMEOUT_S)
+        if proc.is_alive():
+            proc.terminate(); proc.join(5)
+            if proc.is_alive(): proc.kill(); proc.join(5)
+            st.guard_reverts += 1
+            _L(st, f'  [S3-WPE] ⏱ TIMED OUT after {WPE_TIMEOUT_S}s — '
+                   f'skipping WPE, continuing to S4-DF3 [S190]')
+            return wav
+
+        result = q.get() if not q.empty() else {'ok': False, 'reason': 'worker died silently'}
+        if not result.get('ok'):
+            st.guard_reverts += 1
+            _L(st, f"  [S3-WPE] {result.get('reason','failed')} — REVERT")
+            return wav
+
+        out = _tmp('s3', st)
+        if not _enc_mono(mo, out):
+            return wav
+        st.wpe = True
+        _L(st, f"  [S3-WPE] ✓ taps={result['taps']} delay={result['delay']} "
+               f"iters={result['iters']} LRA Δ={result['ld']:.2f}LU")
+        return out
+    except Exception as e:
+        _L(st, f'  [S3-WPE] exception: {e}'); return wav
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+# ─── Stage 4: DF3 smooth adaptive VAD (§22.5 / §106 / RL-01 / RL-16) ─────────
+_ADF_LOUD_T   = -15.0         # dBFS — projecting voice → protect
+_ADF_QUIET_T  = -25.0         # dBFS — soft/breath → clean hard
+_ADF_SNR_GATE = 10.0          # v4: lower gate → more chunks get cleaned (was 12)
+_ADF_CHUNK_S  = 0.050         # 50ms chunks — finer granularity than isteidad 100ms
+# v5: continuous blend — no hard zones, no boundary-only crossfades
+_ADF_SIGMA_DB  = 4.0          # dBFS half-width of loud↔quiet soft transition
+_ADF_SMOOTH_C  = 6            # Gaussian temporal smoothing width in chunks (~300ms @ 50ms/chunk)
+_ADF_GATE_MAX  = 0.70         # max SNR-gate fraction; always retain ≥30% DF3 on clean chunks
+# RL-16: guard bands — restore these from original after blend
+_RL16_BANDS   = [(220, 290), (950, 1100)]   # Hz: Ghunnah nasal pole + formant zone
+
+def _df3_pipe_decode(path, sr):
+    """Decode WAV to float32 mono via ffmpeg pipe — avoids wave/soundfile dep."""
+    r = subprocess.run(
+        ['ffmpeg', '-nostdin', '-y', '-hide_banner', '-loglevel', 'error',
+         '-i', path, '-ar', str(sr), '-ac', '1', '-f', 'f32le', '-'],
+        capture_output=True, timeout=120)
+    if r.returncode or len(r.stdout) < 4:
+        return None
+    return np.frombuffer(r.stdout, dtype=np.float32).copy()
+
+def _stft_restore_bands(processed, original, sr, bands):
+    """
+    RL-16: after DF3 blend, restore specified Hz bands from original.
+    Uses STFT with 50% overlap Hann window — preserves phase coherence.
+    """
+    from numpy.fft import rfft, irfft
+    N = 2048; HOP = N // 2
+    freqs = np.fft.rfftfreq(N, d=1.0/sr)  # Hz per bin
+    restore_mask = np.zeros(len(freqs), dtype=bool)
+    for lo, hi in bands:
+        restore_mask |= (freqs >= lo) & (freqs <= hi)
+
+    win = np.hanning(N).astype(np.float32)
+    min_n = min(len(processed), len(original))
+    p = processed[:min_n].astype(np.float64)
+    o = original[:min_n].astype(np.float64)
+    out = np.zeros(min_n, dtype=np.float64)
+    norm = np.zeros(min_n, dtype=np.float64)
+
+    for s in range(0, min_n - N, HOP):
+        Pf = rfft(p[s:s+N] * win)
+        Of = rfft(o[s:s+N] * win)
+        # S167: soft blend instead of hard copy — avoids tonal whistle when DF3
+        # removes reverb masking context around nasal/formant poles.
+        # 220-290Hz (nasal pole): 60% original (safe, low-freq, well-masked)
+        # 950-1100Hz (formant zone): 15% original — high-risk for unmasked whistle;
+        #   just enough to prevent total nasalization kill without audible tones.
+        for lo, hi in bands:
+            band_mask = (freqs >= lo) & (freqs <= hi)
+            alpha = 0.60 if hi <= 300 else 0.15
+            Pf[band_mask] = alpha * Of[band_mask] + (1.0 - alpha) * Pf[band_mask]
+        frame = irfft(Pf) * win
+        out[s:s+N] += frame; norm[s:s+N] += win**2
+
+    valid = norm > 1e-8
+    out[valid] /= norm[valid]
+    out[~valid] = p[~valid]
+    return out.astype(np.float32)
+
+def _df3(wav, samples, rt60, st, aggressive=False):
+    if not DF3_OK:
+        _L(st, '  [S4-DF3] deep-filter not found — skip'); return wav
+
+    # §106.3 + §79 atten limits — v4: stronger per-class
+    lim = _DF3_LIM_MUJAWWAD if st.mujawwad_conf > 0.6 else _DF3_LIM_MURATTAL
+    if aggressive:
+        # Raise the numeric caps, but they still pass through min(x, lim) —
+        # for Mujawwad sources lim=8 so this changes nothing for them; the
+        # ornamentation protection is preserved by construction, not by a
+        # separate check. Only Murattal-style sources (lim=24) get headroom.
+        a_loud  = min(16, lim)
+        a_mid   = min(22, lim)
+        a_quiet = min(28, lim + 14)
+        a_trans = min(20, lim)
+    else:
+        a_loud  = min(10, lim)       # was 8
+        a_mid   = min(18, lim)       # was 15
+        a_quiet = min(24, lim + 10)  # was 20
+        a_trans = min(14, lim)       # v4: new transition class between loud/mid
+    if st.mujawwad_conf > 0.6:
+        a_loud  = min(a_loud,  8)
+        a_mid   = min(a_mid,  10)
+        a_quiet = min(a_quiet, 14)
+        a_trans = min(a_trans,  9)
+
+    d = tempfile.mkdtemp(prefix='safaa3_df3_')
+    try:
+        # ── Prepare pcm_s16le mono input ──────────────────────────────────
+        fi = os.path.join(d, 'in.wav')
+        rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                         '-acodec', 'pcm_s16le', '-ar', str(SR), '-ac', '1',
+                         '-loglevel', 'error', fi])
+        if rc or not os.path.exists(fi):
+            return wav
+        mono = _df3_pipe_decode(fi, SR)
+        if mono is None:
+            return wav
+        total = len(mono)
+
+        # ── VAD — 50ms chunks with SNR gate (§22.5) ──────────────────────
+        CHUNK = int(_ADF_CHUNK_S * SR)
+        nc = max(1, total // CHUNK)
+        # Estimate noise floor from quietest 10% of chunks
+        rms_db = np.array([
+            20.0 * np.log10(np.sqrt(np.mean(mono[i*CHUNK:(i+1)*CHUNK]**2)) + 1e-12)
+            for i in range(nc)])
+        noise_floor = float(np.percentile(rms_db, 10))
+
+        # §22.5 SNR gate value (used later in continuous blend)
+        chunk_snr = rms_db - noise_floor
+        snr_gate  = (_ADF_SNR_GATE + 3.0) if aggressive else _ADF_SNR_GATE
+
+        # Stats for logging only — no longer used for hard assignment
+        n_loud  = int((rms_db >  _ADF_LOUD_T).sum())
+        n_quiet = int((rms_db <= _ADF_QUIET_T).sum())
+        n_mid   = nc - n_loud - n_quiet
+        n_clean = int((chunk_snr >= snr_gate).sum())
+        _L(st, f'  [S4-ADF] 50ms chunks: LOUD={n_loud} MID={n_mid} '
+               f'QUIET={n_quiet} CLEAN(snr-gate)={n_clean}  nf={noise_floor:.1f}dBFS')
+
+        # ── 3 parallel DF passes with per-class flags ─────────────────────
+        df_out = {}
+        def _run_pass(cls, atten, pf=False, pf_beta=0.02):
+            od = os.path.join(d, cls); os.makedirs(od, exist_ok=True)
+            cmd = [_DF3_CLI_BIN, '--atten-lim-db', str(atten)]
+            if pf:
+                cmd += ['--pf', '--pf-beta', str(pf_beta)]
+            cmd += ['-o', od, fi]
+            r2 = subprocess.run(cmd, capture_output=True, timeout=600)
+            wp = os.path.join(od, 'in.wav')
+            if r2.returncode or not os.path.exists(wp):
+                _L(st, f'  [S4-ADF] {cls} pass failed — using source')
+                return cls, mono.copy()
+            arr = _df3_pipe_decode(wp, SR)
+            if arr is None:
+                _L(st, f'  [S4-ADF] {cls} decode failed — using source')
+                return cls, mono.copy()
+            pf_tag = ' +PF' if pf else ''
+            _L(st, f'  [S4-ADF] {cls:6s} {atten:2d}dB{pf_tag} ✓  '
+                   f'max={np.max(np.abs(arr)):.4f}')
+            return cls, arr
+
+        with ThreadPoolExecutor(max_workers=4) as ex:
+            futs = [
+                ex.submit(_run_pass, 'loud',  a_loud,  aggressive, 0.02),
+                ex.submit(_run_pass, 'mid',   a_mid,   aggressive, 0.02),
+                ex.submit(_run_pass, 'quiet', a_quiet, True, 0.04),   # PF quiet always
+                ex.submit(_run_pass, 'trans', a_trans, aggressive, 0.02),
+            ]
+            for fut in as_completed(futs):
+                cls, arr = fut.result()
+                df_out[cls] = arr
+
+        # ── Continuous soft-weight blend (v5) ────────────────────────────
+        # Root cause of "يروح ويجي": hard zone assignment kept attenuation
+        # constant inside each zone; crossfade only fired AT boundaries.
+        # Fix: compute soft sigmoid weights from RMS per chunk, Gaussian-smooth
+        # them temporally (~300ms window), interpolate to sample level.
+        # Every individual sample now has a uniquely blended attenuation that
+        # tracks the signal continuously — no zones, no boundaries, no jumps.
+
+        def _sig(x):
+            return 1.0 / (1.0 + np.exp(-np.clip(x.astype(np.float64), -20, 20)))
+
+        def _gauss1d(arr, sig):
+            """Gaussian kernel smoothing — pure numpy, no scipy dependency."""
+            sig = max(0.5, float(sig))
+            r = max(1, int(3.5 * sig))
+            t = np.arange(-r, r + 1, dtype=np.float64)
+            k = np.exp(-0.5 * (t / sig) ** 2); k /= k.sum()
+            return np.convolve(arr.astype(np.float64), k, mode='same')
+
+        SIGMA = _ADF_SIGMA_DB    # dBFS half-width of transition (4 dB)
+        SC    = _ADF_SMOOTH_C    # Gaussian temporal smoothing in chunks (~300ms)
+
+        # Raw soft weights per chunk (sum not forced to 1 yet)
+        wL = _sig((rms_db - _ADF_LOUD_T)  / SIGMA)   # 1 = very loud
+        wQ = _sig((_ADF_QUIET_T - rms_db) / SIGMA)   # 1 = very quiet
+        wM = np.clip(1.0 - wL - wQ, 0.0, 1.0)        # mid fills the gap
+
+        # Normalize to sum = 1 per chunk
+        wS = wL + wM + wQ + 1e-8
+        wL /= wS; wM /= wS; wQ /= wS
+
+        # Gaussian temporal smoothing across chunks — this is what eliminates
+        # the step-function zones; after smoothing the weights transition over
+        # ~300ms even when the signal level changes abruptly.
+        wL = _gauss1d(wL, SC); wM = _gauss1d(wM, SC); wQ = _gauss1d(wQ, SC)
+        wS2 = wL + wM + wQ + 1e-8
+        wL /= wS2; wM /= wS2; wQ /= wS2
+
+        # Interpolate chunk-level weights → sample level (linear, smooth)
+        # Anchored at chunk centres so edges don't overshoot
+        t_c = (np.arange(nc, dtype=np.float64) + 0.5) * CHUNK
+        t_s = np.arange(total, dtype=np.float64)
+        wL_s = np.interp(t_s, t_c, wL)
+        wM_s = np.interp(t_s, t_c, wM)
+        wQ_s = np.interp(t_s, t_c, wQ)
+
+        # Three-way blend at sample level
+        min_n = min(total, *(len(df_out[c]) for c in ('loud', 'mid', 'quiet', 'trans')))
+        blended = (
+            wL_s[:min_n] * df_out['loud'][:min_n].astype(np.float64) +
+            wM_s[:min_n] * df_out['mid'][:min_n].astype(np.float64)  +
+            wQ_s[:min_n] * df_out['quiet'][:min_n].astype(np.float64)
+        )
+
+        # SNR gate: for already-clean regions, blend toward 'trans' (light-touch
+        # pass) rather than raw mono — avoids re-introducing un-processed noise.
+        # Gate weight is also Gaussian-smoothed so it ramps gradually.
+        w_gate = np.clip((chunk_snr - snr_gate) / 8.0, 0.0, 1.0)
+        w_gate = _gauss1d(w_gate, SC * 2)                 # wider smooth for gate
+        w_gate_s = np.clip(np.interp(t_s, t_c, w_gate), 0.0, _ADF_GATE_MAX)
+        blended[:min_n] = (
+            (1.0 - w_gate_s[:min_n]) * blended[:min_n] +
+            w_gate_s[:min_n] * df_out['trans'][:min_n].astype(np.float64)
+        )
+
+        _L(st, f'  [S4-ADF] v5 continuous blend: σ_db={SIGMA:.1f}dB '
+               f'smooth={SC}×{int(_ADF_CHUNK_S*1000)}ms={int(SC*_ADF_CHUNK_S*1000)}ms '
+               f'gate≤{int(_ADF_GATE_MAX*100)}%')
+
+        # ── RL-16: restore Ghunnah guard bands from original ──────────────
+        blended_f32 = np.where(np.isfinite(blended), blended, 0.0).astype(np.float32)
+        blended_f32 = _stft_restore_bands(blended_f32, mono[:min_n], SR, _RL16_BANDS)
+        _L(st, f'  [S4-ADF] RL-16 bands restored: '
+               f'{", ".join(f"{lo}-{hi}Hz" for lo,hi in _RL16_BANDS)}')
+
+        # ── Silence guard ─────────────────────────────────────────────────
+        if float(np.max(np.abs(blended_f32))) < 1e-4:
+            _L(st, '  [S4-ADF] ⚠ silent result — fallback to mid pass')
+            blended_f32 = df_out['mid'][:min_n].astype(np.float32)
+
+        # ── Encode to pcm_s24le stereo ────────────────────────────────────
+        out = _tmp('s4', st)
+        r3 = subprocess.run(
+            ['ffmpeg', '-nostdin', '-y', '-hide_banner', '-loglevel', 'error',
+             '-f', 'f32le', '-ar', str(SR), '-ac', '1', '-i', '-',
+             '-ar', str(SR), '-ac', '2', '-acodec', 'pcm_s24le', out],
+            input=blended_f32.tobytes(), capture_output=True, timeout=120)
+        if r3.returncode or not os.path.exists(out):
+            return wav
+
+        delta = _rmsdb(blended_f32) - _rmsdb(mono)
+        st.df3 = True
+        _L(st, f'  [S4-ADF] ✓  loud={a_loud}dB mid={a_mid}dB quiet={a_quiet}dB '
+               f'RMS Δ={delta:+.2f}dB')
+        return out
+    except Exception as e:
+        _L(st, f'  [S4-DF3] exception: {e}'); return wav
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+# ─── Stage 5: JALAA per-frame DRR gate (§28.6) ───────────────────────────────
+def _jalaa(wav, samples, rt60, drr_before, st):
+    """
+    Per-frame DRR classification → calibrated afftdn on reverb-dominated frames.
+    [B1] Late window corrected to 450ms (50-500ms per §3.3).
+    [I10] Skip entirely if DRR already > DRR_ALREADY_DRY (room is dry enough).
+    """
+    if not NUMPY_OK or samples is None or rt60 < 0.30:
+        _L(st, f'  [S5-JALAA] RT60={rt60:.2f}s < 0.30 — skip'); return wav
+    if drr_before > DRR_ALREADY_DRY:
+        _L(st, f'  [S5-JALAA] DRR={drr_before:.1f}dB already dry — skip [I10]'); return wav
+
+    fn = int(0.200 * SR)
+    en = int(0.050 * SR)
+    ln = int(0.450 * SR)          # [B1] was 0.150 → 450ms (50-500ms window)
+    n  = len(samples) // fn
+    if n < 5:
+        return wav
+
+    nf_vals = []
+    for i in range(n):
+        s = i * fn; chunk = samples[s:s + fn]
+        if len(chunk) < en + ln:
+            continue
+        er = float(np.sqrt(np.mean(chunk[:en] ** 2)) + 1e-10)
+        lr = float(np.sqrt(np.mean(chunk[en:en + ln] ** 2)) + 1e-10)
+        if er < 1e-5: continue
+        if 20.0 * np.log10(er / lr) < 3.0:   # reverb-dominated
+            nf_vals.append(float(20 * np.log10(lr + 1e-10)))
+
+    if not nf_vals:
+        _L(st, '  [S5-JALAA] no reverb frames — skip'); return wav
+
+    nf = float(np.clip(float(np.median(nf_vals)) + 3, -72, -20))  # v4: floor raised -25→-20
+    nr = 3 if rt60 > RT60_AGGR else 2   # v4: base raised (was 2/1)
+    if st.mujawwad_conf > 0.6: nr = max(1, nr - 1)
+
+    # v4: two-pass JALAA — first pass stationary, second adaptive tracking
+    out = _tmp('s5a', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                     '-af', f'afftdn=nr={nr}:nf={nf:.0f}:nt=w:tn=1',
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
+                     '-loglevel', 'error', out])
+    if rc or not os.path.exists(out):
+        return wav
+
+    out2 = _tmp('s5b', st)
+    rc2, _, _ = _run(['ffmpeg', '-y', '-i', out,
+                      '-af', f'afftdn=nr={max(1,nr-1)}:nf={nf+3:.0f}:nt=w:tn=1',
+                      '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
+                      '-loglevel', 'error', out2])
+    if rc2 or not os.path.exists(out2):
+        pass  # keep single-pass result
+    else:
+        _cleanup(out); out = out2
+
+    post = _decode(out)
+    if post is not None:
+        d = _rmsdb(post) - _rmsdb(samples)
+        if abs(d) > _RMS_MAX_DELTA:
+            _cleanup(out); st.guard_reverts += 1
+            _L(st, f'  [S5-JALAA] RMS Δ={d:+.2f}dB — REVERT'); return wav
+
+    st.jalaa = True
+    _L(st, f'  [S5-JALAA] ✓ reverb_frames={len(nf_vals)}/{n} nf={nf:.0f}dB nr={nr}')
+    return out
+
+
+# ─── Stage 6: Tail floor NR — 2-stage (afftdn + anlmdn) ─────────────────────
+def _tailnr(wav, samples, rt60, st):
+    """
+    2-stage NR pipeline (§83.3 order: stationary → non-stationary):
+      Stage A: afftdn with nt=w (adaptive tracking) for stationary noise floor.
+      Stage B: anlmdn (s=7:p=3:r=15) for transient/non-stationary residuals.
+    RT60-scaled nr: base=2, +1 per 1.5s RT60 above threshold, cap=5 (§5.3: 20dB/nr max).
+    [I3] If JALAA already ran, reduce nr by 1 to avoid double-attenuation.
+    RL-16: sibilant SNR guard — revert if Safir/Tafasshi band drops > 2dB.
+    """
+    if rt60 < RT60_TAILNR or samples is None or not NUMPY_OK:
+        return wav
+    fn = int(0.200 * SR)
+    overall = _rmsdb(samples)
+    fdb = np.array([float(20 * np.log10(np.sqrt(np.mean(samples[i:i+fn]**2)) + 1e-10))
+                    for i in range(0, len(samples) - fn, fn)])
+    quiet = fdb[fdb < overall - 10]
+    if len(quiet) == 0:
+        return wav
+
+    nf = float(np.clip(float(np.median(quiet)) + 4, -72, -25))
+    # v4: RT60-scaled nr — higher cap (8 was 5), stronger base
+    nr = min(8, 3 + int((rt60 - RT60_TAILNR) / 1.2))   # was cap=5, base=2, step=1.5
+    if st.mujawwad_conf > 0.6: nr = max(1, nr - 1)
+    if st.jalaa:               nr = max(1, nr - 1)   # [I3]
+
+    # ── Stage A: afftdn with adaptive noise tracking ──────────────────────
+    out_a = _tmp('s6a', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                     '-af', f'afftdn=nr={nr}:nf={nf:.0f}:nt=w:om=o',
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                     '-loglevel', 'error', out_a])
+    if rc or not os.path.exists(out_a):
+        return wav
+
+    # ── Stage B: anlmdn for non-stationary residuals ──────────────────────
+    # anlmdn: s=patch size, p=context, r=search radius (§95 KB)
+    # Scale strength with nr: gentle (s=5) at nr<=2, standard (s=7) at nr>2
+    patch = 7 if nr > 2 else 5
+    out_b = _tmp('s6b', st)
+    rc2, _, _ = _run(['ffmpeg', '-y', '-i', out_a,
+                      '-af', f'anlmdn=s={patch}:p=3:r=15:m=1',
+                      '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                      '-loglevel', 'error', out_b])
+    if rc2 or not os.path.exists(out_b):
+        # Stage B failed — commit Stage A only
+        st.tail_nr = True
+        jalaa_note = ' (JALAA-adj)' if st.jalaa else ''
+        _L(st, f'  [S6-tailNR] ✓ 1-stage nr={nr}{jalaa_note} nf={nf:.0f}dB  '
+               f'[anlmdn failed — Stage A only]')
+        return out_a
+
+    # ── Sibilant SNR guard (RL-16 spirit) ─────────────────────────────────
+    post_s = _decode(out_b)
+    if post_s is not None:
+        sib_orig = _band_energy(samples, 3500, 8000)
+        sib_post = _band_energy(post_s,  3500, 8000)
+        sib_drop = sib_post - sib_orig
+        if sib_drop < -2.0:
+            _L(st, f'  [S6-tailNR] sibilant drop {sib_drop:+.1f}dB — '
+                   f'revert Stage B, keep Stage A')
+            _cleanup(out_b)
+            st.tail_nr = True
+            _L(st, f'  [S6-tailNR] ✓ nr={nr} nf={nf:.0f}dB [Stage A only]')
+            return out_a
+
+    # ── Stage C: v4 — gentle anlmdn second pass for reverb tail residual ────
+    out_c = _tmp('s6c', st)
+    rc3, _, _ = _run(['ffmpeg', '-y', '-i', out_b,
+                      '-af', f'anlmdn=s=5:p=3:r=10:m=1',
+                      '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                      '-loglevel', 'error', out_c])
+    if rc3 or not os.path.exists(out_c):
+        pass  # keep Stage B
+    else:
+        post_c = _decode(out_c)
+        if post_c is not None:
+            sib_c = _band_energy(post_c, 3500, 8000)
+            sib_drop_c = sib_c - _band_energy(samples, 3500, 8000)
+            if sib_drop_c >= -2.5:
+                _cleanup(out_b); out_b = out_c
+            else:
+                _cleanup(out_c)
+
+    _cleanup(out_a)
+    st.tail_nr = True
+    jalaa_note = ' (JALAA-adj)' if st.jalaa else ''
+    _L(st, f'  [S6-tailNR] ✓ 3-stage nr={nr}{jalaa_note} nf={nf:.0f}dB '
+           f'patch={patch} rt60={rt60:.1f}s')
+    return out_b
+
+
+# ─── Stage 6.5: Wind noise removal (v4) ─────────────────────────────────────
+def _windnr(wav, samples, rt60, st):
+    """
+    Targets wind noise: broadband low-frequency energy (30–400Hz)
+    that DF3 doesn't clean because it looks like speech sub-harmonics.
+
+    Strategy:
+      A) Hard HPF at 60Hz to kill sub-rumble
+      B) Spectral gate on 60–300Hz band: estimate wind energy from
+         speech-inactive frames, subtract with 6dB headroom
+      C) Gentle de-essing inversion below 400Hz (anlmdn lightweight)
+      D) Guard: if low-band energy drops > 8dB → revert (protect bass vowels)
+    """
+    if samples is None or not NUMPY_OK:
+        _L(st, '  [S6.5-WIND] no samples — skip'); return wav
+
+    # Measure wind energy spectrally — find steady LF floor even during speech
+    # Wind = energy in 60-300Hz that doesn't modulate with speech (stays constant)
+    fn  = int(0.100 * SR)
+    n   = len(samples) // fn
+    overall_db = _rmsdb(samples)
+
+    # Low-band energy per frame (60–300Hz via FFT)
+    lo_energy_db = []
+    for i in range(n):
+        frame = samples[i*fn:(i+1)*fn]
+        spec  = np.abs(np.fft.rfft(frame, n=fn)) / fn   # normalize by N
+        freqs = np.fft.rfftfreq(fn, d=1.0/SR)
+        lo_mask = (freqs >= 60) & (freqs <= 300)
+        lo_rms  = float(np.sqrt(np.mean(spec[lo_mask]**2) + 1e-20))
+        lo_energy_db.append(20 * np.log10(lo_rms + 1e-10))
+
+    lo_energy_db = np.array(lo_energy_db)
+    # Wind floor = the bottom 20th percentile of LF energy across all frames
+    # Wind is the *minimum* steady LF that persists regardless of speech activity
+    wind_floor_db = float(np.percentile(lo_energy_db, 20))
+
+    # Only apply if wind floor is detectable (above -62dBFS in LF band)
+    if wind_floor_db < -62.0:
+        _L(st, f'  [S6.5-WIND] LF floor={wind_floor_db:.1f}dBFS — inaudible, skip'); return wav
+
+    # Baseline for guards must be the wav INPUT (already DF3/tailNR processed),
+    # NOT s_orig — comparing against original would fire on DF3's own changes.
+    wav_pre = _decode(wav)
+    if wav_pre is None:
+        _L(st, '  [S6.5-WIND] decode failed — skip'); return wav
+
+    lo_before  = _band_energy(wav_pre, 60,  200)   # wind zone: 60-200Hz
+    mid_before = _band_energy(wav_pre, 250, 900)   # vowel zone: protect formants
+
+    # Wind noise in mosque/outdoor recordings sits below 200Hz.
+    # afftdn nt=w is too broad (hits vowel formants) — use HPF + low-shelf instead.
+    # Stage A: HPF at 80Hz (2-pole) — kills sub-rumble below speech
+    tmp_a = _tmp('s65a', st)
+    rc, _, _ = _run(['ffmpeg', '-y', '-i', wav,
+                     '-af', 'highpass=f=80:poles=2',
+                     '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                     '-loglevel', 'error', tmp_a])
+    if rc or not os.path.exists(tmp_a):
+        _L(st, '  [S6.5-WIND] HPF failed — skip'); return wav
+
+    # Stage B: low-shelf EQ targeting 80-200Hz wind band.
+    # Depth scales with severity: heavy wind → up to -8dB shelf; faint → -3dB.
+    # shelf at 200Hz, so everything above is unaffected.
+    shelf_db = -8.0 if wind_floor_db > -35 else (-5.0 if wind_floor_db > -45 else -3.0)
+    tmp_b = _tmp('s65b', st)
+    rc2, _, _ = _run(['ffmpeg', '-y', '-i', tmp_a,
+                      '-af', (f'equalizer=f=100:width_type=o:width=1.0:g={shelf_db:.0f},'
+                              f'equalizer=f=180:width_type=o:width=0.8:g={shelf_db*0.5:.0f}'),
+                      '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                      '-loglevel', 'error', tmp_b])
+    if rc2 or not os.path.exists(tmp_b):
+        _L(st, '  [S6.5-WIND] shelf EQ failed — keep HPF only')
+        result = tmp_a
+    else:
+        # Stage C: very gentle anlmdn for residual wind texture (s=2, conservative)
+        tmp_c = _tmp('s65c', st)
+        rc3, _, _ = _run(['ffmpeg', '-y', '-i', tmp_b,
+                          '-af', 'anlmdn=s=2:p=2:r=6:m=1',
+                          '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                          '-loglevel', 'error', tmp_c])
+        result = tmp_c if (rc3 == 0 and os.path.exists(tmp_c)) else tmp_b
+
+    # Dual guard:
+    #   Wind zone (60-200Hz): allow up to -15dB — this IS the wind band
+    #   Vowel zone (250-900Hz): max -2dB — protect speech formants tightly
+    post_s = _decode(result)
+    if post_s is not None:
+        lo_after  = _band_energy(post_s,  60,  200)
+        mid_after = _band_energy(post_s, 250,  900)
+        if lo_before > 1e-15:
+            lo_drop  = 10 * np.log10(lo_after  / (lo_before  + 1e-20) + 1e-20)
+            if lo_drop < -15.0:
+                for t in [tmp_a, tmp_b, tmp_c if 'tmp_c' in dir() else None]:
+                    if t: _cleanup(t)
+                st.guard_reverts += 1
+                _L(st, f'  [S6.5-WIND] wind-zone over-removal {lo_drop:+.1f}dB — REVERT')
+                return wav
+        if mid_before > 1e-15:
+            mid_drop = 10 * np.log10(mid_after / (mid_before + 1e-20) + 1e-20)
+            if mid_drop < -2.0:
+                for t in [tmp_a, tmp_b, tmp_c if 'tmp_c' in dir() else None]:
+                    if t: _cleanup(t)
+                st.guard_reverts += 1
+                _L(st, f'  [S6.5-WIND] vowel band drop {mid_drop:+.1f}dB — REVERT')
+                return wav
+            _L(st, f'  [S6.5-WIND] guards ✓  wind={lo_drop:+.1f}dB  vowel={mid_drop:+.1f}dB')
+
+    if result not in (tmp_a,):
+        _cleanup(tmp_a)
+    if 'tmp_b' in dir() and result not in (tmp_b,):
+        _cleanup(tmp_b)
+    _L(st, f'  [S6.5-WIND] ✓ floor={wind_floor_db:.1f}dBFS  shelf={shelf_db:.0f}dB @100-180Hz')
+    return result
+
+
+# ─── Stage 7: Arabic phoneme guards (§35/§52/§143/§152) ──────────────────────
+def _arabic_guards(orig_s, proc_wav, st):
+    """
+    Seven guards verifying Tajweed-critical features survived processing.
+    WARN-only by design — reverb is worse than mild phoneme loss.
+    Results stored in st.guard_pass / st.guard_warn (structured). [I6]
+    [B3] _band_energy() now samples across full file.
+    [B4] G4 Ra-trill scans full audio in overlapping 1s windows.
+    """
+    if not NUMPY_OK or orig_s is None:
+        return proc_wav
+    proc_s = _decode(proc_wav)
+    if proc_s is None:
+        return proc_wav
+    n = min(len(orig_s), len(proc_s))
+    o = orig_s[:n]; p = proc_s[:n]
+
+    def chk(name, cond, detail):
+        entry = f'{name}: {detail}'
+        if cond:
+            st.guard_pass.append(entry); _L(st, f'  [S7-PASS] {entry}')
+        else:
+            st.guard_warn.append(entry); _L(st, f'  [S7-WARN] ⚠ {entry}')
+
+    # G1 Ghunnah 250-300 Hz (§152.3)
+    go = _band_energy(o, 250, 300); gp = _band_energy(p, 250, 300)
+    if go > 1e-15:
+        d = 10 * np.log10(gp / go + 1e-20)
+        chk('G1-Ghunnah', d >= -3.0, f'{d:+.1f}dB {"✓" if d>=-3 else "⚠ nasal murmur lost"}')
+
+    # G2 Ikhfa 250-400 Hz (§52.5)
+    io = _band_energy(o, 250, 400); ip = _band_energy(p, 250, 400)
+    if io > 1e-15:
+        d = 10 * np.log10(ip / io + 1e-20)
+        chk('G2-Ikhfa', d >= -4.0, f'{d:+.1f}dB {"✓" if d>=-4 else "⚠ ikhfa nasalisation lost"}')
+
+    # G3 Qalqalah burst (§52.7, §143 Class 2)
+    sil_n = int(0.020 * SR); bst_n = int(0.030 * SR)
+    total = viol = 0
+    for i in range(0, n - sil_n - bst_n, sil_n):
+        sr_ = float(np.sqrt(np.mean(o[i:i + sil_n] ** 2)) + 1e-10)
+        br_ = float(np.sqrt(np.mean(o[i + sil_n:i + sil_n + bst_n] ** 2)) + 1e-10)
+        if sr_ < 0.005 and br_ > sr_ * 5:
+            total += 1
+            bp = float(np.sqrt(np.mean(p[i + sil_n:i + sil_n + bst_n] ** 2)) + 1e-10)
+            if 20 * np.log10(bp / br_ + 1e-10) < -6.0: viol += 1
+    if total > 0:
+        pct = viol / total * 100
+        chk('G3-Qalqalah', pct <= 20,
+            f'{total} bursts {pct:.0f}% violated {"✓" if pct<=20 else "⚠ echo burst attenuated"}')
+
+    # G4 Ra trill AM 25-35 Hz — FULL AUDIO scan in overlapping 1s windows [B4]
+    win = SR; hop = SR // 2
+    am_ratios = []
+    for pos in range(0, n - win, hop):
+        ef_o = np.abs(np.fft.rfft(np.abs(o[pos:pos + win]), n=win))
+        ef_p = np.abs(np.fft.rfft(np.abs(p[pos:pos + win]), n=win))
+        am_o = float(np.mean(ef_o[25:36])); am_p = float(np.mean(ef_p[25:36]))
+        if am_o > 1e-8:
+            am_ratios.append(am_p / am_o)
+    if am_ratios:
+        r = float(np.median(am_ratios))
+        chk('G4-Ra-trill', r >= 0.70,
+            f'AM ratio={r:.2f} (median over {len(am_ratios)} windows) '
+            f'{"✓" if r>=0.70 else "⚠ ر trill may be smeared"}')
+
+    # G5 Safir 5.5-12 kHz — ص س ز (§152.3)
+    so = _band_energy(o, 5500, 12000); sp = _band_energy(p, 5500, 12000)
+    if so > 1e-15:
+        d = 10 * np.log10(sp / so + 1e-20)
+        chk('G5-Safir', d >= -5.0,
+            f'{d:+.1f}dB {"✓" if d>=-5 else "⚠ ص س ز may be dull"}')
+
+    # G6 Tafasshi 3-8 kHz — ش (§152.3)
+    to = _band_energy(o, 3000, 8000); tp = _band_energy(p, 3000, 8000)
+    if to > 1e-15:
+        d = 10 * np.log10(tp / to + 1e-20)
+        chk('G6-Tafasshi', d >= -4.0,
+            f'{d:+.1f}dB {"✓" if d>=-4 else "⚠ ش may lose spread"}')
+
+    # G7 Izhar silence count (§52.5.1)
+    def _sil_count(s):
+        fn_ = int(0.010 * SR)
+        db = np.array([float(20 * np.log10(np.sqrt(np.mean(s[i:i + fn_] ** 2)) + 1e-10))
+                       for i in range(0, len(s) - fn_, fn_)])
+        med = float(np.median(db)); c = 0; in_s = False; sl = 0
+        for v in db:
+            if v < med - 18: in_s = True; sl += 1
+            else:
+                if in_s and 2 <= sl <= 8: c += 1
+                in_s = False; sl = 0
+        return c
+    sc_o = _sil_count(o); sc_p = _sil_count(p)
+    if sc_o > 0:
+        r = sc_p / sc_o
+        chk('G7-Izhar', r >= 0.70,
+            f'silences {sc_o}→{sc_p} ({r:.0%}) {"✓" if r>=0.70 else "⚠ words may run together"}')
+
+    total_g = len(st.guard_pass) + len(st.guard_warn)
+    if st.guard_warn:
+        _L(st, f'  [S7] {len(st.guard_warn)}/{total_g} warnings — check output for Tajweed artifacts')
+    else:
+        _L(st, f'  [S7] All {total_g} guards passed ✓')
+    return proc_wav
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+def process(input_path, output_path, source_tier='TIER_UNKNOWN',
+            mujawwad_conf=0.0, force_rt60=0.0, verbose=True, aggressive=False):
+    """
+    الصفاء v3 — main entry point.
+    Returns SafaaState with full diagnostics.
+    All temp files are tracked and cleaned up on exit. [I8]
+    """
+    st = SafaaState(input_path=input_path, source_tier=source_tier,
+                    mujawwad_conf=mujawwad_conf)
+    _L(st, f'\n{"═"*60}')
+    _L(st, f'  الصفاء {__version__} — إزالة الصدى والريفيرب')
+    _L(st, f'  Input   : {Path(input_path).name}')
+    _L(st, f'  Tier    : {source_tier}   Mujawwad: {mujawwad_conf:.2f}')
+    _L(st, f'{"═"*60}')
+    if aggressive:
+        _L(st, '  [AGGRESSIVE] DF3 attenuation caps + post-filter coverage widened '
+                '(Mujawwad ceiling unchanged — protected by design)')
+
+    s_orig = _decode(input_path)
+    if s_orig is None:
+        _L(st, '  ERROR: decode failed'); return st
+
+    try:
+        cur = input_path
+
+        # S1: RT60 + DRR
+        rt60 = force_rt60 if force_rt60 > 0 else _rt60(s_orig)
+        st.rt60_initial = rt60; st.drr_before = _drr(s_orig)
+        _L(st, f'  [S1] RT60={rt60:.2f}s  DRR={st.drr_before:.1f}dB')
+
+        if rt60 < RT60_MIN:
+            _L(st, f'  [S1] RT60 < {RT60_MIN}s — no processing needed')
+            _enc_stereo(input_path, output_path); return st
+
+        # S2 Sub-band LF EQ
+        cur = _lf_eq(cur, s_orig, rt60, st)
+        # S3 WPE
+        cur = _wpe(cur, rt60, st)
+        # S4 DF3 (parallel)
+        _s4 = _decode(cur); s4 = _s4 if _s4 is not None else s_orig
+        cur = _df3(cur, s4, rt60, st, aggressive=aggressive)
+        # S5 JALAA (DRR-weighted, corrected late window)
+        _s5 = _decode(cur); s5 = _s5 if _s5 is not None else s_orig
+        cur = _jalaa(cur, s5, rt60, st.drr_before, st)
+        # S6 Tail NR (JALAA-aware)
+        _s6 = _decode(cur); s6 = _s6 if _s6 is not None else s_orig
+        cur = _tailnr(cur, s6, rt60, st)
+        # S6.5 Wind noise removal — v4 addition
+        cur = _windnr(cur, s_orig, rt60, st)
+        # S7 Arabic guards
+        cur = _arabic_guards(s_orig, cur, st)
+
+        # Final stereo encode + S8a dynamic normalizer + S8b volume boost
+        # S8a: dynaudnorm final level evenness (v5: DF3 now self-smooth; dynaudnorm is a safety net)
+        #   f=500ms window (long=smooth), m=10 max gain cap (20dB safety),
+        #   p=0.92 peak target, r=0.0 (peak mode, not RMS — preserves Tajweed transients)
+        # S8b: Aggressive mode = 4x boost (7.40) vs standard (1.85); limiter tightened
+        _s8_vol = 7.40 if aggressive else 1.85
+        _s8_lim = 0.94 if aggressive else 0.89
+        _s8_norm = 'dynaudnorm=f=500:g=31:p=0.92:m=10:r=0.0:b=1,'
+        _s8_af  = (_s8_norm +
+                   f'volume={_s8_vol},'
+                   'equalizer=f=2000:width_type=o:width=1.0:g=1.5,'
+                   'equalizer=f=300:width_type=o:width=1.0:g=-1.0,'
+                   f'alimiter=level_in=1:level_out=1:limit={_s8_lim}:attack=5:release=50')
+        _s8_mode = 'AGGRESSIVE 4x' if aggressive else 'standard'
+        _L(st, f'  [S8a] dynaudnorm f=500ms m=10 p=0.92 — level evenness pass')
+        _L(st, f'  [S8b] volume boost={_s8_vol:.2f} ({_s8_mode})')
+        rc, _, err = _run(['ffmpeg', '-y', '-i', cur,
+                           '-af', _s8_af,
+                           '-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
+                           '-loglevel', 'error', output_path])
+        if rc:
+            _L(st, f'  ERROR: final encode: {err[:80]}'); return st
+
+        sf_ = _decode(output_path)
+        if sf_ is not None: st.drr_after = _drr(sf_)
+
+        _L(st, f'\n{"═"*60}')
+        _L(st, f'  الصفاء {__version__} ✓')
+        _L(st, f'  RT60  : {st.rt60_initial:.2f}s')
+        _L(st, f'  DRR   : {st.drr_before:.1f} → {st.drr_after:.1f} dB  '
+              f'(Δ{st.drr_after - st.drr_before:+.1f})')
+        _L(st, f'  LF={st.lf_eq} WPE={st.wpe} DF3={st.df3} JALAA={st.jalaa} tailNR={st.tail_nr}')
+        _L(st, f'  Reverts:{st.guard_reverts}  Warns:{len(st.guard_warn)}/{len(st.guard_pass)+len(st.guard_warn)}')
+        _L(st, f'{"═"*60}\n')
+        return st
+
+    finally:
+        _cleanup_all(st)   # [I8] always runs
+
+
+# ─── CLI ──────────────────────────────────────────────────────────────────────
+if __name__ == '__main__':
+    import argparse, json
+    ap = argparse.ArgumentParser(description=f'الصفاء {__version__} — Dereverberation Engine')
+    ap.add_argument('input')
+    ap.add_argument('output')
+    ap.add_argument('--tier',     default='TIER_UNKNOWN')
+    ap.add_argument('--mujawwad', type=float, default=0.0)
+    ap.add_argument('--rt60',       type=float, default=0.0, help='Force RT60 (0=auto)')
+    ap.add_argument('--aggressive', action='store_true',
+                    help='4x volume boost (7.40) + wider DF3 caps vs standard (1.85)')
+    a = ap.parse_args()
+    st = process(a.input, a.output,
+                 source_tier=a.tier, mujawwad_conf=a.mujawwad, force_rt60=a.rt60,
+                 aggressive=a.aggressive)
+    print('\n[REPORT]')
+    print(json.dumps({
+        'version':      __version__,
+        'rt60':         st.rt60_initial,
+        'drr_before':   round(st.drr_before, 2),
+        'drr_after':    round(st.drr_after,  2),
+        'drr_gain':     round(st.drr_after - st.drr_before, 2),
+        'stages': {
+            'lf_eq':    st.lf_eq,
+            'wpe':      st.wpe,
+            'df3':      st.df3,
+            'jalaa':    st.jalaa,
+            'tail_nr':  st.tail_nr,
+        },
+        'guard_reverts': st.guard_reverts,
+        'guard_pass':    st.guard_pass,
+        'guard_warn':    st.guard_warn,
+    }, indent=2, ensure_ascii=False))