Spaces:

carm5333
/

Background

Running

App Files Files Community

Background / engine_ihya_v3.py

carm5333

S201: add engine_ihya_v3.py (replaces isteidad in v11.2 slot)

90a7ac9 verified about 1 month ago

Raw

History Blame Contribute Delete

150 kB

	#!/usr/bin/env python3
	"""
	╔══════════════════════════════════════════════════════════════════════════════╗
	║ ║
	║ الإحياء — ENGINE-3 OF THE AETHERION ║
	║ Voice Revival Engine — Making Artificial Sound Human Again ║
	║ ║
	║ "الإحياء" — revival, bringing back to life. When the Sheikh's voice ║
	║ sounds robotic, pixelated, or hollow — this engine breathes life ║
	║ back into it. ║
	║ ║
	║ الهدف: Transform artificial/mechanical Quran recitation into ║
	║ natural, human-sounding voice ║
	║ ║
	╠══════════════════════════════════════════════════════════════════════════════╣
	║ ║
	║ SCOPE ║
	║ Audio that sounds: ║
	║ • Artificial / robotic / flat F0 (TTS-like, vocoder artifacts) ║
	║ • Pixelated / digital (codec ghosting, metallic ringing) ║
	║ • Hollow / thin (spectral holes, missing formants) ║
	║ • Mechanically denoised (over-NR'd, spectral musical noise) ║
	║ • Low-bitrate degraded (64-96kbps MP3/Opus/WhatsApp) ║
	║ ║
	║ PIPELINE (12 phases) ║
	║ Phase 0 Deep artifact analysis: F0 flatness, spectral holes, ║
	║ metallic ringing, codec ghost detection, NR damage score, ║
	║ SNR estimation, active bandwidth, wind noise detection ║
	║ Phase 1 Dereverberation (Safaa S1-S7 pipeline, lightweight) ║
	║ Phase 2 Selective noise repair: spectral-musical-noise reduction ║
	║ + artifact interpolation (not just NR — targeted repair) ║
	║ + wind noise HPF + SNR-gated NR depth ║
	║ Phase 3 F0 contour revival: micro-pitch variation injection ║
	║ + natural jitter/shimmer restoration ║
	║ Phase 4 Formant reconstruction: rebuild missing/collapsed formants ║
	║ using EQ-based formant boosting from Arabic reference template ║
	║ Phase 5 Harmonic richness restoration: selective harmonic excitation ║
	║ on voiced frames only, F0-histogram-weighted ║
	║ Phase 6 Micro-dynamics breathing: phrase-level RMS modulation ║
	║ to restore natural loudness variation ║
	║ Phase 7 Spectral continuity repair: smooth spectral holes/edges ║
	║ from codec artifacts and aggressive NR ║
	║ Phase 8 Sibilant naturalization: rebuild sibilant texture ║
	║ (ش/س/ص/ز) that codec/NR destroys ║
	║ Phase 9 Temporal envelope shaping: attack/transient restoration ║
	║ + consonant-vowel boundary sharpening + 2-4kHz presence boost ║
	║ Phase 10 Tajweed phoneme guards: 7-guard verification + repair ║
	║ Phase 11 Final loudness + quality optimization + naturalness scoring ║
	║ ║
	║ KEY DESIGN PRINCIPLES ║
	║ R1 Never hallucinate — only enhance what exists; don't synthesize ║
	║ new phonemes or words ║
	║ R2 Tajweed above all — F0 variation must never alter Tajweed ║
	║ phoneme identity (§35, §36, §79, §152) ║
	║ R3 Subtlety over spectacle — 0.5dB changes compound to naturalness ║
	║ R4 Measurement-driven — every phase has guards and reverts ║
	║ R5 Arabic-first — all processing calibrated for Arabic phonetics ║
	║ and Quranic recitation patterns (Murattal/Mujawwad/Hadr) ║
	║ ║
	║ KB REFS: §4 §35 §36 §52 §79 §80 §85 §91 §102 §109 §122 §133 ║
	║ §143 §145 §152 §154 §160 ║
	║ ║
	║ ★ ENGINE-3 v2.0 — THE AETHERION PROJECT ║
	║ Built for the Quran. وما التوفيق إلا بالله ║
	║ ║
	╚══════════════════════════════════════════════════════════════════════════════╝
	"""
	__version__ = 'v2.2'

	import argparse, json, os, shutil, subprocess, sys, time, tempfile, warnings
	from dataclasses import dataclass, field
	from pathlib import Path
	from typing import Dict, List, Optional, Tuple
	warnings.filterwarnings('ignore')

	_TMP = tempfile.gettempdir()

	try:
	import numpy as np
	from scipy.fft import rfft, rfftfreq
	from scipy.signal import medfilt, butter, sosfilt
	NUMPY_OK = SCIPY_OK = True
	except ImportError:
	NUMPY_OK = SCIPY_OK = False

	try:
	from voicefixer import VoiceFixer as _VoiceFixer
	VOICEFIXER_OK = True
	except ImportError:
	VOICEFIXER_OK = False

	try:
	import audiosr as _audiosr
	AUDIOSR_OK = True
	except ImportError:
	AUDIOSR_OK = False

	try:
	import soundfile as SF
	SF_OK = True
	except ImportError:
	SF_OK = False


	# ══════════════════════════════════════════════════════════════════════════════
	# CONSTANTS
	# ══════════════════════════════════════════════════════════════════════════════

	SR = 48000
	WAV_CODEC = 'pcm_s24le'

	# Arabic sibilant bands (§152: Safir ص/س/ز)
	ARABIC_SIB_BANDS = [2500.0, 3150.0, 4000.0, 5000.0, 6300.0, 8000.0]

	# Formant frequencies for adult male Arabic reciter (§4, §152)
	# F1: vowel height, F2: vowel backness, F3: lip rounding + nasal
	FORMANT_MALE_ARABIC = {
	'F1': {'min': 250, 'typical': 350, 'max': 800}, # open vowels ~800, closed ~250
	'F2': {'min': 600, 'typical': 1400, 'max': 2500}, # back ~600, front ~2500
	'F3': {'min': 2200, 'typical': 2800, 'max': 3500}, # rounding/nasal
	}

	# F0 natural variation ranges for Quranic recitation (§85, §133)
	# Murattal: steadier, Mujawwad: more ornamentation
	F0_JITTER_MS = 0.35 # ms: natural cycle-to-cycle variation (§133.3)
	F0_SHIMMER_DB = 0.20 # dB: natural amplitude variation (§133.3)
	F0_DRIFT_CENTS = 12.0 # cents: slow drift within a phrase (§85)
	MUJAWWAD_DRIFT = 35.0 # cents: wider ornamentation drift (§145)

	# Artifact detection thresholds (§8, §21, §160)
	METALLIC_RING_THRESHOLD = 0.15 # ratio of harmonic false peaks (used in _detect_metallic_ringing)
	CODEC_GHOST_THRESHOLD = 0.08 # spectral hole depth ratio (used in _detect_spectral_holes)
	NR_DAMAGE_THRESHOLD = 0.25 # musical noise energy ratio (used in _detect_nr_damage severity)
	F0_FLATNESS_THRESHOLD = 0.85 # 1.0 = perfectly flat = robotic (§133)

	# Spectral smoothing (§7, §154)
	SPEC_SMOOTH_WINDOW = 3 # bands for median smoothing (used in _detect_spectral_holes)
	SPEC_HOLE_DEPTH_DB = -18.0 # band energy below this = spectral hole
	SPEC_EDGE_SHARP_DB = 8.0 # adjacent band delta > this = codec edge

	# Micro-dynamics (§85, §133)
	PHRASE_LRA_MIN = 1.5 # used in phase6 micro-dynamics LRA range
	PHRASE_LRA_MAX = 5.0 # used in phase6 micro-dynamics LRA range
	BREATH_DEPTH_DB = 1.5 # subtle RMS modulation depth (used in phase6)

	# Tajweed guard thresholds (§35, §52, §143)
	GHUNNAH_BAND = (220, 320) # Hz: nasal murmur (§152.3)
	IKHFA_BAND = (250, 420) # Hz: nasalisation (§52.5)
	QALQALAH_BURST_DB = 6.0 # dB: burst above silence
	RA_TRILL_AM_BAND = (22, 40) # Hz: Ra amplitude modulation
	SAFIR_BAND = (5500, 12000) # Hz: ص س ز (§152.3)
	TAFASSHI_BAND = (3000, 8000) # Hz: ش (§152.3)

	# Wind noise detection
	WIND_BAND_HZ = (20, 200) # Hz: wind rumble band
	WIND_REF_BAND_HZ = (200, 500) # Hz: reference band for comparison
	WIND_RATIO_THRESH = 6.0 # dB: wind band above reference = wind noise

	# SNR estimation
	SNR_NOISY_THRESH = 15.0 # dB: below this = noisy recording

	# Active bandwidth detection
	BANDWIDTH_FLOOR_DB = -60.0 # dB: minimum energy for "active" band
	BANDWIDTH_HPF_FREQ = 80.0 # Hz: ignore below this for bandwidth

	# ── TIER_TELEPHONE detection thresholds (§169) ────────────────────────────────
	TELEPHONE_CUTOFF_HZ = 4000.0 # recordings ≤ this Hz = TIER_TELEPHONE
	TELEPHONE_ABOVE4K_THRESH = 0.001 # energy fraction above 4kHz must be < 0.1%
	TELEPHONE_ROLLOFF_MIN_DB = 35.0 # dB drop across pre/post-cutoff bands (§169: ≥40dB)
	TELEPHONE_BLEND_ORDER = 8 # Butterworth crossover filter order for blend step

	# 48-band centers (inherited from Itiqan)
	CENTERS_48: List[float] = [
	60.0, 80.0, 89.4, 100.0, 111.8, 125.0, 141.4,
	160.0, 178.9, 200.0, 223.6, 250.0, 280.6, 315.0,
	354.9, 400.0, 447.2, 500.0, 561.2, 630.0, 709.9,
	800.0, 894.4, 1000.0, 1118.0, 1250.0, 1414.2, 1600.0,
	1788.8, 2000.0, 2236.1, 2500.0, 2806.2, 3150.0, 3549.6,
	4000.0, 4472.1, 5000.0, 5612.3, 6300.0, 7099.3, 8000.0,
	8944.3,10000.0,11180.3,12500.0,14142.1,16000.0,
	]

	# Reference targets for natural Quranic voice (from 1425H)
	TARGET = {
	'lufs': -6.29, 'rms': -10.01, 'crest': 10.25, 'lra': 4.19,
	'true_peak': -1.0,
	}

	# Perceptual loss weights (§154, §160) — used in naturalness score
	_PERC_WEIGHT: Dict[float, float] = {
	125: 0.30, 250: 0.50, 500: 0.70, 1000: 0.90,
	2000: 1.00, 3150: 1.00, 4000: 0.90, 5000: 0.70,
	6300: 0.50, 8000: 0.40,10000: 0.30,
	}


	# ══════════════════════════════════════════════════════════════════════════════
	# DATA CLASSES
	# ══════════════════════════════════════════════════════════════════════════════

	@dataclass
	class ArtifactReport:
	"""Phase 0 diagnostic — what's wrong with the audio."""
	f0_flatness: float = 0.0 # 0=highly variable, 1=flat=robotic
	f0_flat_severity: str = 'none' # none/mild/moderate/severe
	spectral_holes: int = 0 # count of bands with deep holes
	spectral_edges: int = 0 # count of sharp codec edges
	metallic_score: float = 0.0 # 0=clean, 1=severe ringing
	metallic_severity: str = 'none' # none/mild/moderate/severe
	codec_ghost_score: float = 0.0 # spectral leakage from codec
	nr_damage_score: float = 0.0 # musical noise from over-NR
	nr_damage_severity: str = 'none' # none/mild/moderate/severe
	formant_collapse: float = 0.0 # 0=intact, 1=fully collapsed
	sibilant_quality: float = 1.0 # 1=natural, 0=destroyed
	breathiness_score: float = 0.0 # 0=present, 1=missing breath
	overall_artificial: float = 0.0 # composite: 0=natural, 1=severe
	diagnosis: str = '' # human-readable diagnosis
	mujawwad_conf: float = 0.0 # recitation style confidence
	# v2 additions
	noise_floor_db: float = -60.0 # estimated noise floor
	snr_db: float = 40.0 # estimated SNR
	is_noisy: bool = False # SNR below threshold
	active_bandwidth_hz:float = 20000.0 # highest freq with meaningful energy
	wind_detected: bool = False # wind noise detected below 200Hz

	# v2.2 — TIER_TELEPHONE (§169)
	is_telephone_tier: bool = False # True if codec_cutoff ≤ 4 kHz
	telephone_cutoff_hz:float = 0.0 # detected cutoff frequency (Hz)


	@dataclass
	class IhyaState:
	"""Runtime state for الإحياء engine."""
	input_path: str = ''
	output_path: str = ''
	duration_s: float = 0.0
	bitrate_kbps: int = 0
	source_tier: str = 'TIER_UNKNOWN'
	mujawwad_conf: float = 0.0
	aggressive: bool = False # v2: aggressive mode

	# Phase 0 results
	artifacts: 'ArtifactReport \| None' = None

	# Measurements
	lufs: float = 0.0
	rms: float = 0.0
	crest: float = 0.0
	lra: float = 0.0
	true_peak: float = 0.0
	f0_median: float = 0.0

	# Phase results
	p0_analyzed: bool = False
	p1_dereverb_applied: bool = False
	p2_nr_repair_applied:bool = False
	p3_f0_revival: bool = False
	p3_jitter_injected: bool = False
	p3_shimmer_injected: bool = False
	p4_formant_rebuilt: bool = False
	p5_harmonic_rich: bool = False
	p6_micro_dynamics: bool = False
	p7_spectral_repair: bool = False
	p8_sibilant_nat: bool = False
	p9_temporal_shaping: bool = False
	p10_guards_ok: bool = False
	p11_final_done: bool = False

	# v2.2 — TIER_TELEPHONE (§169)
	is_telephone_tier: bool = False # bandwidth ≤ 4 kHz detected
	telephone_bwe_applied: bool = False # VoiceFixer BWE phase ran
	telephone_audiosr_applied:bool = False # AudioSR Stage-B ran
	telephone_cutoff_hz: float = 0.0 # detected cutoff (Hz)
	telephone_bwe_mode: str = '' # 'voicefixer_mode0' / 'none'

	# Repair metrics
	f0_flatness_before: float = 0.0
	f0_flatness_after: float = 0.0
	spectral_holes_before: int = 0
	spectral_holes_after: int = 0
	metallic_before: float = 0.0
	metallic_after: float = 0.0

	# Guard tracking
	guard_pass: List[str] = field(default_factory=list)
	guard_warn: List[str] = field(default_factory=list)
	guard_reverts: int = 0

	# Naturalness score (v2)
	naturalness_score: float = 50.0 # 0-100 composite

	# Temp file tracking
	_tmps: List[str] = field(default_factory=list, repr=False)

	# Processing time
	t0: float = 0.0


	# ══════════════════════════════════════════════════════════════════════════════
	# LOGGER + FFMPEG RUNNER
	# ══════════════════════════════════════════════════════════════════════════════

	_LOG: List[str] = []

	def L(msg: str) -> None:
	_LOG.append(msg)
	print(msg, flush=True)

	def _chk(label: str) -> None:
	L(f'\n── {label} ──')


	def _run_ffmpeg(cmd: List[str], capture: bool = False, timeout: int = 600) -> Tuple[int, str, str]:
	"""Run ffmpeg command. Returns (returncode, stdout, stderr)."""
	try:
	result = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, timeout=timeout)
	stdout = result.stdout.decode('utf-8', errors='replace')
	stderr = result.stderr.decode('utf-8', errors='replace')
	return result.returncode, stdout, stderr
	except subprocess.TimeoutExpired:
	return 1, '', 'TIMEOUT'
	except FileNotFoundError:
	return 1, '', 'ffmpeg not found'


	def _tmp_wav(suffix: str = '', st: Optional[IhyaState] = None) -> str:
	p = os.path.join(_TMP, f'ihya_{os.getpid()}_{suffix}_{int(time.time()*1000)}.wav')
	if st is not None:
	st._tmps.append(p)
	return p


	def _cleanup(*paths: str) -> None:
	for p in paths:
	try:
	if p and os.path.exists(p):
	os.remove(p)
	except OSError:
	pass

	def _cleanup_all(st: IhyaState) -> None:
	for p in st._tmps:
	try:
	if p and os.path.exists(p): os.unlink(p)
	except Exception:
	pass
	st._tmps.clear()


	# ══════════════════════════════════════════════════════════════════════════════
	# AUDIO MEASUREMENT — inherited from Itiqan + extensions
	# ══════════════════════════════════════════════════════════════════════════════

	def _decode_to_wav(input_path: str, output_wav: str) -> bool:
	"""Decode any audio to 48kHz mono 24-bit WAV."""
	cmd = ['ffmpeg', '-y', '-i', input_path,
	'-ar', str(SR), '-ac', '1', '-acodec', WAV_CODEC, output_wav]
	rc, _, _ = _run_ffmpeg(cmd)
	return rc == 0 and os.path.exists(output_wav)


	def _decode_samples(wav_path: str) -> Tuple[Optional['np.ndarray'], int]:
	"""Decode WAV to numpy float32 array."""
	if not NUMPY_OK:
	return None, SR
	# Use pipe decode for speed
	try:
	r = subprocess.run(
	['ffmpeg', '-nostdin', '-y', '-hide_banner', '-loglevel', 'error',
	'-i', wav_path, '-ar', str(SR), '-ac', '1', '-f', 'f32le', '-'],
	capture_output=True, timeout=300)
	if r.returncode or len(r.stdout) < 4:
	# Fallback: 16-bit decode
	tmp = os.path.join(_TMP, f'ihya_pcm16_{os.getpid()}.pcm')
	cmd = ['ffmpeg', '-y', '-i', wav_path,
	'-ar', str(SR), '-ac', '1', '-f', 's16le', tmp]
	rc, _, _ = _run_ffmpeg(cmd)
	if rc != 0 or not os.path.exists(tmp):
	return None, SR
	try:
	raw = np.fromfile(tmp, dtype=np.int16)
	samples = raw.astype(np.float32) / 32768.0
	return samples, SR
	finally:
	_cleanup(tmp)
	data = np.frombuffer(r.stdout, dtype=np.float32).copy()
	return data, SR
	except Exception:
	return None, SR


	def _get_duration(path: str) -> float:
	rc, out, _ = _run_ffmpeg([
	'ffprobe', '-v', 'error', '-show_entries', 'format=duration',
	'-of', 'default=noprint_wrappers=1:nokey=1', path
	])
	try:
	return float(out.strip())
	except ValueError:
	return 0.0

	def _get_bitrate(path: str) -> int:
	rc, out, _ = _run_ffmpeg([
	'ffprobe', '-v', 'error', '-show_entries', 'format=bit_rate',
	'-of', 'default=noprint_wrappers=1:nokey=1', path
	])
	try:
	return int(out.strip()) // 1000
	except ValueError:
	return 0


	def _measure_lufs(wav_path: str) -> Tuple[float, float]:
	"""Returns (integrated_lufs, lra)."""
	cmd = ['ffmpeg', '-i', wav_path,
	'-af', 'ebur128=peak=true:framelog=quiet', '-f', 'null', '-']
	rc, out, err = _run_ffmpeg(cmd)
	combined = out + err
	lufs, lra = -99.0, 0.0
	for line in combined.splitlines():
	if 'I:' in line and 'LUFS' in line:
	try:
	lufs = float(line.split('I:')[1].split('LUFS')[0].strip())
	except (IndexError, ValueError):
	pass
	if 'LRA:' in line and 'LU' in line:
	try:
	lra = float(line.split('LRA:')[1].split('LU')[0].strip())
	except (IndexError, ValueError):
	pass
	return lufs, lra


	def _measure_rms_crest(samples: 'np.ndarray') -> Tuple[float, float]:
	"""Returns (rms_db, crest_db)."""
	if samples is None or len(samples) == 0:
	return -99.0, 0.0
	rms_linear = float(np.sqrt(np.mean(samples ** 2)))
	peak_linear = float(np.max(np.abs(samples)))
	rms_db = 20 * np.log10(max(rms_linear, 1e-10))
	peak_db = 20 * np.log10(max(peak_linear, 1e-10))
	crest_db = peak_db - rms_db
	return rms_db, crest_db


	def _band_energy(samples: 'np.ndarray', flo: float, fhi: float,
	sr: int = SR, n_fft: int = 4096) -> float:
	"""Band energy in [flo, fhi] Hz, sampled across the signal."""
	if samples is None or len(samples) < n_fft:
	return 0.0
	n_samples = min(8, max(1, len(samples) // n_fft))
	step = max(n_fft, len(samples) // (n_samples + 1))
	energies = []
	freqs = np.fft.rfftfreq(n_fft, 1.0 / sr)
	mask = (freqs >= flo) & (freqs <= fhi)
	if not mask.any():
	return 0.0
	for pos in range(0, len(samples) - n_fft, step):
	sp = np.abs(np.fft.rfft(samples[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


	def _band_energy_db(samples: 'np.ndarray', flo: float, fhi: float,
	sr: int = SR) -> float:
	"""Band energy in dB."""
	e = _band_energy(samples, flo, fhi, sr)
	if e < 1e-20:
	return -100.0
	return float(10 * np.log10(e))


	def _rmsdb(s: 'np.ndarray') -> float:
	return float(20 * np.log10(np.sqrt(np.mean(s ** 2)) + 1e-10))


	# ══════════════════════════════════════════════════════════════════════════════
	# NEW v2 DETECTION: SNR, ACTIVE BANDWIDTH, WIND NOISE
	# ══════════════════════════════════════════════════════════════════════════════

	def _estimate_snr(samples: 'np.ndarray', sr: int = SR) -> Tuple[float, float, bool]:
	"""
	Estimate noise floor and SNR from the audio signal.
	Uses frame-level energy analysis: quiet frames represent the noise floor,
	loud frames represent signal+noise.
	Returns (noise_floor_db, snr_db, is_noisy).
	"""
	if not NUMPY_OK or samples is None:
	return -60.0, 40.0, False

	FRAME_MS = 20.0
	frame_n = int(FRAME_MS / 1000.0 * sr)
	n_frames = len(samples) // frame_n
	if n_frames < 20:
	return -60.0, 40.0, False

	# Compute per-frame RMS
	frame_rms = np.array([float(np.sqrt(np.mean(samples[iframe_n:(i+1)frame_n]**2)))
	for i in range(n_frames)])

	# Noise floor: use 10th percentile of frame energies (true silence/noise)
	voiced_mask = frame_rms > 1e-7
	if not voiced_mask.any():
	return -60.0, 40.0, False

	noise_rms = float(np.percentile(frame_rms[voiced_mask], 10))
	# Signal level: use 75th percentile (typical speech level)
	signal_rms = float(np.percentile(frame_rms[voiced_mask], 75))

	noise_floor_db = 20 * np.log10(max(noise_rms, 1e-10))
	signal_db = 20 * np.log10(max(signal_rms, 1e-10))
	snr_db = signal_db - noise_floor_db

	is_noisy = snr_db < SNR_NOISY_THRESH

	return noise_floor_db, snr_db, is_noisy


	def _detect_active_bandwidth(samples: 'np.ndarray', sr: int = SR) -> float:
	"""
	Detect the highest frequency with meaningful energy.
	Low-bitrate codecs cut off above 12-16kHz, leaving silence above that.
	Returns bandwidth in Hz.
	"""
	if not NUMPY_OK or samples is None:
	return sr / 2.0

	# Use FFT on central portion
	center_start = int(len(samples) * 0.15)
	center_end = int(len(samples) * 0.85)
	center = samples[center_start:center_end]

	N = min(len(center), sr * 2)
	if N < sr // 4:
	return sr / 2.0

	spec = np.abs(rfft(center[:N] * np.hanning(N))) ** 2
	freqs = rfftfreq(N, d=1.0 / sr)

	# Overall spectral floor
	overall_floor = float(np.percentile(spec[spec > 0], 10)) if (spec > 0).any() else 1e-20

	# Scan from high to low frequency
	# Find highest frequency above BANDWIDTH_HPF_FREQ with energy above floor
	mask_above_hpf = freqs >= BANDWIDTH_HPF_FREQ
	freqs_filtered = freqs[mask_above_hpf]
	spec_filtered = spec[mask_above_hpf]

	if len(spec_filtered) == 0:
	return sr / 2.0

	# Use 1/3-octave bands for robustness
	active_bw = BANDWIDTH_HPF_FREQ
	for fc in reversed(CENTERS_48):
	if fc < BANDWIDTH_HPF_FREQ or fc > sr / 2:
	continue
	lo = fc / (2 ** (1.0/6))
	hi = fc * (2 ** (1.0/6))
	band_mask = (freqs >= lo) & (freqs <= hi)
	if band_mask.any():
	band_energy = float(np.mean(spec[band_mask]))
	# Band is "active" if it's significantly above the noise floor
	if band_energy > overall_floor * 100: # 20dB above floor
	active_bw = max(active_bw, hi)
	break

	return float(active_bw)


	def _detect_wind_noise(samples: 'np.ndarray', sr: int = SR) -> bool:
	"""
	Detect wind noise below 200Hz.
	Mosque/outdoor recordings often have wind rumble.
	Wind noise shows as disproportionately high energy in 20-200Hz
	relative to the 200-500Hz reference band.
	Returns True if wind noise is detected.
	"""
	if not NUMPY_OK or samples is None:
	return False

	wind_energy = _band_energy(samples, WIND_BAND_HZ[0], WIND_BAND_HZ[1], sr)
	ref_energy = _band_energy(samples, WIND_REF_BAND_HZ[0], WIND_REF_BAND_HZ[1], sr)

	if ref_energy < 1e-20:
	return False

	ratio_db = 10 * np.log10(wind_energy / (ref_energy + 1e-20))

	return ratio_db > WIND_RATIO_THRESH


	def _detect_telephone_tier(samples: 'np.ndarray',
	active_bandwidth_hz: float,
	sr: int = SR) -> Tuple[bool, float]:
	"""
	Detect TIER_TELEPHONE: recording with hard spectral cutoff ≤ 4 kHz.
	§169 criteria:
	(1) active_bandwidth_hz already < 4000 Hz
	(2) energy above 4 kHz < 0.1% of total power
	(3) steep rolloff: ≥ 35 dB drop across pre-cutoff / post-cutoff bands

	Returns (is_telephone_tier, cutoff_hz).

	KEY INSIGHT (§169): Container bitrate is IRRELEVANT.
	128 kbps AAC wrapping a 3.4 kHz telephone source is still TIER_TELEPHONE.
	"""
	if active_bandwidth_hz >= TELEPHONE_CUTOFF_HZ:
	return False, 0.0

	if not NUMPY_OK or samples is None or len(samples) < sr // 2:
	# Trust the bandwidth detection alone
	return True, float(min(active_bandwidth_hz, 3400.0))

	# FFT on central portion (avoid head/tail silence)
	center_s = int(len(samples) * 0.10)
	center_e = int(len(samples) * 0.90)
	seg = samples[center_s:center_e]
	N = min(len(seg), sr * 2)
	if N < 512:
	return True, float(min(active_bandwidth_hz, 3400.0))

	win = seg[:N] * np.hanning(N)
	Pxx = np.abs(rfft(win, n=N)) ** 2
	freqs = rfftfreq(N, d=1.0 / sr)
	total = float(Pxx.sum()) + 1e-30

	# Criterion 1: almost no energy above 4 kHz (< 0.1 %)
	above_4k_frac = float(Pxx[freqs > 4000].sum()) / total
	if above_4k_frac >= TELEPHONE_ABOVE4K_THRESH:
	return False, 0.0

	# Criterion 2: must have signal below 3.5 kHz (not a dead/silent file)
	band_signal = float(Pxx[(freqs >= 300) & (freqs <= 3500)].sum()) / total
	if band_signal < 0.01:
	return False, 0.0

	# Criterion 3: steep rolloff — compare band just below cutoff vs just above
	# Use 2.5–3.4 kHz (below) vs 3.8–5.0 kHz (above)
	band_below = float(Pxx[(freqs >= 2500) & (freqs <= 3400)].sum()) + 1e-30
	band_above = float(Pxx[(freqs >= 3800) & (freqs <= 5000)].sum()) + 1e-30
	rolloff_db = 10.0 * np.log10(band_below / band_above)

	if rolloff_db < TELEPHONE_ROLLOFF_MIN_DB:
	return False, 0.0

	# Estimate cutoff more precisely: walk down from 4 kHz to find last
	# bin with meaningful energy (> 1% of average below 3 kHz)
	ref_level = float(np.mean(Pxx[(freqs >= 500) & (freqs <= 2500)]))
	thresh = ref_level * 0.01
	cutoff_est = 3400.0
	for fc in np.arange(3900, 1000, -50, dtype=float):
	mask = (freqs >= fc - 25) & (freqs < fc + 25)
	if mask.any() and float(Pxx[mask].mean()) > thresh:
	cutoff_est = fc
	break

	return True, float(cutoff_est)


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 0: DEEP ARTIFACT ANALYSIS
	# ══════════════════════════════════════════════════════════════════════════════

	def _detect_f0(samples: 'np.ndarray', sr: int = SR) -> Tuple['np.ndarray', float]:
	"""
	Detect F0 contour using autocorrelation on voiced frames.
	Returns (f0_contour_array, f0_median).
	Each element is Hz (0.0 for unvoiced frames).
	"""
	if not NUMPY_OK or samples is None:
	return np.array([]), 0.0

	FRAME_MS = 20.0
	frame_n = int(FRAME_MS / 1000.0 * sr)
	n_frames = len(samples) // frame_n
	if n_frames < 10:
	return np.array([]), 0.0

	f0_contour = np.zeros(n_frames)
	min_lag = int(sr / 500.0) # 500 Hz max F0
	max_lag = int(sr / 60.0) # 60 Hz min F0

	for i in range(n_frames):
	frame = samples[i * frame_n:(i + 1) * frame_n]
	rms = float(np.sqrt(np.mean(frame ** 2)))
	if rms < 1e-5: # silence/unvoiced
	continue

	# Autocorrelation
	corr = np.correlate(frame, frame, mode='full')
	corr = corr[len(frame) - 1:] # keep positive lags only

	# Find peak in F0 range
	search = corr[min_lag:min(max_lag, len(corr))]
	if len(search) < 2:
	continue

	peak_idx = int(np.argmax(search)) + min_lag
	if corr[peak_idx] < 0.3 * corr[0]: # too weak = unvoiced
	continue

	f0_contour[i] = sr / peak_idx

	# Median of voiced frames
	voiced = f0_contour[f0_contour > 0]
	f0_median = float(np.median(voiced)) if len(voiced) > 5 else 0.0

	return f0_contour, f0_median


	def _compute_f0_flatness(f0_contour: 'np.ndarray') -> float:
	"""
	Compute F0 flatness (0 = highly variable/natural, 1 = perfectly flat/robotic).
	Uses coefficient of variation of voiced F0 values.
	§133: natural speech has F0 variation > 30 cents (semi-tones).
	Robotic/TTS has < 10 cents variation.
	"""
	voiced = f0_contour[f0_contour > 0]
	if len(voiced) < 10:
	return 0.0 # not enough data

	# Convert to cents relative to median (more perceptually relevant)
	median_f0 = float(np.median(voiced))
	if median_f0 < 50:
	return 0.0

	cents = 1200.0 * np.log2(voiced / median_f0)
	std_cents = float(np.std(cents))

	# Natural recitation: std_cents typically 15-40 cents
	# Robotic: std_cents < 5 cents
	# Map: 0 cents std → 1.0 flat, 40+ cents → 0.0 flat
	flatness = float(np.clip(1.0 - std_cents / 40.0, 0.0, 1.0))
	return flatness


	def _detect_spectral_holes(samples: 'np.ndarray', sr: int = SR) -> Tuple[int, List[float]]:
	"""
	Detect spectral holes — bands where energy drops abnormally.
	These are typical of codec artifacts (§8, §21) or aggressive NR (§160).
	Returns (count, list_of_center_frequencies).
	"""
	if not NUMPY_OK or samples is None:
	return 0, []

	holes = []
	# Compute per-band energy
	band_db = {}
	for f in CENTERS_48:
	if f < 80 or f > 16000:
	continue
	# Approximate band: center ± 1/12 octave
	lo = f / (2 ** (1.0/12))
	hi = f * (2 ** (1.0/12))
	e_db = _band_energy_db(samples, lo, hi, sr)
	band_db[f] = e_db

	if len(band_db) < 4:
	return 0, []

	# Apply median smoothing using SPEC_SMOOTH_WINDOW to reduce noise
	sorted_centers = sorted(band_db.keys())
	db_values = np.array([band_db[f] for f in sorted_centers])
	if len(db_values) >= SPEC_SMOOTH_WINDOW:
	kernel_size = SPEC_SMOOTH_WINDOW if SPEC_SMOOTH_WINDOW % 2 == 1 else SPEC_SMOOTH_WINDOW + 1
	db_smoothed = medfilt(db_values, kernel_size=kernel_size)
	for i, f in enumerate(sorted_centers):
	band_db[f] = float(db_smoothed[i])

	# A spectral hole is a band that is significantly below its neighbors
	for i in range(1, len(sorted_centers) - 1):
	prev_db = band_db[sorted_centers[i - 1]]
	curr_db = band_db[sorted_centers[i]]
	next_db = band_db[sorted_centers[i + 1]]
	neighbor_avg = (prev_db + next_db) / 2.0
	dip = curr_db - neighbor_avg # negative = hole
	if dip < -abs(SPEC_HOLE_DEPTH_DB):
	holes.append(sorted_centers[i])

	return len(holes), holes


	def _detect_spectral_edges(samples: 'np.ndarray', sr: int = SR) -> Tuple[int, List[float]]:
	"""
	Detect sharp spectral edges — typical of codec block artifacts.
	Adjacent band energy delta > threshold indicates codec edge.
	"""
	if not NUMPY_OK or samples is None:
	return 0, []

	edges = []
	band_db = {}
	for f in CENTERS_48:
	if f < 80 or f > 16000:
	continue
	lo = f / (2 ** (1.0/12))
	hi = f * (2 ** (1.0/12))
	e_db = _band_energy_db(samples, lo, hi, sr)
	band_db[f] = e_db

	sorted_centers = sorted(band_db.keys())
	for i in range(1, len(sorted_centers)):
	delta = abs(band_db[sorted_centers[i]] - band_db[sorted_centers[i - 1]])
	if delta > SPEC_EDGE_SHARP_DB:
	edges.append(sorted_centers[i])

	return len(edges), edges


	def _detect_metallic_ringing(samples: 'np.ndarray', sr: int = SR) -> float:
	"""
	Detect metallic/ringing artifacts.
	Metallic sound = harmonic false peaks at non-harmonic frequencies (§8, §21).
	Analyze spectrum for peaks that don't align with F0 harmonics.
	Returns score 0.0 (clean) to 1.0 (severe).
	Uses METALLIC_RING_THRESHOLD for classification.
	"""
	if not NUMPY_OK or samples is None:
	return 0.0

	# Use central portion to avoid transients
	center_start = int(len(samples) * 0.15)
	center_end = int(len(samples) * 0.85)
	center = samples[center_start:center_end]

	N = min(len(center), sr * 2)
	if N < sr // 4:
	return 0.0

	spec = np.abs(rfft(center[:N] * np.hanning(N))) ** 2
	freqs = rfftfreq(N, d=1.0 / sr)

	# Find fundamental peak in 100-400Hz
	mask_fund = (freqs >= 100) & (freqs <= 400)
	if not mask_fund.any():
	return 0.0
	f1_idx = int(np.argmax(spec[mask_fund])) + int(np.where(mask_fund)[0][0])
	f1 = float(freqs[f1_idx])

	if f1 < 80:
	return 0.0

	# Count spectral peaks that are NOT at harmonic positions
	# Harmonics at f1, 2f1, 3f1, ... up to Nyquist
	harmonic_positions = [f1 * k for k in range(2, int(sr / 2 / f1) + 1)]
	harmonic_width_hz = f1 * 0.12 # ±12% tolerance

	# Find all significant peaks
	from scipy.signal import find_peaks as _find_peaks
	try:
	peaks, props = _find_peaks(np.log10(spec[1:] + 1e-20) * 10,
	height=0, distance=int(N * 50 / sr))
	except ImportError:
	return 0.0

	if len(peaks) < 3:
	return 0.0

	peak_freqs = freqs[peaks + 1] # +1 because we sliced spec[1:]
	peak_heights = spec[peaks + 1]

	# Classify each peak: harmonic or non-harmonic
	non_harmonic_energy = 0.0
	total_peak_energy = 0.0
	for pf, ph in zip(peak_freqs, peak_heights):
	total_peak_energy += ph
	is_harmonic = any(abs(pf - hp) < harmonic_width_hz for hp in harmonic_positions)
	if not is_harmonic and pf > f1 * 1.5: # ignore sub-harmonics
	non_harmonic_energy += ph

	if total_peak_energy < 1e-20:
	return 0.0

	ratio = non_harmonic_energy / total_peak_energy
	score = float(np.clip(ratio * 5.0, 0.0, 1.0))

	# Apply METALLIC_RING_THRESHOLD for severity flagging
	# (threshold used by caller for classification)
	return score


	def _detect_nr_damage(samples: 'np.ndarray', sr: int = SR) -> float:
	"""
	Detect musical noise from over-aggressive NR (§11, §160).
	Musical noise = random tonal artifacts in quiet frames.
	Returns score 0.0 (clean) to 1.0 (severe).

	v2 FIX: Only count frames BELOW median energy as "true background noise".
	Previous version used bottom 25% which incorrectly flagged clean tonal
	content (e.g. sine waves, speech leakage into quiet frames) as musical
	noise. True background noise frames are below the median energy level.
	"""
	if not NUMPY_OK or samples is None:
	return 0.0

	FRAME_MS = 20.0
	frame_n = int(FRAME_MS / 1000.0 * sr)
	n_frames = len(samples) // frame_n
	if n_frames < 20:
	return 0.0

	# Compute per-frame RMS
	frame_rms = np.array([float(np.sqrt(np.mean(samples[iframe_n:(i+1)frame_n]**2)))
	for i in range(n_frames)])

	# v2 FIX: Use median energy as threshold instead of 25th percentile.
	# Frames below median are true background noise, not speech leakage.
	# A pure sine wave has roughly constant RMS across frames, so no frames
	# fall below median — correctly NOT flagged as NR damage.
	voiced_frames = frame_rms[frame_rms > 1e-7]
	if len(voiced_frames) < 5:
	return 0.0
	median_energy = float(np.median(voiced_frames))

	# v2.1 FIX: NR damage detection must distinguish between:
	# (a) musical noise = isolated tonal islands in quiet regions
	# (b) speech leakage = harmonics from voiced speech bleeding into quiet frames
	# (c) continuous harmonics = the signal itself (not noise)
	#
	# Key insight: musical noise is SPARSE — only a few isolated frequency bins
	# are active per frame, and they vary RANDOMLY between frames (no temporal
	# coherence). Speech harmonics are TEMPORALLY COHERENT across frames.
	#
	# Detection strategy: measure spectral SPARSITY (peak-to-mean ratio) in
	# quiet frames. Musical noise has very high sparsity (few isolated peaks)
	# while natural noise/speech leakage has low sparsity (many peaks or flat).

	# Only consider frames well below median (true noise floor)
	quiet_thresh = median_energy * 0.3 # well below speech level
	quiet_frames = []
	for i in range(n_frames):
	if frame_rms[i] > 1e-7 and frame_rms[i] < quiet_thresh:
	quiet_frames.append(samples[iframe_n:(i+1)frame_n])

	if len(quiet_frames) < 3:
	return 0.0 # not enough quiet frames to analyze

	# Measure spectral sparsity (peak-to-mean ratio) in quiet frames
	sparsity_values = []
	for qf in quiet_frames:
	N = min(len(qf), 2048)
	spec = np.abs(rfft(qf[:N])) ** 2
	spec = spec[1:] # remove DC
	if len(spec) < 2 or spec.max() < 1e-20:
	continue
	# Peak-to-mean ratio: high = sparse (musical noise), low = flat (natural)
	peak = float(np.max(spec))
	mean = float(np.mean(spec))
	if mean > 1e-20:
	sparsity = peak / mean # >10 = very sparse, <3 = flat
	sparsity_values.append(sparsity)

	if len(sparsity_values) < 2:
	return 0.0

	avg_sparsity = float(np.mean(sparsity_values))
	# Musical noise: sparsity > 20 (few isolated tonal peaks)
	# Natural noise: sparsity < 5 (flat or many peaks)
	# Speech leakage: sparsity 5-15 (harmonic structure but broader)
	if avg_sparsity < 5:
	return 0.0 # natural noise, not musical noise
	elif avg_sparsity > 20:
	damage = 1.0 # severe musical noise
	else:
	damage = float(np.clip((avg_sparsity - 5.0) / 15.0, 0.0, 1.0))

	return damage


	def _detect_formant_collapse(samples: 'np.ndarray', sr: int = SR) -> float:
	"""
	Detect formant collapse — when F1/F2 distinction is lost.
	This makes voice sound hollow/thin/telephone-quality (§4, §8).
	Returns 0.0 (intact) to 1.0 (fully collapsed).
	"""
	if not NUMPY_OK or samples is None:
	return 0.0

	# Measure energy in formant bands using FORMANT_MALE_ARABIC reference
	f1_lo = FORMANT_MALE_ARABIC['F1']['min']
	f1_hi = FORMANT_MALE_ARABIC['F1']['max']
	f2_lo = FORMANT_MALE_ARABIC['F2']['min']
	f2_hi = FORMANT_MALE_ARABIC['F2']['max']

	f1_energy = _band_energy(samples, f1_lo, f1_hi, sr)
	f2_energy = _band_energy(samples, f2_lo, f2_hi, sr)

	if f1_energy < 1e-20 or f2_energy < 1e-20:
	return 0.5 # can't measure, assume moderate

	# Natural voice: F1 and F2 have similar energy levels
	# Collapsed: F2 much weaker than F1 (spectral tilt)
	ratio_db = 10 * np.log10(f2_energy / (f1_energy + 1e-20))

	# Natural: ratio around -3 to +3 dB
	# Collapsed: ratio < -10 dB
	if ratio_db > -3:
	return 0.0
	elif ratio_db < -15:
	return 1.0
	else:
	return float(np.clip((-ratio_db - 3) / 12.0, 0.0, 1.0))


	def _detect_sibilant_quality(samples: 'np.ndarray', sr: int = SR) -> float:
	"""
	Assess sibilant (ش/س/ص/ز) quality.
	Returns 1.0 (natural) to 0.0 (destroyed/artificial).
	§152: Arabic sibilants have characteristic spectral signatures.
	"""
	if not NUMPY_OK or samples is None:
	return 1.0

	safir_energy = _band_energy(samples, 5500, 12000, sr)
	mid_energy = _band_energy(samples, 1000, 3000, sr)

	if mid_energy < 1e-20:
	return 1.0

	# Natural: sibilant energy ~ -10 to -25 dB relative to mid
	# Destroyed: sibilant energy < -35 dB (over-NR'd)
	# Artificial: sibilant energy > -5 dB (too bright/harsh)
	ratio_db = 10 * np.log10(safir_energy / (mid_energy + 1e-20))

	if -25 <= ratio_db <= -5:
	return 1.0 # natural
	elif ratio_db < -35:
	return 0.0 # destroyed
	elif ratio_db > 0:
	return 0.5 # harsh/artificial
	else:
	return float(np.clip(1.0 - abs(ratio_db + 15) / 20.0, 0.0, 1.0))


	def _detect_mujawwad(samples: 'np.ndarray', f0_contour: 'np.ndarray',
	sr: int = SR) -> float:
	"""
	Detect Mujawwad recitation style confidence.
	§85, §145: Mujawwad has wider F0 variation, longer madd, more ornamentation.
	Returns 0.0 (Murattal/Hadr) to 1.0 (Mujawwad).
	"""
	if not NUMPY_OK or len(f0_contour) < 20:
	return 0.0

	voiced = f0_contour[f0_contour > 0]
	if len(voiced) < 10:
	return 0.0

	# Mujawwad indicators:
	# 1. Wider F0 range (more than 200 cents between min and max)
	median_f0 = float(np.median(voiced))
	if median_f0 < 50:
	return 0.0
	cents = 1200.0 * np.log2(voiced / median_f0)
	f0_range = float(np.percentile(cents, 95) - np.percentile(cents, 5))

	# 2. Higher F0 standard deviation
	f0_std = float(np.std(cents))

	# 3. More F0 contour direction changes (ornamentation)
	diff = np.diff(cents)
	direction_changes = int(np.sum(diff[1:] * diff[:-1] < 0))

	# Scoring
	range_score = float(np.clip(f0_range / 300.0, 0.0, 1.0)) # 300 cents = strong Mujawwad
	std_score = float(np.clip(f0_std / 40.0, 0.0, 1.0)) # 40 cents std
	orn_score = float(np.clip(direction_changes / (len(diff) * 0.3), 0.0, 1.0))

	conf = range_score * 0.4 + std_score * 0.35 + orn_score * 0.25
	return float(np.clip(conf, 0.0, 1.0))


	def _severity(score: float, mild: float = 0.25, moderate: float = 0.50,
	severe: float = 0.75) -> str:
	if score < mild:
	return 'none'
	elif score < moderate:
	return 'mild'
	elif score < severe:
	return 'moderate'
	else:
	return 'severe'


	def phase0_analyze(samples: 'np.ndarray', sr: int, st: IhyaState) -> ArtifactReport:
	"""
	Phase 0: Deep artifact analysis.
	Determines exactly what's wrong with the audio and how severe.
	v2: Also estimates SNR, active bandwidth, and wind noise.
	"""
	_chk('phase_0_analysis')
	report = ArtifactReport()

	# F0 analysis
	f0_contour, f0_median = _detect_f0(samples, sr)
	st.f0_median = f0_median
	L(f' F0 median={f0_median:.1f}Hz voiced_frames={np.sum(f0_contour > 0)}/{len(f0_contour)}')

	# F0 flatness
	report.f0_flatness = _compute_f0_flatness(f0_contour)
	report.f0_flat_severity = _severity(report.f0_flatness, 0.40, 0.60, 0.80)
	L(f' F0 flatness={report.f0_flatness:.3f} ({report.f0_flat_severity})')

	# Spectral holes
	report.spectral_holes, hole_freqs = _detect_spectral_holes(samples, sr)
	L(f' Spectral holes={report.spectral_holes} freqs={[f"{f:.0f}" for f in hole_freqs[:6]]}')

	# Spectral edges
	report.spectral_edges, edge_freqs = _detect_spectral_edges(samples, sr)
	L(f' Spectral edges={report.spectral_edges}')

	# Metallic ringing
	report.metallic_score = _detect_metallic_ringing(samples, sr)
	report.metallic_severity = _severity(report.metallic_score)
	L(f' Metallic score={report.metallic_score:.3f} ({report.metallic_severity})')

	# NR damage
	report.nr_damage_score = _detect_nr_damage(samples, sr)
	report.nr_damage_severity = _severity(report.nr_damage_score)
	L(f' NR damage={report.nr_damage_score:.3f} ({report.nr_damage_severity})')

	# Formant collapse
	report.formant_collapse = _detect_formant_collapse(samples, sr)
	L(f' Formant collapse={report.formant_collapse:.3f}')

	# Sibilant quality
	report.sibilant_quality = _detect_sibilant_quality(samples, sr)
	L(f' Sibilant quality={report.sibilant_quality:.3f}')

	# Mujawwad confidence
	report.mujawwad_conf = _detect_mujawwad(samples, f0_contour, sr)
	st.mujawwad_conf = report.mujawwad_conf
	L(f' Mujawwad confidence={report.mujawwad_conf:.3f}')

	# v2: SNR estimation
	report.noise_floor_db, report.snr_db, report.is_noisy = _estimate_snr(samples, sr)
	L(f' SNR={report.snr_db:.1f}dB noise_floor={report.noise_floor_db:.1f}dB is_noisy={report.is_noisy}')

	# v2: Active bandwidth detection
	report.active_bandwidth_hz = _detect_active_bandwidth(samples, sr)
	L(f' Active bandwidth={report.active_bandwidth_hz:.0f}Hz')

	# v2: Wind noise detection
	report.wind_detected = _detect_wind_noise(samples, sr)
	L(f' Wind noise={report.wind_detected}')

	# v2.2: TIER_TELEPHONE detection — must run AFTER active_bandwidth_hz is set
	report.is_telephone_tier, report.telephone_cutoff_hz = \
	_detect_telephone_tier(samples, report.active_bandwidth_hz, sr)
	if report.is_telephone_tier:
	st.is_telephone_tier = True
	st.telephone_cutoff_hz = report.telephone_cutoff_hz
	L(f'')
	L(f' ╔══════════════════════════════════════════════════════╗')
	L(f' ║ ⚠ TIER_TELEPHONE DETECTED ⚠ ║')
	L(f' ║ Spectral cutoff: {report.telephone_cutoff_hz:.0f} Hz ║')
	L(f' ║ Missing spectrum: {report.telephone_cutoff_hz:.0f}–22000 Hz ({100*(1-report.telephone_cutoff_hz/22050):.0f}% absent) ║')
	L(f' ║ Standard enhancement passes: BYPASSED ║')
	L(f' ║ Treatment: BWE-first pipeline §173 ║')
	L(f' ╚══════════════════════════════════════════════════════╝')
	L(f'')

	# Composite artificialness score
	report.overall_artificial = float(np.clip(
	report.f0_flatness * 0.25 +
	min(1.0, report.spectral_holes / 8.0) * 0.10 +
	report.metallic_score * 0.20 +
	report.nr_damage_score * 0.15 +
	report.formant_collapse * 0.15 +
	(1.0 - report.sibilant_quality) * 0.10 +
	(1.0 if report.is_noisy else 0.0) * 0.05,
	0.0, 1.0
	))

	# Diagnosis
	parts = []
	if report.f0_flat_severity != 'none':
	parts.append(f'F0 {report.f0_flat_severity} flatness={report.f0_flatness:.2f}')
	if report.metallic_severity != 'none':
	parts.append(f'metallic {report.metallic_severity}={report.metallic_score:.2f}')
	if report.nr_damage_severity != 'none':
	parts.append(f'NR damage {report.nr_damage_severity}={report.nr_damage_score:.2f}')
	if report.spectral_holes > 2:
	parts.append(f'{report.spectral_holes} spectral holes')
	if report.formant_collapse > 0.3:
	parts.append(f'formant collapse={report.formant_collapse:.2f}')
	if report.sibilant_quality < 0.7:
	parts.append(f'sibilant quality={report.sibilant_quality:.2f}')
	if report.is_noisy:
	parts.append(f'noisy (SNR={report.snr_db:.0f}dB)')
	if report.wind_detected:
	parts.append('wind noise detected')
	if report.active_bandwidth_hz < 16000:
	parts.append(f'limited bandwidth={report.active_bandwidth_hz:.0f}Hz')
	if report.is_telephone_tier:
	parts.append(f'TIER_TELEPHONE cutoff={report.telephone_cutoff_hz:.0f}Hz — BWE required')

	report.diagnosis = '; '.join(parts) if parts else 'no significant artifacts detected'
	L(f' ══ DIAGNOSIS: {report.diagnosis}')
	L(f' ══ Overall artificial: {report.overall_artificial:.3f}')

	st.artifacts = report
	st.f0_flatness_before = report.f0_flatness
	st.spectral_holes_before = report.spectral_holes
	st.metallic_before = report.metallic_score
	st.p0_analyzed = True

	return report


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 1: DEREVERBERATION (lightweight Safaa-inspired)
	# ══════════════════════════════════════════════════════════════════════════════

	def _rt60_estimate(samples: 'np.ndarray', sr: int = SR) -> float:
	"""Schroeder backward integration RT60 estimate."""
	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[ifn:(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))
	return 0.0


	def _drr_estimate(samples: 'np.ndarray', sr: int = SR) -> float:
	"""DRR: early vs late energy ratio."""
	if not NUMPY_OK or samples is None:
	return 0.0
	en = int(0.050 * sr)
	ln = int(0.450 * sr)
	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


	def phase1_dereverb(wav_path: str, samples: 'np.ndarray',
	st: IhyaState) -> str:
	"""
	Phase 1: Lightweight dereverberation.
	Only processes if RT60 > 0.5s (significant reverb).
	Uses ffmpeg-based EQ + afftdn for reverb reduction.
	"""
	_chk('phase_1_dereverb')

	rt60 = _rt60_estimate(samples)
	drr = _drr_estimate(samples)
	L(f' RT60={rt60:.2f}s DRR={drr:.1f}dB')

	# v2.1 FIX: RT60 on continuous tones can be wildly wrong (shows 4+ seconds
	# on a pure sine). If DRR is 0.0 (no early/late distinction), the signal
	# is probably not reverberant — it's continuous. Skip dereverb.
	if rt60 < 0.50:
	L(f' RT60 < 0.50s — no dereverb needed')
	return wav_path
	if drr == 0.0 and rt60 > 3.0:
	L(f' RT60={rt60:.2f}s but DRR=0 — likely continuous tone, not reverb. Skipping.')
	return wav_path

	# LF room mode EQ (§3.4: LF RT60 scaled by 1.3×)
	lf_rt60 = rt60 * 1.3
	scale = float(np.clip(lf_rt60 / 0.5, 1.0, 4.0))
	d_sub = float(np.clip(scale * 0.8, 0.8, 4.8))
	d_lo = float(np.clip(scale * 0.5, 0.5, 3.0))

	# Mujawwad: reduce depth (§145.3)
	if st.mujawwad_conf > 0.6:
	d_sub *= 0.5
	d_lo *= 0.5

	flt = []
	if d_sub > 0.3:
	flt.append(f'equalizer=f=150:width_type=o:width=1.4:g=-{d_sub:.1f}')
	if d_lo > 0.3:
	flt.append(f'equalizer=f=300:width_type=o:width=1.2:g=-{d_lo:.1f}')

	# Gentle dereverb NR if RT60 > 1.0s
	if rt60 > 1.0:
	nr_depth = min(6, int(rt60 * 3))
	flt.append(f'afftdn=nt=w:n={nr_depth}:t=6')

	if not flt:
	L(f' No filters needed')
	return wav_path

	out = _tmp_wav('p1_derev', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', ','.join(flt),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	L(f' Dereverb failed — keeping original')
	_cleanup(out)
	return wav_path

	# Guard: RMS delta check
	post, _ = _decode_samples(out)
	if post is not None and samples is not None:
	delta = _rmsdb(post) - _rmsdb(samples)
	guard_thresh = 4.5 if st.aggressive else 3.0
	if abs(delta) > guard_thresh:
	L(f' RMS delta={delta:+.2f}dB — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p1_dereverb_applied = True
	L(f' ✓ dereverb applied: rt60={rt60:.2f}s lf_cuts=[{d_sub:.1f},{d_lo:.1f}]dB')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 2: SELECTIVE NOISE REPAIR (v2: + wind HPF + SNR-gated NR)
	# ══════════════════════════════════════════════════════════════════════════════

	def phase2_noise_repair(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 2: Repair NR damage and spectral musical noise.
	Targeted: only processes if NR damage detected in Phase 0.
	v2: Also handles wind noise (HPF below 200Hz) and uses SNR
	to gate NR depth more intelligently.
	"""
	_chk('phase_2_noise_repair')

	filters = []

	# v2: Wind noise HPF — apply if wind detected
	if artifacts.wind_detected:
	hpf_freq = 80 if st.aggressive else 100
	filters.append(f'highpass=f={hpf_freq}:p=2')
	L(f' Wind noise detected — applying HPF at {hpf_freq}Hz')

	# Musical noise reduction: only if NR damage detected
	if artifacts.nr_damage_severity != 'none':
	# v2: Scale NR strength by SNR — noisier recordings need gentler NR
	# to avoid over-cleaning; cleaner recordings can use stronger NR
	snr_factor = 1.0
	if artifacts.is_noisy:
	# Low SNR: be more conservative with NR
	snr_factor = max(0.4, artifacts.snr_db / SNR_NOISY_THRESH)
	L(f' Low SNR ({artifacts.snr_db:.0f}dB) — reducing NR strength to {snr_factor:.1f}×')

	strength_map = {'mild': 3, 'moderate': 5, 'severe': 7}
	base_strength = strength_map.get(artifacts.nr_damage_severity, 3)
	strength = max(1, int(base_strength * snr_factor))

	if st.aggressive:
	strength = min(10, strength + 2)

	# Also add gentle afftdn for broadband noise floor
	nr_depth = min(4, strength)

	filters.append(f'anlmdn=s={strength}:p=3:r=7:m=2')
	filters.append(f'afftdn=nt=w:n={nr_depth}:t=6')
	L(f' NR damage {artifacts.nr_damage_severity}: anlmdn s={strength} afftdn n={nr_depth}')
	else:
	L(f' NR damage = none — skipping musical noise NR')

	if not filters:
	return wav_path

	out = _tmp_wav('p2_nrrepair', st)

	# v2.1 FIX: Try afftdn alone first (more reliable than anlmdn).
	# If that works and passes guards, done. If anlmdn is also available,
	# try the combined chain as a second attempt.
	rc, _, err = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', ','.join(filters),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	# First attempt failed — try afftdn-only as fallback
	L(f' Combined NR failed — trying afftdn-only fallback')
	_cleanup(out)
	fallback_filters = [f'afftdn=nt=w:n={nr_depth}:t=6']
	if artifacts.wind_detected:
	hpf_freq = 80 if st.aggressive else 100
	fallback_filters.insert(0, f'highpass=f={hpf_freq}:p=2')
	rc, _, err2 = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', ','.join(fallback_filters),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])
	if rc != 0 or not os.path.exists(out):
	L(f' NR repair failed entirely — keeping original')
	_cleanup(out)
	return wav_path

	# Guard: check that we didn't over-clean
	post, _ = _decode_samples(out)
	if post is not None and samples is not None:
	# RMS should not drop more than 2dB (over-NR), 3dB in aggressive
	rms_limit = 3.0 if st.aggressive else 2.0
	delta = _rmsdb(post) - _rmsdb(samples)
	if delta < -rms_limit:
	L(f' RMS delta={delta:+.2f}dB — over-NR — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path
	# Sibilant band should not drop more than 4dB (§152)
	sib_before = _band_energy_db(samples, 5500, 12000)
	sib_after = _band_energy_db(post, 5500, 12000)
	sib_limit = 5.0 if st.aggressive else 4.0
	if sib_before > -80 and (sib_after - sib_before) < -sib_limit:
	L(f' Sibilant band drop={sib_after-sib_before:+.1f}dB — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p2_nr_repair_applied = True
	L(f' ✓ NR repair applied')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 3: F0 CONTOUR REVIVAL — the heart of الإحياء
	# ══════════════════════════════════════════════════════════════════════════════

	def phase3_f0_revival(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 3: Revive the F0 contour — inject natural micro-pitch variation
	into flat/robotic voice. This is the core of الإحياء.

	Strategy:
	- Detect F0 contour
	- If flatness > threshold, inject natural jitter + shimmer
	- Jitter: cycle-to-cycle period variation (§133.3)
	- Shimmer: cycle-to-cycle amplitude variation (§133.3)
	- Slow drift: phrase-level F0 contour variation (§85)
	- All changes are extremely subtle — compound naturalness

	Implementation: Uses ffmpeg chorus filter with very subtle settings
	to add micro-pitch variation that mimics natural vocal jitter.
	"""
	_chk('phase_3_f0_revival')

	if not NUMPY_OK or samples is None:
	L(f' No numpy — skipping F0 revival')
	return wav_path

	if artifacts.f0_flat_severity == 'none':
	L(f' F0 flatness = none — skipping revival')
	return wav_path

	f0_contour, f0_median = _detect_f0(samples)
	if f0_median < 60 or len(f0_contour) < 20:
	L(f' F0 detection insufficient — skipping')
	return wav_path

	L(f' F0 median={f0_median:.1f}Hz flatness={artifacts.f0_flatness:.3f}')

	# ── 3a: Natural Jitter Injection ──────────────────────────────────────────
	# Jitter = small cycle-to-cycle pitch variations.
	# Natural speech: ~0.3ms jitter (§133.3)
	# Robotic: ~0.0ms jitter
	# We add jitter by pitch-shifting tiny segments by random micro-amounts.
	if artifacts.f0_flatness > F0_FLATNESS_THRESHOLD * 0.6:
	L(f' [3a] Injecting natural F0 jitter...')
	wav_path = _inject_f0_jitter(wav_path, samples, f0_median,
	artifacts.f0_flatness, st)

	# ── 3b: Natural Shimmer Injection ─────────────────────────────────────────
	# Shimmer = small cycle-to-cycle amplitude variations.
	# Natural: ~0.2dB shimmer (§133.3)
	if artifacts.f0_flatness > F0_FLATNESS_THRESHOLD * 0.5:
	L(f' [3b] Injecting natural shimmer...')
	wav_path = _inject_shimmer(wav_path, st)

	# ── 3c: Phrase-level F0 Drift ─────────────────────────────────────────────
	# Natural speech drifts slowly over phrases (§85, §133).
	# Murattal: ~12 cents drift; Mujawwad: ~35 cents (§145).
	if artifacts.f0_flatness > F0_FLATNESS_THRESHOLD * 0.7:
	L(f' [3c] Injecting phrase-level F0 drift...')
	wav_path = _inject_f0_drift(wav_path, samples, f0_median, st)

	# Measure improvement
	post, _ = _decode_samples(wav_path)
	if post is not None:
	new_f0_contour, _ = _detect_f0(post)
	if len(new_f0_contour) > 10:
	st.f0_flatness_after = _compute_f0_flatness(new_f0_contour)
	improvement = st.f0_flatness_before - st.f0_flatness_after
	L(f' F0 flatness: {st.f0_flatness_before:.3f} → {st.f0_flatness_after:.3f} '
	f'(Δ={improvement:+.3f})')

	st.p3_f0_revival = True
	return wav_path


	def _inject_f0_jitter(wav_path: str, samples: 'np.ndarray', f0_median: float,
	flatness: float, st: IhyaState) -> str:
	"""
	Inject natural pitch jitter using ffmpeg's chorus filter.
	The chorus filter adds subtle pitch variation via short modulated delays.

	v2 FIX: Chorus filter format is chorus=input_gain:output_gain:
	delays:decays:speeds:depths — each pipe-list must have the
	same number of entries. Fixed parameter labeling and values.
	"""
	sr = SR
	# Scale jitter by flatness severity
	# mild: 0.15ms, moderate: 0.30ms, severe: 0.45ms
	jitter_ms = F0_JITTER_MS * (flatness / F0_FLATNESS_THRESHOLD)
	jitter_ms = min(jitter_ms, 0.60) # cap at 0.6ms — never artificial

	# Chorus filter: chorus=input_gain:output_gain:delays:decays:speeds:depths
	# delays = milliseconds, decays = 0-1, speeds = Hz, depths = milliseconds
	# For natural jitter: short delays, moderate decays, very slow speeds, minimal depths
	depth_ms = min(1.5, jitter_ms * 3.0) # depth in milliseconds (not percentage)

	if st.aggressive:
	depth_ms *= 1.3

	# Multiple micro-chorus voices for natural variation
	# Each voice at slightly different rate for organic feel
	v1_delay = 0.5 + np.random.uniform(0, 0.3)
	v2_delay = 1.2 + np.random.uniform(0, 0.5)
	v3_delay = 2.0 + np.random.uniform(0, 0.8)

	v1_speed = 0.15 + np.random.uniform(0, 0.05)
	v2_speed = 0.08 + np.random.uniform(0, 0.03)
	v3_speed = 0.22 + np.random.uniform(0, 0.06)

	chorus_str = (
	f'chorus=0.5:0.9:'
	f'50\|60\|40:' # delays in ms (3 voices)
	f'0.4\|0.3\|0.3:' # decays (0-1 range, 3 voices)
	f'{v1_speed:.2f}\|{v2_speed:.2f}\|{v3_speed:.2f}:' # speeds in Hz (3 voices)
	f'{depth_ms:.1f}\|{depth_ms0.7:.1f}\|{depth_ms0.5:.1f}' # depths in ms (3 voices)
	)

	out = _tmp_wav('p3a_jitter', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', chorus_str,
	'-acodec', WAV_CODEC, '-ar', str(sr), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	L(f' Jitter injection failed — keeping original')
	_cleanup(out)
	return wav_path

	# Guard: verify we didn't alter overall spectral character
	# v2 FIX: Chorus naturally adds energy (comb filtering + multiple voices).
	# The 1.5dB guard was too strict — changed to 3.0dB.
	post, _ = _decode_samples(out)
	if post is not None and samples is not None:
	delta = _rmsdb(post) - _rmsdb(samples)
	jitter_rms_limit = 4.5 if st.aggressive else 3.0 # v2: was 1.5, now 3.0
	if abs(delta) > jitter_rms_limit:
	L(f' Jitter RMS delta={delta:+.2f}dB — REVERT (limit={jitter_rms_limit})')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path
	# Check formant bands are preserved
	# v2.1 FIX: Chorus naturally reshapes harmonic balance which shifts
	# per-band energy. Use a wider tolerance — the IMPORTANT thing is that
	# the overall spectral shape is preserved, not that each band is identical.
	# Check F1 AND F2 together; only revert if BOTH shift significantly.
	f1_before = _band_energy_db(samples, 250, 800)
	f1_after = _band_energy_db(post, 250, 800)
	f2_before = _band_energy_db(samples, 800, 2500)
	f2_after = _band_energy_db(post, 800, 2500)
	f1_limit = 4.0 if st.aggressive else 3.0
	f2_limit = 4.0 if st.aggressive else 3.0
	f1_shift = abs(f1_after - f1_before) if f1_before > -80 else 0
	f2_shift = abs(f2_after - f2_before) if f2_before > -80 else 0
	if f1_shift > f1_limit and f2_shift > f2_limit:
	L(f' Formant shift: F1 Δ={f1_after-f1_before:+.1f}dB F2 Δ={f2_after-f2_before:+.1f}dB — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p3_jitter_injected = True
	L(f' ✓ jitter injected: {jitter_ms:.2f}ms depth={depth_ms:.1f}ms')
	return out


	def _inject_shimmer(wav_path: str, st: IhyaState) -> str:
	"""
	Inject natural amplitude shimmer.
	Uses gentle tremolo at very low depth + slow rate.
	"""
	# Shimmer: very gentle amplitude modulation
	# Natural: 0.2dB variation at ~4-8Hz (§133.3)
	# Use tremolo with extremely low depth
	depth = min(0.15, F0_SHIMMER_DB * 0.1) # ffmpeg tremolo depth is 0-1
	rate = 5.5 + np.random.uniform(-1.5, 1.5) # Hz: natural shimmer rate

	if st.aggressive:
	depth = min(0.25, depth * 1.5)

	out = _tmp_wav('p3b_shimmer', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', f'tremolo=f={rate:.1f}:d={depth:.3f}',
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	return wav_path

	st.p3_shimmer_injected = True
	L(f' ✓ shimmer injected: rate={rate:.1f}Hz depth={depth:.3f}')
	return out


	def _inject_f0_drift(wav_path: str, samples: 'np.ndarray',
	f0_median: float, st: IhyaState) -> str:
	"""
	Inject slow phrase-level F0 drift using subtle pitch shifting.
	Uses ffmpeg's chorus filter with very slow modulation for drift.

	v2 FIX: Chorus parameter format fixed: delays:decays:speeds:depths.
	RMS guard changed from 1.0dB to 2.5dB (drift chorus naturally adds energy).
	"""
	sr = SR
	# Drift amount depends on recitation style
	drift_cents = MUJAWWAD_DRIFT if st.mujawwad_conf > 0.6 else F0_DRIFT_CENTS
	if st.aggressive:
	drift_cents *= 1.3

	# Generate a slow drift contour using chorus at very slow speed + larger depth
	duration_s = len(samples) / sr
	if duration_s < 2.0:
	return wav_path

	# Chorus filter: chorus=input_gain:output_gain:delays:decays:speeds:depths
	# For drift: long delays, moderate decays, very slow speeds, subtle depths
	drift_depth_ms = min(2.5, drift_cents / 12.0) # depth in ms

	# Slow drift chorus: long delay, very slow modulation, subtle depth
	drift_filter = (
	f'chorus=0.7:0.9:'
	f'55\|65\|45:' # delays in ms (3 voices)
	f'0.5\|0.4\|0.3:' # decays (0-1 range, 3 voices)
	f'0.05\|0.03\|0.07:' # speeds in Hz (very slow, 3 voices)
	f'{drift_depth_ms:.1f}\|{drift_depth_ms0.6:.1f}\|{drift_depth_ms0.4:.1f}' # depths in ms (3 voices)
	)

	out = _tmp_wav('p3c_drift', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', drift_filter,
	'-acodec', WAV_CODEC, '-ar', str(sr), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	L(f' F0 drift injection failed — keeping original')
	_cleanup(out)
	return wav_path

	# Guard: spectral sanity
	# v2.1 FIX: Drift chorus adds significant energy naturally.
	# Allow 3.5dB (was 2.5dB which caused too many false reverts).
	post, _ = _decode_samples(out)
	if post is not None and samples is not None:
	delta = _rmsdb(post) - _rmsdb(samples)
	drift_rms_limit = 5.0 if st.aggressive else 3.5 # v2.1: was 2.5, now 3.5
	if abs(delta) > drift_rms_limit:
	L(f' Drift RMS delta={delta:+.2f}dB — REVERT (limit={drift_rms_limit})')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	L(f' ✓ F0 drift injected: {drift_cents:.0f} cents (mujawwad={st.mujawwad_conf:.2f})')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 4: FORMANT RECONSTRUCTION
	# ══════════════════════════════════════════════════════════════════════════════

	def phase4_formant_rebuild(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 4: Rebuild collapsed/missing formants.
	When codec or NR destroys formant structure, voice sounds hollow/thin.
	We boost energy in F1/F2/F3 zones proportionally using the
	FORMANT_MALE_ARABIC reference template for center frequencies.

	v2: Docstring updated — this uses EQ-based formant boosting from the
	Arabic reference template, not LPC analysis (LPC was never implemented).
	"""
	_chk('phase_4_formant_rebuild')

	if artifacts.formant_collapse < 0.2:
	L(f' Formant collapse={artifacts.formant_collapse:.3f} < 0.2 — skipping')
	return wav_path

	# Calculate needed boosts based on collapse severity
	# v2: Use FORMANT_MALE_ARABIC reference for center frequencies
	f1_center = FORMANT_MALE_ARABIC['F1']['typical']
	f2_center = FORMANT_MALE_ARABIC['F2']['typical']
	f3_center = FORMANT_MALE_ARABIC['F3']['typical']

	f1_boost = min(3.0, artifacts.formant_collapse * 4.0) # F1: warmth
	f2_boost = min(4.0, artifacts.formant_collapse * 5.5) # F2: clarity
	f3_boost = min(2.5, artifacts.formant_collapse * 3.0) # F3: presence

	# Scale by Mujawwad confidence — Mujawwad needs F2/F3 more (§145)
	if st.mujawwad_conf > 0.6:
	f2_boost *= 1.2
	f3_boost *= 1.1

	if st.aggressive:
	f1_boost = min(4.5, f1_boost * 1.3)
	f2_boost = min(6.0, f2_boost * 1.3)
	f3_boost = min(4.0, f3_boost * 1.3)

	filters = []
	# F1 boost: warmth and body (using Arabic formant reference)
	if f1_boost > 0.3:
	filters.append(f'equalizer=f={f1_center}:width_type=o:width=1.0:g={f1_boost:.1f}')
	# F2 boost: vowel clarity (using Arabic formant reference)
	if f2_boost > 0.3:
	filters.append(f'equalizer=f={f2_center}:width_type=o:width=1.0:g={f2_boost:.1f}')
	# F3 boost: presence and definition (using Arabic formant reference)
	if f3_boost > 0.3:
	filters.append(f'equalizer=f={f3_center}:width_type=o:width=0.8:g={f3_boost:.1f}')

	if not filters:
	return wav_path

	out = _tmp_wav('p4_formant', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', ','.join(filters),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	return wav_path

	# Guard: check formant ratio improved
	post, _ = _decode_samples(out)
	if post is not None:
	# v2.1 FIX: Re-detect formant collapse from CURRENT state (not original).
	# Previous phases (jitter/shimmer) may have changed spectral balance.
	current_collapse = _detect_formant_collapse(post)
	if current_collapse > _detect_formant_collapse(samples) + 0.1:
	L(f' Formant collapse worsened: was {_detect_formant_collapse(samples):.3f}→{current_collapse:.3f} — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path
	# Sibilant guard: F3 boost shouldn't harshen sibilants
	sib_before = _band_energy_db(samples, 5500, 12000)
	sib_after = _band_energy_db(post, 5500, 12000)
	sib_limit = 4.5 if st.aggressive else 3.0
	if sib_before > -80 and (sib_after - sib_before) > sib_limit:
	L(f' Sibilant harshness: {sib_after-sib_before:+.1f}dB — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p4_formant_rebuilt = True
	L(f' ✓ formant rebuilt: F1({f1_center}Hz)=+{f1_boost:.1f} F2({f2_center}Hz)=+{f2_boost:.1f} F3({f3_center}Hz)=+{f3_boost:.1f}dB')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 5: HARMONIC RICHNESS RESTORATION
	# ══════════════════════════════════════════════════════════════════════════════

	def phase5_harmonic_richness(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 5: Restore harmonic richness to thin/artificial voice.
	Uses aexciter on voiced frames to add natural harmonics.
	Only adds harmonics at F0-derived positions (§80, §152).

	v2: Improved fallback when aexciter isn't available:
	- Try crystalizer first (expands HF dynamics)
	- Then try anoisesrc mixing at -60dB for harmonic texture
	- Only then fall back to shelf EQ
	"""
	_chk('phase_5_harmonic_richness')

	if artifacts.formant_collapse < 0.15 and artifacts.f0_flatness < 0.5:
	L(f' Harmonics OK — skipping')
	return wav_path

	f0 = st.f0_median if st.f0_median > 60 else 150.0

	# aexciter: adds harmonics above a frequency
	# Set the crossover at 1.5× F0 (below voice harmonics region)
	# For male reciter: F0 ~120-250Hz, harmonics start ~300Hz
	freq = min(max(f0 * 1.5, 200.0), 3000.0)
	# v2: Don't boost above active bandwidth
	if artifacts.active_bandwidth_hz < freq + 1000:
	freq = max(f0 * 1.2, artifacts.active_bandwidth_hz * 0.5)

	# Strength scales with artificialness
	strength = min(8.0, artifacts.overall_artificial * 12.0)
	if st.mujawwad_conf > 0.6:
	strength *= 0.7 # §145: gentler on Mujawwad (ornaments can amplify)

	if st.aggressive:
	strength *= 1.3

	if strength < 1.0:
	L(f' Harmonic strength too low ({strength:.1f}) — skipping')
	return wav_path

	# aexciter: freq=crossover, mix=strength percentage
	mix = min(4.0, strength * 0.4) # mix level (0-10 range, keep low)

	out = _tmp_wav('p5_harmonic', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', f'aexciter=freq={freq:.0f}:mix={mix:.1f}',
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	# aexciter might not be available — try crystalizer fallback
	L(f' aexciter failed — trying crystalizer fallback')
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', f'crystalizer=i=2.0:c=1.0',
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	# v2.1 FIX: Reduced noise exciter level and narrower bandpass
	# Previous -65dB was still too audible and was damaging Tajweed features.
	# Now: -75dB (nearly inaudible), narrower bandpass (w=1000)
	duration_s = len(samples) / SR if samples is not None else 10.0
	noise_mix_db = max(-78.0, -75.0 + strength * 0.3) # -75 to -72 dB range
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-f', 'lavfi', '-i', f'anoisesrc=d={duration_s:.1f}:c=pink:r={SR}:a=0.001',
	'-filter_complex',
	f'[1:a]bandpass=f={freq:.0f}:w=1000,volume={noise_mix_db:.0f}dB[noise];'
	f'[0:a][noise]amix=inputs=2:duration=first:dropout_transition=0[out]',
	'-map', '[out]',
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	# Last resort: shelf EQ fallback (doesn't add harmonics but boosts existing HF)
	L(f' anoisesrc failed — using shelf EQ fallback (weaker)')
	shelf_gain = min(2.0, strength * 0.3)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', f'highshelf=f={freq:.0f}:width_type=s:width=0.5:g={shelf_gain:.1f}',
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])
	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	return wav_path

	# Guard: THD check — harmonic excitation shouldn't add excessive distortion
	post, _ = _decode_samples(out)
	if post is not None and samples is not None:
	# Quick THD check on center portion
	c_start = int(len(post) * 0.2)
	c_end = int(len(post) * 0.8)
	c = post[c_start:c_end]
	N = min(len(c), SR * 2)
	if N > SR // 4:
	spec = np.abs(rfft(c[:N] * np.hanning(N))) ** 2
	freqs = rfftfreq(N, d=1.0/SR)
	fund_mask = (freqs >= f0 * 0.8) & (freqs <= f0 * 1.2)
	h2_mask = (freqs >= f0 * 1.8) & (freqs <= f0 * 2.2)
	if fund_mask.any() and h2_mask.any():
	fund_power = float(np.mean(spec[fund_mask]))
	h2_power = float(np.mean(spec[h2_mask]))
	if fund_power > 1e-20:
	h2_ratio = h2_power / fund_power
	# v2.1 FIX: We're TRYING to add harmonics — the H2 limit should be
	# generous. Natural male voice H2/H1 is 0.1-0.5. The guard is only
	# to prevent extreme distortion (>0.6 is genuinely harsh).
	h2_limit = 0.60 if st.aggressive else 0.50
	if h2_ratio > h2_limit: # too much harmonic distortion
	L(f' H2 ratio={h2_ratio:.3f} > {h2_limit} — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p5_harmonic_rich = True
	L(f' ✓ harmonic richness: freq={freq:.0f}Hz mix={mix:.1f} f0={f0:.0f}Hz')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 6: MICRO-DYNAMICS BREATHING
	# ══════════════════════════════════════════════════════════════════════════════

	def phase6_micro_dynamics(wav_path: str, samples: 'np.ndarray',
	st: IhyaState) -> str:
	"""
	Phase 6: Restore natural micro-dynamics.
	Robotic/over-processed audio has compressed dynamics.
	We gently expand the dynamic range to restore natural breathing.
	§85, §133: natural recitation has LRA within PHRASE_LRA_MIN to PHRASE_LRA_MAX.
	Uses BREATH_DEPTH_DB for modulation depth.
	"""
	_chk('phase_6_micro_dynamics')

	if not NUMPY_OK or samples is None:
	return wav_path

	# Measure current dynamics
	lufs, lra = _measure_lufs(wav_path)
	L(f' Current LRA={lra:.2f} target range=[{PHRASE_LRA_MIN},{PHRASE_LRA_MAX}]')

	# Target LRA: midpoint of the natural range
	target_lra = (PHRASE_LRA_MIN + PHRASE_LRA_MAX) / 2.0
	lra_deficit = target_lra - lra
	if lra_deficit < 0.5:
	L(f' LRA deficit={lra_deficit:.2f} < 0.5 — no expansion needed')
	return wav_path

	# Use aexpander to gently expand dynamics
	# Threshold at p30 of voiced RMS
	frame_n = int(0.020 * SR)
	frame_rms = []
	for i in range(0, len(samples) - frame_n, frame_n):
	e = float(np.sqrt(np.mean(samples[i:i+frame_n]**2)))
	if e > 1e-7:
	frame_rms.append(e)

	if not frame_rms:
	return wav_path

	threshold = float(np.percentile(frame_rms, 30))
	ratio = min(1.0 + lra_deficit * 0.12, 1.6) # gentle, capped

	if st.aggressive:
	ratio = min(2.0, ratio * 1.2)

	out = _tmp_wav('p6_dynamics', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', (f'aexpander=threshold={max(0.001,threshold):.5f}'
	f':ratio={ratio:.2f}:attack=3:release=150'),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	return wav_path

	# Guard: LRA must improve but not overshoot
	_, lra_after = _measure_lufs(out)
	lra_max = PHRASE_LRA_MAX + (1.5 if st.aggressive else 1.0)
	if lra_after > lra and lra_after <= lra_max:
	st.p6_micro_dynamics = True
	L(f' ✓ micro-dynamics: LRA {lra:.2f}→{lra_after:.2f} ratio={ratio:.2f}')
	return out
	else:
	L(f' LRA guard failed: {lra:.2f}→{lra_after:.2f} — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 7: SPECTRAL CONTINUITY REPAIR
	# ══════════════════════════════════════════════════════════════════════════════

	def phase7_spectral_repair(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 7: Repair spectral discontinuities from codec artifacts and NR.
	Smooths spectral holes and sharp edges using gentle EQ interpolation.

	v2: Tracks spectral_holes_after even if phase doesn't run.
	Respects active bandwidth — no boosting above detected bandwidth.
	"""
	_chk('phase_7_spectral_repair')

	if artifacts.spectral_holes < 2 and artifacts.spectral_edges < 2:
	L(f' Spectral continuity OK — skipping')
	# v2 FIX: Track spectral_holes_after even if we don't process
	post_check, _ = _decode_samples(wav_path)
	if post_check is not None:
	st.spectral_holes_after, _ = _detect_spectral_holes(post_check)
	return wav_path

	# Strategy: apply gentle spectral smoothing using equalizer banks
	# Fill holes: boost the dropped bands
	# Smooth edges: apply gentle Q bridges between adjacent bands

	filters = []

	# Get current spectral profile
	band_db = {}
	for f in CENTERS_48:
	if f < 80 or f > 16000:
	continue
	# v2: Don't process bands above active bandwidth
	if f > artifacts.active_bandwidth_hz:
	continue
	lo = f / (2 ** (1.0/12))
	hi = f * (2 ** (1.0/12))
	band_db[f] = _band_energy_db(samples, lo, hi)

	# Detect and fill holes
	sorted_f = sorted(band_db.keys())
	for i in range(1, len(sorted_f) - 1):
	prev_db = band_db[sorted_f[i-1]]
	curr_db = band_db[sorted_f[i]]
	next_db = band_db[sorted_f[i+1]]
	neighbor_avg = (prev_db + next_db) / 2.0
	dip = curr_db - neighbor_avg

	if dip < -abs(SPEC_HOLE_DEPTH_DB):
	# Boost this band to fill the hole — but only partially
	# Full fill would sound unnatural; fill 60% of the dip
	fill_frac = 0.75 if st.aggressive else 0.6
	boost = min(4.0 if not st.aggressive else 6.0, abs(dip) * fill_frac)
	q = 8.65 # sixth-octave
	filters.append(f'equalizer=f={sorted_f[i]:.0f}:width_type=q:width={q}:g={boost:.1f}')

	# Smooth sharp edges
	for i in range(1, len(sorted_f)):
	delta = abs(band_db[sorted_f[i]] - band_db[sorted_f[i-1]])
	if delta > SPEC_EDGE_SHARP_DB:
	# Apply a gentle EQ to smooth the transition
	mid_f = np.sqrt(sorted_f[i] * sorted_f[i-1])
	# Gentle cut at the peak side or boost at the valley side
	if band_db[sorted_f[i]] > band_db[sorted_f[i-1]]:
	# Sharp rise — gentle cut at upper band
	cut = min(2.0, (delta - SPEC_EDGE_SHARP_DB) * 0.3)
	filters.append(f'equalizer=f={sorted_f[i]:.0f}:width_type=q:width=4.0:g=-{cut:.1f}')
	else:
	# Sharp drop — gentle boost at lower band
	boost = min(2.0, (delta - SPEC_EDGE_SHARP_DB) * 0.3)
	filters.append(f'equalizer=f={sorted_f[i-1]:.0f}:width_type=q:width=4.0:g={boost:.1f}')

	if not filters:
	L(f' No spectral repair filters needed')
	# v2: Track spectral_holes_after even when no filters needed
	post_check, _ = _decode_samples(wav_path)
	if post_check is not None:
	st.spectral_holes_after, _ = _detect_spectral_holes(post_check)
	return wav_path

	# Limit total filter count (ffmpeg has practical limits)
	filters = filters[:20]

	out = _tmp_wav('p7_spectral', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', ','.join(filters),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	L(f' Spectral repair failed — keeping original')
	_cleanup(out)
	return wav_path

	# Guard: overall spectral smoothness should improve
	post, _ = _decode_samples(out)
	if post is not None:
	new_holes, _ = _detect_spectral_holes(post)
	st.spectral_holes_after = new_holes
	if new_holes > artifacts.spectral_holes:
	L(f' Spectral holes increased: {artifacts.spectral_holes}→{new_holes} — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p7_spectral_repair = True
	L(f' ✓ spectral repair: {len(filters)} filters applied')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 8: SIBILANT NATURALIZATION
	# ══════════════════════════════════════════════════════════════════════════════

	def phase8_sibilant_naturalization(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 8: Naturalize sibilants (ش/س/ص/ز).
	Codec and NR often destroy sibilant texture, making them sound
	artificial (too sharp or too dull). This phase:
	- If sibilants too dull (destroyed): boost Safir band (5.5-12kHz)
	- If sibilants too sharp (harsh): de-ess the Safir band
	§152: Arabic sibilant spectral characteristics.
	"""
	_chk('phase_8_sibilant_nat')

	if artifacts.sibilant_quality > 0.8:
	L(f' Sibilant quality={artifacts.sibilant_quality:.2f} > 0.8 — OK')
	return wav_path

	# Measure current sibilant balance
	mid_energy = _band_energy(samples, 1000, 3000)
	safir_energy = _band_energy(samples, 5500, 12000)

	if mid_energy < 1e-20:
	return wav_path

	ratio_db = 10 * np.log10(safir_energy / (mid_energy + 1e-20))

	filters = []

	if ratio_db < -25:
	# Sibilants destroyed by NR/codec — boost them back
	boost = min(4.0 if not st.aggressive else 6.0, (-25 - ratio_db) * 0.3)
	# v2: Don't boost above active bandwidth
	bw = artifacts.active_bandwidth_hz
	if bw >= 6000:
	filters.append(f'equalizer=f=6000:width_type=o:width=0.8:g={boost:.1f}')
	if bw >= 8000:
	filters.append(f'equalizer=f=8000:width_type=o:width=0.7:g={boost*0.8:.1f}')
	if bw >= 10000:
	filters.append(f'equalizer=f=10000:width_type=o:width=0.6:g={boost*0.5:.1f}')
	L(f' Sibilant deficit: {ratio_db:.1f}dB — boosting +{boost:.1f}dB')
	elif ratio_db > -3:
	# Sibilants harsh/artificial — de-ess
	cut = min(3.0 if not st.aggressive else 4.5, (ratio_db + 3) * 0.5)
	filters.append(f'equalizer=f=6000:width_type=o:width=0.8:g=-{cut:.1f}')
	filters.append(f'equalizer=f=8000:width_type=o:width=0.7:g=-{cut*0.7:.1f}')
	L(f' Sibilant harsh: {ratio_db:.1f}dB — cutting -{cut:.1f}dB')
	else:
	# Moderate — subtle texture enhancement
	# Add slight breathiness texture via high-frequency presence
	# This makes sibilants sound more natural/airy
	filters.append(f'equalizer=f=7000:width_type=o:width=0.8:g=0.8')
	L(f' Sibilant moderate: subtle texture enhancement')

	if not filters:
	return wav_path

	out = _tmp_wav('p8_sibilant', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', ','.join(filters),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	return wav_path

	# Guard: verify sibilant quality improved
	post, _ = _decode_samples(out)
	if post is not None:
	new_quality = _detect_sibilant_quality(post)
	if new_quality < artifacts.sibilant_quality - 0.1:
	L(f' Sibilant quality worsened: {artifacts.sibilant_quality:.2f}→{new_quality:.2f} — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	st.p8_sibilant_nat = True
	L(f' ✓ sibilant naturalization applied')
	return out


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 9: TEMPORAL ENVELOPE SHAPING
	# ══════════════════════════════════════════════════════════════════════════════

	def phase9_temporal_shaping(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	Phase 9: Restore natural temporal envelope.
	Artificial/processed audio often has smeared consonant-vowel boundaries
	and flattened transients. This phase:
	- Sharpens consonant attacks (Qalqalah preservation, §35)
	- Restores natural vowel onset/offset shapes
	- Uses gentle expansion on transient regions

	v2: Added second sub-pass that boosts 2-4kHz briefly on transient
	onsets for consonant sharpening (presence boost).
	"""
	_chk('phase_9_temporal_shaping')

	# Measure current crest factor — if too low, transients are smeared
	rms_db, crest_db = _measure_rms_crest(samples)
	target_crest = TARGET['crest']

	crest_deficit = target_crest - crest_db
	if crest_deficit < 1.0:
	L(f' Crest={crest_db:.1f}dB OK (target={target_crest:.1f}) — skipping')
	return wav_path

	L(f' Crest deficit={crest_deficit:.1f}dB — applying transient shaping')

	# Strategy: gentle expansion on quiet-to-loud transitions
	# This sharpens consonant attacks without changing overall dynamics
	frame_n = int(0.010 * SR) # 10ms frames for fine transient detection
	frame_rms = np.array([float(np.sqrt(np.mean(samples[iframe_n:(i+1)frame_n]**2)))
	for i in range(len(samples) // frame_n)])

	# Find transient frames (sudden energy increase)
	if len(frame_rms) < 20:
	return wav_path

	# Use aexpander with fast attack to catch transients
	# Threshold at p40 of voiced frames
	voiced_rms = frame_rms[frame_rms > 1e-5]
	if len(voiced_rms) < 10:
	return wav_path

	threshold = float(np.percentile(voiced_rms, 40))
	ratio = min(1.0 + crest_deficit * 0.08, 1.5) # gentle

	if st.aggressive:
	ratio = min(1.8, ratio * 1.2)

	# Sub-pass 1: Broadband expansion for transient recovery
	out = _tmp_wav('p9_temporal', st)
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', (f'aexpander=threshold={max(0.001,threshold):.5f}'
	f':ratio={ratio:.2f}:attack=1:release=50'),
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out
	])

	if rc != 0 or not os.path.exists(out):
	_cleanup(out)
	return wav_path

	# Sub-pass 2: v2 — Consonant presence boost (2-4kHz) on transient onsets
	# Uses fast-attack compression on 2-4kHz band to sharpen consonant-vowel boundaries
	# This makes consonants like ت/ك/ق/ب more distinct
	presence_boost = min(2.0, crest_deficit * 0.15)
	if st.aggressive:
	presence_boost = min(3.0, presence_boost * 1.3)

	if presence_boost > 0.3:
	# Apply presence EQ + gentle compression for transient sharpening
	# The 2-4kHz range is where consonant articulation energy lives
	presence_filter = (
	f'equalizer=f=3000:width_type=o:width=0.5:g={presence_boost:.1f},'
	f'aemphasis=1:replay_gain=track'
	)
	out2 = _tmp_wav('p9_presence', st)
	rc2, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', out,
	'-af', presence_filter,
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '1',
	'-loglevel', 'error', out2
	])

	if rc2 == 0 and os.path.exists(out2):
	# Verify presence boost didn't over-brighten
	post2, _ = _decode_samples(out2)
	if post2 is not None:
	# Check sibilant band isn't over-boosted
	sib_before = _band_energy_db(samples, 5500, 12000)
	sib_after = _band_energy_db(post2, 5500, 12000)
	if sib_before > -80 and (sib_after - sib_before) < 3.0:
	_cleanup(out)
	out = out2
	L(f' ✓ presence boost: +{presence_boost:.1f}dB at 2-4kHz')
	else:
	L(f' Presence boost too bright — keeping expansion only')
	_cleanup(out2)
	else:
	_cleanup(out2)
	else:
	_cleanup(out2)

	# Guard: crest should improve but not exceed target by much
	post, _ = _decode_samples(out)
	if post is not None:
	_, new_crest = _measure_rms_crest(post)
	crest_max = target_crest + (3.0 if st.aggressive else 2.0)
	if new_crest > crest_db and new_crest <= crest_max:
	st.p9_temporal_shaping = True
	L(f' ✓ temporal shaping: crest {crest_db:.1f}→{new_crest:.1f}dB')
	return out
	else:
	L(f' Crest guard failed: {crest_db:.1f}→{new_crest:.1f} — REVERT')
	_cleanup(out)
	st.guard_reverts += 1
	return wav_path

	return wav_path


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 10: TAJWEED PHONEME GUARDS
	# ══════════════════════════════════════════════════════════════════════════════

	def phase10_guards(original_samples: 'np.ndarray', processed_wav: str,
	st: IhyaState) -> str:
	"""
	Phase 10: Verify Tajweed-critical phoneme features survived processing.
	Seven guards from §35, §52, §143, §152.
	WARN-only by design — naturalness improvement outweighs mild phoneme loss.
	"""
	_chk('phase_10_guards')

	if not NUMPY_OK or original_samples is None:
	L(f' No samples for guards — skip')
	return processed_wav

	proc_samples, _ = _decode_samples(processed_wav)
	if proc_samples is None:
	return processed_wav

	n = min(len(original_samples), len(proc_samples))
	o = original_samples[:n]
	p = proc_samples[:n]

	def chk(name, cond, detail):
	entry = f'{name}: {detail}'
	if cond:
	st.guard_pass.append(entry)
	L(f' [PASS] {entry}')
	else:
	st.guard_warn.append(entry)
	L(f' [WARN] {entry}')

	# G1 Ghunnah 220-320Hz (§152.3)
	go = _band_energy(o, GHUNNAH_BAND); gp = _band_energy(p, GHUNNAH_BAND)
	if go > 1e-15:
	d = 10 * np.log10(gp / go + 1e-20)
	chk('G1-Ghunnah', d >= -3.0,
	f'{d:+.1f}dB {"OK" if d>=-3 else "nasal murmur at risk"}')

	# G2 Ikhfa 250-420Hz (§52.5)
	io = _band_energy(o, IKHFA_BAND); ip = _band_energy(p, IKHFA_BAND)
	if io > 1e-15:
	d = 10 * np.log10(ip / io + 1e-20)
	chk('G2-Ikhfa', d >= -4.0,
	f'{d:+.1f}dB {"OK" if d>=-4 else "nasalisation at risk"}')

	# G3 Qalqalah burst (§52.7, §143)
	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')

	# G4 Ra trill AM 22-40Hz
	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[RA_TRILL_AM_BAND[0]:RA_TRILL_AM_BAND[1]]))
	am_p = float(np.mean(ef_p[RA_TRILL_AM_BAND[0]:RA_TRILL_AM_BAND[1]]))
	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 {len(am_ratios)} windows)')

	# G5 Safir 5500-12000Hz (§152.3)
	so = _band_energy(o, SAFIR_BAND); sp = _band_energy(p, SAFIR_BAND)
	if so > 1e-15:
	d = 10 * np.log10(sp / so + 1e-20)
	chk('G5-Safir', d >= -5.0,
	f'{d:+.1f}dB {"OK" if d>=-5 else "sibilants at risk"}')

	# G6 Tafasshi 3000-8000Hz (§152.3)
	to = _band_energy(o, TAFASSHI_BAND); tp = _band_energy(p, TAFASSHI_BAND)
	if to > 1e-15:
	d = 10 * np.log10(tp / to + 1e-20)
	chk('G6-Tafasshi', d >= -4.0,
	f'{d:+.1f}dB {"OK" if d>=-4 else "ش spread at risk"}')

	# G7 Formant F2 preservation (§4)
	f2o = _band_energy(o, 800, 2500); f2p = _band_energy(p, 800, 2500)
	if f2o > 1e-15:
	d = 10 * np.log10(f2p / f2o + 1e-20)
	chk('G7-Formant-F2', d >= -3.0,
	f'{d:+.1f}dB {"OK" if d>=-3 else "formant clarity at risk"}')

	total_g = len(st.guard_pass) + len(st.guard_warn)
	if st.guard_warn:
	L(f' ⚠ {len(st.guard_warn)}/{total_g} warnings — check output for Tajweed artifacts')
	else:
	L(f' ✓ All {total_g} guards passed')

	st.p10_guards_ok = len(st.guard_warn) == 0
	return processed_wav


	# ══════════════════════════════════════════════════════════════════════════════
	# Phase 11: FINAL LOUDNESS + QUALITY OPTIMIZATION
	# ══════════════════════════════════════════════════════════════════════════════

	def phase11_final(wav_path: str, st: IhyaState) -> Tuple[str, Dict]:
	"""
	Phase 11: Final loudness normalization + quality optimization.
	- Target LUFS from reference model
	- True peak limiting
	- Gentle dynamic normalization for evenness
	- Stereo output encode
	"""
	_chk('phase_11_final')

	# Measure current levels
	lufs, lra = _measure_lufs(wav_path)
	L(f' Pre-final: LUFS={lufs:.2f} LRA={lra:.2f}')

	# Build final filter chain
	# 1. dynaudnorm for level evenness
	# 2. Volume adjustment to target LUFS
	# 3. Limiter for true peak
	vol_delta = TARGET['lufs'] - lufs
	# Cap volume adjustment
	vol_delta = max(-12.0, min(12.0, vol_delta))

	final_af = (
	f'dynaudnorm=f=500:g=31:p=0.92:m=10:r=0.0:b=1,'
	f'volume={vol_delta:.2f}dB,'
	f'alimiter=level_in=1:level_out=1:limit=0.89:attack=5:release=50'
	)

	out = st.output_path
	rc, _, err = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-af', final_af,
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2',
	'-loglevel', 'error', out
	])

	if rc != 0:
	L(f' Final encode failed: {err[:80]}')
	# Fallback: just copy
	rc2, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-acodec', WAV_CODEC, '-ar', str(SR), '-ac', '2', out
	])
	if rc2 != 0:
	L(f' Fallback encode also failed')
	return wav_path, {}

	# Final measurements
	final_lufs, final_lra = _measure_lufs(out)
	final_samples, _ = _decode_samples(out)
	final_rms, final_crest = _measure_rms_crest(final_samples) if final_samples is not None else (-99, 0)

	report = {
	'lufs': final_lufs,
	'lra': final_lra,
	'rms': final_rms,
	'crest': final_crest,
	'vol_delta_db': vol_delta,
	}

	L(f' Final: LUFS={final_lufs:.2f} LRA={final_lra:.2f} '
	f'Crest={final_crest:.1f}dB vol={vol_delta:+.2f}dB')

	st.p11_final_done = True
	return out, report


	# ══════════════════════════════════════════════════════════════════════════════
	# NATURALNESS SCORE (v2)
	# ══════════════════════════════════════════════════════════════════════════════

	def _compute_naturalness_score(st: IhyaState, artifacts: ArtifactReport,
	final_samples: Optional['np.ndarray']) -> float:
	"""
	Compute a composite naturalness score (0-100).
	Similar to Itiqan's quality score. Includes:
	- F0 flatness improvement
	- Spectral hole reduction
	- Metallic score reduction
	- Formant improvement
	- Sibilant quality
	- Guard pass rate
	- Perceptual band quality (using _PERC_WEIGHT)

	Returns score 0-100 (higher = more natural).
	"""
	if not NUMPY_OK:
	return 50.0

	score = 50.0 # start at 50 (neutral)

	# ── F0 flatness improvement: up to ±15 points ──
	f0_improvement = st.f0_flatness_before - st.f0_flatness_after
	score += float(np.clip(f0_improvement * 30, -10, 15))

	# ── Spectral hole reduction: up to ±10 points ──
	hole_reduction = st.spectral_holes_before - st.spectral_holes_after
	score += float(np.clip(hole_reduction * 2, -5, 10))

	# ── Metallic score reduction: up to ±10 points ──
	metallic_reduction = st.metallic_before - st.metallic_after
	score += float(np.clip(metallic_reduction * 20, -5, 10))

	# ── Formant improvement: up to +10 points ──
	if artifacts.formant_collapse < 0.2:
	score += 10.0
	elif artifacts.formant_collapse < 0.4:
	score += 5.0
	elif artifacts.formant_collapse > 0.7:
	score -= 5.0

	# ── Sibilant quality: up to +10 points ──
	score += float(np.clip(artifacts.sibilant_quality * 10, -5, 10))

	# ── Guard pass rate: up to +5 points ──
	total_guards = len(st.guard_pass) + len(st.guard_warn)
	if total_guards > 0:
	pass_rate = len(st.guard_pass) / total_guards
	score += pass_rate * 5.0
	else:
	score += 2.5 # no guards to fail = neutral

	# ── Revert penalty: up to -10 points ──
	score -= min(10, st.guard_reverts * 2.0)

	# ── Perceptual band quality (using _PERC_WEIGHT): up to +5 points ──
	if final_samples is not None and artifacts is not None:
	perc_score = 0.0
	n_bands = 0
	for freq, weight in _PERC_WEIGHT.items():
	# Check if band energy is reasonable (not too hot/cold)
	lo = freq / (2 ** (1.0/6))
	hi = freq * (2 ** (1.0/6))
	band_e = _band_energy_db(final_samples, lo, hi)
	# Reasonable band energy: -60 to -5 dB
	if -50 < band_e < -5:
	perc_score += weight
	n_bands += 1
	if n_bands > 0:
	perc_norm = perc_score / sum(_PERC_WEIGHT.values())
	score += perc_norm * 5.0

	return float(max(0.0, min(100.0, score)))


	# ══════════════════════════════════════════════════════════════════════════════
	# TIER_TELEPHONE: BANDWIDTH EXTENSION PHASE (§173)
	# ══════════════════════════════════════════════════════════════════════════════

	def _telephone_soft_declip(samples: 'np.ndarray') -> 'np.ndarray':
	"""
	Soft-knee declip via tanh saturation (§173 Step 0).
	Converts hard-clipped peaks into soft saturation before feeding BWE models.
	Very light: threshold=0.97, maps anything above to gentle saturation.
	"""
	CLIP_THRESH = 0.97
	clip_count = int(np.sum(np.abs(samples) > CLIP_THRESH))
	if clip_count == 0:
	return samples
	# tanh saturation: y = tanh(x * (1/CLIP_THRESH)) * CLIP_THRESH
	# smooth approximation to clipping that avoids hard corners
	out = np.tanh(samples * (1.0 / CLIP_THRESH)) * CLIP_THRESH
	L(f' Soft declip: {clip_count} samples above {CLIP_THRESH:.2f} → tanh-limited')
	return out


	def _telephone_crossover_blend(original: 'np.ndarray',
	extended: 'np.ndarray',
	cutoff_hz: float,
	sr: int = SR) -> 'np.ndarray':
	"""
	Crossover blend — §173 Step 5 (Pipeline B, blend step).

	Preserves original signal below cutoff_hz bit-for-bit,
	uses BWE output only above cutoff_hz.

	This is the CRITICAL safety net:
	- Original 0–cutoff_hz: guaranteed authentic (no synthesis)
	- BWE cutoff_hz–22kHz: synthesised / plausible but not certain
	- Red Line 18: caller must tag output as 'BWE-processed / synthetic HF'

	Implementation: 8th-order Butterworth LR crossover (Linkwitz-Riley
	equivalent via cascade). -3dB at cutoff_hz.
	Uses scipy.signal.butter(order//2) applied twice for steeper slope.
	"""
	# Pad to same length
	n = min(len(original), len(extended))
	orig = original[:n]
	ext = extended[:n]

	nyq = sr / 2.0
	fc = float(np.clip(cutoff_hz, 100.0, nyq * 0.98))
	wn = fc / nyq

	# Low-pass on original (preserve authentic band)
	sos_lo = butter(TELEPHONE_BLEND_ORDER, wn, btype='low', output='sos')
	# High-pass on extended (take only the synthesised new content)
	sos_hi = butter(TELEPHONE_BLEND_ORDER, wn, btype='high', output='sos')

	lo = sosfilt(sos_lo, orig)
	hi = sosfilt(sos_hi, ext)

	blended = lo + hi
	# Normalise peak to avoid clipping from blend summation
	peak = float(np.max(np.abs(blended)))
	if peak > 0.98:
	blended = blended * (0.98 / peak)
	L(f' Blend: peak {peak:.3f} → normalised to 0.98')

	return blended.astype(np.float32)


	def phase_telephone_bwe(wav_path: str, samples: 'np.ndarray',
	artifacts: ArtifactReport, st: IhyaState) -> str:
	"""
	TIER_TELEPHONE Bandwidth Extension — §173 Pipeline B-lite.

	This is the ONLY viable treatment when codec_cutoff ≤ 4 kHz.
	All standard enhancement passes (NR, harmonics, EQ above 3kHz) are
	USELESS on this tier and are bypassed by the caller.

	§171 Guards enforced here:
	G1 (R-3 BWE): No PCHIP harmonic inference (only ~13 harmonics present).
	G2 (EQ): No EQ boost above 3kHz before VoiceFixer.
	G3 (DF3): No DeepFilterNet AFTER VoiceFixer (would suppress syn. HF).

	Pipeline:
	Step 0 Soft declip (tanh saturation, threshold 0.97)
	Step 1 Resample to 44100 Hz (VoiceFixer internal requirement)
	Step 2 VoiceFixer Mode 0 — ResUNet discriminative NB→WB/fullband
	mode=0 preferred: least hallucination, best phoneme fidelity
	mode=2 (HiFi-GAN) avoided: alters Arabic phoneme identity (§173)
	Step 3 Resample VF output back to 48 kHz
	Step 4 Crossover blend: original 0–cutoff + VF output cutoff–22kHz
	Guarantees authentic signal below cutoff (Red Line 18)
	Step 5 AudioSR Stage B (optional) — only if audiosr is installed
	Applies AFTER VoiceFixer so AudioSR receives wideband input
	(not raw 3.4kHz telephone audio — §173 Colab recipe)
	guidance_scale=2.5 (reduced from default 3.5: less hallucination)

	KB refs: §169 §170 §171 §172 §173
	"""
	_chk('phase_telephone_bwe')
	L(f' ★ TIER_TELEPHONE — BWE-first pipeline (§173)')
	L(f' ★ Cutoff: {artifacts.telephone_cutoff_hz:.0f} Hz '
	f'Missing: {artifacts.telephone_cutoff_hz:.0f}–22000 Hz '
	f'({100.0*(22000-artifacts.telephone_cutoff_hz)/22000:.0f}% of spectrum is synthesised)')
	L(f' ★ NR / harmonic / EQ passes BYPASSED (§171 guards active)')

	if not NUMPY_OK:
	L(' SKIP: numpy not available')
	return wav_path

	if not VOICEFIXER_OK:
	L('')
	L(' ╔══════════════════════════════════════════════════════════╗')
	L(' ║ VoiceFixer NOT INSTALLED — BWE cannot proceed ║')
	L(' ║ Install: pip install voicefixer ║')
	L(' ║ TIER_TELEPHONE audio will NOT be enhanced ║')
	L(' ╚══════════════════════════════════════════════════════════╝')
	L('')
	L(' Passing audio through unchanged (standard phases also bypassed)')
	return wav_path

	cutoff_hz = artifacts.telephone_cutoff_hz or 3400.0

	# ── Step 0: Soft declip ───────────────────────────────────────────────────
	samples_dc = _telephone_soft_declip(samples)

	# ── Step 1: Write declipped samples as 44100 Hz WAV for VoiceFixer ───────
	# VoiceFixer resamples internally to 44100; provide it at 44100 mono.
	wav_44k = _tmp_wav('tel_44k', st)

	# Write float32 samples via ffmpeg pipe (avoids soundfile dependency)
	try:
	raw_bytes = samples_dc.astype(np.float32).tobytes()
	pipe_cmd = [
	'ffmpeg', '-y', '-loglevel', 'error',
	'-f', 'f32le', '-ar', str(SR), '-ac', '1', '-i', 'pipe:0',
	'-ar', '44100', '-ac', '1', '-acodec', 'pcm_s16le', wav_44k,
	]
	proc = subprocess.run(pipe_cmd, input=raw_bytes,
	capture_output=True, timeout=300)
	if proc.returncode != 0 or not os.path.exists(wav_44k):
	L(f' Resample→44100 failed, trying file-based route')
	rc, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', wav_path,
	'-ar', '44100', '-ac', '1', '-acodec', 'pcm_s16le', wav_44k,
	'-loglevel', 'error',
	])
	if rc != 0:
	L(f' Resample→44100 failed entirely — BWE aborted')
	return wav_path
	except Exception as ex:
	L(f' Resample write error: {ex} — BWE aborted')
	return wav_path

	L(f' 44100 Hz WAV written: {wav_44k}')

	# ── Step 2: VoiceFixer Mode 0 ─────────────────────────────────────────────
	vf_out_44k = _tmp_wav('tel_vf44', st)
	vf_success = False
	try:
	L(f' VoiceFixer Mode 0 (ResUNet discriminative) — loading…')
	vf = _VoiceFixer()
	# cuda=False: safe default; user can override if GPU available
	# mode=0: discriminative ResUNet — best phoneme fidelity for Arabic (§173)
	# mode=2 (HiFi-GAN) deliberately avoided — alters phoneme identity
	vf.restore(input=wav_44k, output=vf_out_44k, mode=0, cuda=False)
	if os.path.exists(vf_out_44k) and os.path.getsize(vf_out_44k) > 1000:
	L(f' VoiceFixer Mode 0: OK → {vf_out_44k}')
	vf_success = True
	st.telephone_bwe_mode = 'voicefixer_mode0'
	else:
	L(f' VoiceFixer produced empty output — BWE aborted')
	except Exception as ex:
	L(f' VoiceFixer failed: {ex}')

	if not vf_success:
	_cleanup(wav_44k)
	return wav_path

	# ── Step 3: Resample VoiceFixer output back to 48 kHz ────────────────────
	wav_vf_48k = _tmp_wav('tel_vf48', st)
	rc, _, err = _run_ffmpeg([
	'ffmpeg', '-y', '-i', vf_out_44k,
	'-ar', str(SR), '-ac', '1', '-acodec', WAV_CODEC, wav_vf_48k,
	'-loglevel', 'error',
	])
	_cleanup(wav_44k, vf_out_44k)
	if rc != 0 or not os.path.exists(wav_vf_48k):
	L(f' Resample→48k failed: {err[:60]}')
	return wav_path

	# ── Step 4: Crossover blend ────────────────────────────────────────────────
	# Load VF output at 48 kHz
	vf_samples, _ = _decode_samples(wav_vf_48k)
	if vf_samples is None:
	L(f' Could not decode VF output — using VF output as-is')
	# Still an improvement over the raw telephone audio
	blended_wav = wav_vf_48k
	st.telephone_bwe_applied = True
	else:
	L(f' Crossover blend at {cutoff_hz:.0f} Hz '
	f'(orig 0–{cutoff_hz:.0f}Hz + VF {cutoff_hz:.0f}–22kHz)')
	blended = _telephone_crossover_blend(samples_dc, vf_samples, cutoff_hz, SR)

	# Write blended result
	blended_wav = _tmp_wav('tel_blend', st)
	try:
	raw_bytes = blended.astype(np.float32).tobytes()
	pipe_cmd = [
	'ffmpeg', '-y', '-loglevel', 'error',
	'-f', 'f32le', '-ar', str(SR), '-ac', '1', '-i', 'pipe:0',
	'-acodec', WAV_CODEC, '-ar', str(SR), blended_wav,
	]
	proc = subprocess.run(pipe_cmd, input=raw_bytes,
	capture_output=True, timeout=300)
	if proc.returncode != 0 or not os.path.exists(blended_wav):
	L(f' Blend write failed — using raw VF output')
	blended_wav = wav_vf_48k
	else:
	_cleanup(wav_vf_48k)
	L(f' Blend written: {blended_wav}')
	except Exception as ex:
	L(f' Blend write error: {ex} — using raw VF output')
	blended_wav = wav_vf_48k

	st.telephone_bwe_applied = True

	# ── Step 5: AudioSR Stage B (optional) ───────────────────────────────────
	# §173 Colab recipe: AudioSR on VoiceFixer OUTPUT (not raw telephone audio)
	# Only run if audiosr is installed. guidance_scale reduced to 2.5 (§172-E).
	# Guard (§171): AudioSR not applied to raw 3.4kHz audio — VF must run first.
	if AUDIOSR_OK and st.telephone_bwe_applied:
	L(f' AudioSR Stage B (WB→48kHz) — guidance_scale=2.5 (low hallucination)')
	asr_out = _tmp_wav('tel_asr', st)
	try:
	asr_model = _audiosr.build_model(model_name='basic')
	asr_wave = _audiosr.super_resolution(
	asr_model,
	blended_wav,
	guidance_scale=2.5, # reduced from default 3.5 (§172-E: less hallucination)
	ddim_steps=50,
	)
	_audiosr.save_wave(asr_wave, inputpath=blended_wav,
	savepath=os.path.dirname(asr_out))
	# audiosr saves with its own naming convention — locate it
	asr_candidate = os.path.join(
	os.path.dirname(asr_out),
	Path(blended_wav).stem + '_audiosr.wav'
	)
	if not os.path.exists(asr_candidate):
	# Try common naming
	for p in Path(os.path.dirname(asr_out)).glob('audiosr'):
	asr_candidate = str(p)
	break
	if os.path.exists(asr_candidate):
	# Resample to 48k in case AudioSR output 44.1k
	rc2, _, _ = _run_ffmpeg([
	'ffmpeg', '-y', '-i', asr_candidate,
	'-ar', str(SR), '-ac', '1', '-acodec', WAV_CODEC, asr_out,
	'-loglevel', 'error',
	])
	if rc2 == 0 and os.path.exists(asr_out):
	_cleanup(blended_wav)
	blended_wav = asr_out
	st.telephone_audiosr_applied = True
	L(f' AudioSR Stage B: OK → {blended_wav}')
	else:
	L(f' AudioSR resample failed — keeping VF output')
	else:
	L(f' AudioSR output not found — keeping VF output')
	except Exception as ex:
	L(f' AudioSR failed: {ex} — keeping VF output')
	elif not AUDIOSR_OK:
	L(f' AudioSR not installed (optional Stage B). pip install audiosr')
	L(f' VoiceFixer output used as final BWE result')

	# ── Summary ───────────────────────────────────────────────────────────────
	L(f'')
	L(f' ╔══════════════════════════════════════════════════════════╗')
	L(f' ║ BWE COMPLETE — §173 ║')
	L(f' ║ Mode: {st.telephone_bwe_mode:<49}║')
	L(f' ║ AudioSR Stage B: {"YES" if st.telephone_audiosr_applied else "NO (not installed)":<40}║')
	L(f' ║ ★ Red Line 18: output tagged BWE-processed/synthetic HF ║')
	L(f' ╚══════════════════════════════════════════════════════════╝')
	L(f'')

	return blended_wav

	def process(input_path: str, output_path: str,
	force_tier: str = '',
	mujawwad_override: float = -1.0,
	skip_dereverb: bool = False,
	skip_f0_revival: bool = False,
	aggressive: bool = False,
	verbose: bool = True) -> Dict:
	"""
	الإحياء — main entry point.
	Returns dict with full diagnostics.
	v2: Added aggressive mode, improved sample tracking, naturalness score.
	"""
	t0 = time.time()
	st = IhyaState(input_path=input_path, output_path=output_path, t0=t0,
	aggressive=aggressive)

	L(f'\n{"═"*60}')
	L(f' الإحياء {__version__} — إحياء الصوت البشري')
	L(f' Input: {Path(input_path).name}')
	L(f' Output: {Path(output_path).name}')
	if aggressive:
	L(f' Mode: AGGRESSIVE')
	L(f'{"═"*60}')

	if not NUMPY_OK:
	L(' ERROR: numpy not installed — pip install numpy scipy')
	return {'error': 'numpy required', 'score': 0}

	# ── Decode input ───────────────────────────────────────────────────────────
	work_wav = _tmp_wav('input', st)
	if not _decode_to_wav(input_path, work_wav):
	return {'error': f'Failed to decode: {input_path}', 'score': 0}

	st.duration_s = _get_duration(work_wav)
	st.bitrate_kbps = _get_bitrate(input_path)
	L(f' Duration={st.duration_s:.1f}s Bitrate={st.bitrate_kbps}kbps')

	samples, sr = _decode_samples(work_wav)
	if samples is None:
	return {'error': 'Failed to decode samples', 'score': 0}

	original_samples = samples.copy() # keep for guards

	# ── Phase 0: Deep Analysis ────────────────────────────────────────────────
	artifacts = phase0_analyze(samples, sr, st)

	# If audio is already natural, skip most processing
	artificial_thresh = 0.10 if aggressive else 0.15
	if artifacts.overall_artificial < artificial_thresh:
	L(f'\n ══ Audio appears natural (artificialness={artifacts.overall_artificial:.3f})')
	L(f' ══ Minimal processing only')
	else:
	L(f'\n ══ Artificialness detected: {artifacts.overall_artificial:.3f}')
	L(f' ══ Full revival pipeline activated')

	# Override mujawwad if requested
	if mujawwad_override >= 0:
	st.mujawwad_conf = mujawwad_override
	artifacts.mujawwad_conf = mujawwad_override

	current_wav = work_wav

	# v2: Initialize "after" tracking to "before" values (will be updated)
	st.spectral_holes_after = st.spectral_holes_before
	st.metallic_after = st.metallic_before
	st.f0_flatness_after = st.f0_flatness_before

	try:
	# ══════════════════════════════════════════════════════════════════════
	# TIER_TELEPHONE: BWE-first pipeline (§173)
	# Standard enhancement passes are BYPASSED for this tier.
	# Guards enforced (§171):
	# G1: No R-3 PCHIP harmonic inference (codec_cutoff < 5000 Hz)
	# G2: No EQ boost above 3kHz before BWE
	# G3: No DeepFilterNet AFTER VoiceFixer (suppresses synthesised HF)
	# ══════════════════════════════════════════════════════════════════════
	if artifacts.is_telephone_tier:
	# Run BWE phase (soft-declip → VoiceFixer → crossover blend)
	current_wav = phase_telephone_bwe(current_wav, samples, artifacts, st)

	# After BWE: update working samples
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# BYPASSED passes (§171 — useless / harmful on TIER_TELEPHONE):
	L('\n── phase_1_dereverb ── SKIP (TIER_TELEPHONE: no useful reverb info)')
	L('── phase_2_noise_repair── SKIP (TIER_TELEPHONE: no noise, BWE already ran)')
	L('── phase_3_f0_revival ── SKIP (TIER_TELEPHONE: harmonics were absent, now synthesised)')
	L('── phase_4_formant ── SKIP (TIER_TELEPHONE: VoiceFixer handles formants)')
	L('── phase_5_harmonics ── SKIP (TIER_TELEPHONE: G1 guard — codec_cutoff < 5000 Hz)')
	L('── phase_7_spectral ── SKIP (TIER_TELEPHONE: G2 guard — no EQ above 3kHz pre-BWE)')
	L('── phase_8_sibilant ── SKIP (TIER_TELEPHONE: G3 guard — sibilants are synthesised)')

	# ALLOWED passes (neutral / helpful after BWE):
	# P6 micro-dynamics: restore natural loudness variation
	current_wav = phase6_micro_dynamics(current_wav, cur_samples, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# P9 temporal shaping: very light — transient restoration
	# Guard: skip presence boost (3-5kHz is synthesised, §173 post-VF EQ)
	current_wav = phase9_temporal_shaping(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# Update after-metrics
	if cur_samples is not None and len(cur_samples) > SR:
	st.spectral_holes_after, _ = _detect_spectral_holes(cur_samples)
	st.metallic_after = _detect_metallic_ringing(cur_samples)
	f0_post, _ = _detect_f0(cur_samples)
	if len(f0_post) > 10:
	st.f0_flatness_after = _compute_f0_flatness(f0_post)

	# P10 guards + P11 final (always run)
	current_wav = phase10_guards(original_samples, current_wav, st)
	final_wav, final_report = phase11_final(current_wav, st)

	final_samples, _ = _decode_samples(final_wav)
	st.naturalness_score = _compute_naturalness_score(st, artifacts, final_samples)

	elapsed = time.time() - t0

	L(f'\n{"═"*60}')
	L(f' الإحياء {__version__} — COMPLETE (TIER_TELEPHONE)')
	L(f' Time: {elapsed:.1f}s')
	L(f' Naturalness score: {st.naturalness_score:.1f}/100')
	L(f' BWE mode: {st.telephone_bwe_mode or "none"}')
	L(f' AudioSR Stage B: {"YES" if st.telephone_audiosr_applied else "NO"}')
	L(f' ★ Red Line 18: output is BWE-processed / synthetic HF above {st.telephone_cutoff_hz:.0f}Hz')
	L(f'{"═"*60}')

	result = {
	'engine': 'الإحياء',
	'version': __version__,
	'elapsed_s': round(elapsed, 1),
	'naturalness_score': round(st.naturalness_score, 1),
	'aggressive': aggressive,
	'artifacts': {
	'f0_flatness': artifacts.f0_flatness,
	'f0_flat_severity': artifacts.f0_flat_severity,
	'spectral_holes': artifacts.spectral_holes,
	'metallic_score': artifacts.metallic_score,
	'nr_damage': artifacts.nr_damage_score,
	'formant_collapse': artifacts.formant_collapse,
	'sibilant_quality': artifacts.sibilant_quality,
	'overall': artifacts.overall_artificial,
	'diagnosis': artifacts.diagnosis,
	'snr_db': artifacts.snr_db,
	'is_noisy': artifacts.is_noisy,
	'active_bandwidth_hz': artifacts.active_bandwidth_hz,
	'wind_detected': artifacts.wind_detected,
	},
	'improvement': {
	'f0_flatness_before': st.f0_flatness_before,
	'f0_flatness_after': st.f0_flatness_after,
	'spectral_holes_before': st.spectral_holes_before,
	'spectral_holes_after': st.spectral_holes_after,
	'metallic_before': st.metallic_before,
	'metallic_after': st.metallic_after,
	},
	'phases': {
	'dereverb': False,
	'nr_repair': False,
	'f0_revival': False,
	'jitter': False,
	'shimmer': False,
	'formant': False,
	'harmonics': False,
	'dynamics': st.p6_micro_dynamics,
	'spectral': False,
	'sibilant': False,
	'temporal': st.p9_temporal_shaping,
	},
	'guards': {
	'pass': st.guard_pass,
	'warn': st.guard_warn,
	'reverts': st.guard_reverts,
	},
	'final': final_report,
	'mujawwad_conf': st.mujawwad_conf,
	'f0_median': st.f0_median,
	'telephone_tier': {
	'detected': True,
	'cutoff_hz': st.telephone_cutoff_hz,
	'bwe_applied': st.telephone_bwe_applied,
	'bwe_mode': st.telephone_bwe_mode,
	'audiosr_stage_b': st.telephone_audiosr_applied,
	'red_line_18': 'BWE-processed / synthetic HF',
	'standard_passes_bypassed': [
	'dereverb', 'nr_repair', 'f0_revival',
	'formant', 'harmonics', 'spectral', 'sibilant',
	],
	},
	}
	return result
	# ── Phase 1: Dereverberation ──────────────────────────────────────────
	if not skip_dereverb:
	current_wav = phase1_dereverb(current_wav, samples, st)
	else:
	L(f'\n── phase_1_dereverb ── SKIPPED')

	# v2 FIX: Update working samples after each phase
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 2: Noise Repair ─────────────────────────────────────────────
	current_wav = phase2_noise_repair(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 3: F0 Contour Revival ───────────────────────────────────────
	if not skip_f0_revival and artifacts.f0_flat_severity != 'none':
	current_wav = phase3_f0_revival(current_wav, cur_samples, artifacts, st)
	elif skip_f0_revival:
	L(f'\n── phase_3_f0_revival ── SKIPPED')
	else:
	L(f'\n── phase_3_f0_revival ── F0 natural, skipping')

	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 4: Formant Reconstruction ───────────────────────────────────
	current_wav = phase4_formant_rebuild(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 5: Harmonic Richness ────────────────────────────────────────
	current_wav = phase5_harmonic_richness(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 6: Micro-Dynamics ───────────────────────────────────────────
	current_wav = phase6_micro_dynamics(current_wav, cur_samples, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 7: Spectral Repair ──────────────────────────────────────────
	current_wav = phase7_spectral_repair(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 8: Sibilant Naturalization ──────────────────────────────────
	current_wav = phase8_sibilant_naturalization(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── Phase 9: Temporal Shaping ─────────────────────────────────────────
	current_wav = phase9_temporal_shaping(current_wav, cur_samples, artifacts, st)
	cur_samples, _ = _decode_samples(current_wav)
	if cur_samples is None:
	cur_samples = samples

	# ── v2: Final re-measurement for "after" tracking ─────────────────────
	# Re-measure metrics that may have been affected by subsequent phases
	if cur_samples is not None and len(cur_samples) > SR:
	# Update spectral holes after all processing
	if st.spectral_holes_after == st.spectral_holes_before:
	# Phase 7 may not have run or may not have updated
	st.spectral_holes_after, _ = _detect_spectral_holes(cur_samples)
	# Update metallic score after all processing
	st.metallic_after = _detect_metallic_ringing(cur_samples)
	# Update F0 flatness if not already set
	if st.f0_flatness_after == st.f0_flatness_before:
	f0_post, _ = _detect_f0(cur_samples)
	if len(f0_post) > 10:
	st.f0_flatness_after = _compute_f0_flatness(f0_post)

	# ── Phase 10: Tajweed Guards ──────────────────────────────────────────
	current_wav = phase10_guards(original_samples, current_wav, st)

	# ── Phase 11: Final ───────────────────────────────────────────────────
	final_wav, final_report = phase11_final(current_wav, st)

	# ── v2: Compute naturalness score ─────────────────────────────────────
	final_samples, _ = _decode_samples(final_wav)
	st.naturalness_score = _compute_naturalness_score(st, artifacts, final_samples)

	elapsed = time.time() - t0

	# ── Summary ───────────────────────────────────────────────────────────
	L(f'\n{"═"*60}')
	L(f' الإحياء {__version__} — COMPLETE')
	L(f' Time: {elapsed:.1f}s')
	L(f' Naturalness score: {st.naturalness_score:.1f}/100')
	L(f' Phases applied:')
	for pname, applied in [
	('P0-Analysis', st.p0_analyzed),
	('P1-Dereverb', st.p1_dereverb_applied),
	('P2-NR Repair', st.p2_nr_repair_applied),
	('P3-F0 Revival', st.p3_f0_revival),
	('P4-Formant', st.p4_formant_rebuilt),
	('P5-Harmonics', st.p5_harmonic_rich),
	('P6-Dynamics', st.p6_micro_dynamics),
	('P7-Spectral', st.p7_spectral_repair),
	('P8-Sibilant', st.p8_sibilant_nat),
	('P9-Temporal', st.p9_temporal_shaping),
	('P10-Guards', st.p10_guards_ok),
	('P11-Final', st.p11_final_done),
	]:
	L(f' {pname}: {"✓" if applied else "—"}')
	L(f' Artifacts: flatness {st.f0_flatness_before:.3f}→{st.f0_flatness_after:.3f} '
	f'holes {st.spectral_holes_before}→{st.spectral_holes_after} '
	f'metallic {st.metallic_before:.3f}→{st.metallic_after:.3f}')
	L(f' Guards: {len(st.guard_pass)} pass / {len(st.guard_warn)} warn / {st.guard_reverts} reverts')
	if final_report:
	L(f' Final: LUFS={final_report.get("lufs",0):.2f} '
	f'LRA={final_report.get("lra",0):.2f} '
	f'Crest={final_report.get("crest",0):.1f}dB')
	L(f'{"═"*60}')

	return {
	'engine': 'الإحياء',
	'version': __version__,
	'elapsed_s': round(elapsed, 1),
	'naturalness_score': round(st.naturalness_score, 1),
	'aggressive': aggressive,
	'artifacts': {
	'f0_flatness': artifacts.f0_flatness,
	'f0_flat_severity': artifacts.f0_flat_severity,
	'spectral_holes': artifacts.spectral_holes,
	'metallic_score': artifacts.metallic_score,
	'nr_damage': artifacts.nr_damage_score,
	'formant_collapse': artifacts.formant_collapse,
	'sibilant_quality': artifacts.sibilant_quality,
	'overall': artifacts.overall_artificial,
	'diagnosis': artifacts.diagnosis,
	'snr_db': artifacts.snr_db,
	'is_noisy': artifacts.is_noisy,
	'active_bandwidth_hz': artifacts.active_bandwidth_hz,
	'wind_detected': artifacts.wind_detected,
	},
	'improvement': {
	'f0_flatness_before': st.f0_flatness_before,
	'f0_flatness_after': st.f0_flatness_after,
	'spectral_holes_before': st.spectral_holes_before,
	'spectral_holes_after': st.spectral_holes_after,
	'metallic_before': st.metallic_before,
	'metallic_after': st.metallic_after,
	},
	'phases': {
	'dereverb': st.p1_dereverb_applied,
	'nr_repair': st.p2_nr_repair_applied,
	'f0_revival': st.p3_f0_revival,
	'jitter': st.p3_jitter_injected,
	'shimmer': st.p3_shimmer_injected,
	'formant': st.p4_formant_rebuilt,
	'harmonics': st.p5_harmonic_rich,
	'dynamics': st.p6_micro_dynamics,
	'spectral': st.p7_spectral_repair,
	'sibilant': st.p8_sibilant_nat,
	'temporal': st.p9_temporal_shaping,
	},
	'guards': {
	'pass': st.guard_pass,
	'warn': st.guard_warn,
	'reverts': st.guard_reverts,
	},
	'final': final_report,
	'mujawwad_conf': st.mujawwad_conf,
	'f0_median': st.f0_median,
	'telephone_tier': {
	'detected': False,
	'cutoff_hz': 0.0,
	'bwe_applied': False,
	},
	}

	finally:
	_cleanup_all(st)


	# ══════════════════════════════════════════════════════════════════════════════
	# CLI
	# ══════════════════════════════════════════════════════════════════════════════

	def main() -> int:
	if not NUMPY_OK:
	print('pip install numpy scipy')
	return 1

	p = argparse.ArgumentParser(
	description=f'الإحياء {__version__} — Voice Revival Engine — Aetherion Engine-3'
	)
	p.add_argument('-i', '--input', required=False, help='Input audio file')
	p.add_argument('-o', '--output', required=False, help='Output WAV file')
	p.add_argument('--mujawwad', type=float, default=-1.0,
	help='Override Mujawwad confidence (0.0=Murattal, 1.0=Mujawwad)')
	p.add_argument('--skip-dereverb', action='store_true',
	help='Skip dereverberation phase')
	p.add_argument('--skip-f0', action='store_true',
	help='Skip F0 contour revival (jitter/shimmer/drift)')
	p.add_argument('--aggressive', action='store_true',
	help='Aggressive mode: wider guards, stronger processing')
	p.add_argument('--diagnose-only', action='store_true',
	help='Only run Phase 0 analysis, no processing')
	args = p.parse_args()

	if not args.input:
	p.print_help()
	return 1

	if not os.path.exists(args.input):
	print(f'Input not found: {args.input}')
	return 1

	if args.diagnose_only:
	# Only analyze
	work_wav = os.path.join(_TMP, f'ihya_diag_{os.getpid()}.wav')
	if not _decode_to_wav(args.input, work_wav):
	print('Failed to decode input')
	return 1
	samples, sr = _decode_samples(work_wav)
	_cleanup(work_wav)
	if samples is None:
	print('Failed to decode samples')
	return 1
	st = IhyaState()
	artifacts = phase0_analyze(samples, sr, st)
	print('\n' + json.dumps({
	'f0_flatness': float(artifacts.f0_flatness),
	'f0_flat_severity': artifacts.f0_flat_severity,
	'spectral_holes': int(artifacts.spectral_holes),
	'metallic_score': float(artifacts.metallic_score),
	'metallic_severity': artifacts.metallic_severity,
	'nr_damage': float(artifacts.nr_damage_score),
	'nr_damage_severity': artifacts.nr_damage_severity,
	'formant_collapse': float(artifacts.formant_collapse),
	'sibilant_quality': float(artifacts.sibilant_quality),
	'overall_artificial': float(artifacts.overall_artificial),
	'diagnosis': artifacts.diagnosis,
	'mujawwad_conf': float(artifacts.mujawwad_conf),
	'f0_median': float(st.f0_median),
	'snr_db': float(artifacts.snr_db),
	'is_noisy': bool(artifacts.is_noisy),
	'active_bandwidth_hz': float(artifacts.active_bandwidth_hz),
	'wind_detected': bool(artifacts.wind_detected),
	'telephone_tier': {
	'detected': bool(artifacts.is_telephone_tier),
	'cutoff_hz': float(artifacts.telephone_cutoff_hz),
	'note': (
	'BWE required — VoiceFixer Mode 0 pipeline (§173)'
	if artifacts.is_telephone_tier else 'N/A'
	),
	},
	}, indent=2, ensure_ascii=False))
	return 0

	if not args.output:
	base = Path(args.input).stem
	args.output = str(Path(args.input).parent / f'{base}_ihya.wav')

	try:
	result = process(
	args.input, args.output,
	mujawwad_override=args.mujawwad,
	skip_dereverb=args.skip_dereverb,
	skip_f0_revival=args.skip_f0,
	aggressive=args.aggressive,
	)
	if 'error' in result:
	print(f'\n ERROR: {result["error"]}')
	return 2

	art = result.get('artifacts', {})
	imp = result.get('improvement', {})
	tel = result.get('telephone_tier', {})
	print(f'\n ══ Diagnosis: {art.get("diagnosis", "N/A")}')
	print(f' ══ Overall artificial: {art.get("overall", 0):.3f}')
	print(f' ══ Naturalness score: {result.get("naturalness_score", 0):.1f}/100')
	print(f' ══ F0 flatness: {imp.get("f0_flatness_before", 0):.3f} → {imp.get("f0_flatness_after", 0):.3f}')
	print(f' ══ Spectral holes: {imp.get("spectral_holes_before", 0)} → {imp.get("spectral_holes_after", 0)}')
	print(f' ══ Metallic: {imp.get("metallic_before", 0):.3f} → {imp.get("metallic_after", 0):.3f}')
	print(f' ══ SNR: {art.get("snr_db", 0):.1f}dB Bandwidth: {art.get("active_bandwidth_hz", 0):.0f}Hz')
	if art.get('wind_detected'):
	print(f' ══ Wind noise detected')
	if tel.get('detected'):
	print(f' ══ ★ TIER_TELEPHONE: cutoff={tel.get("cutoff_hz", 0):.0f}Hz '
	f'BWE={"✓" if tel.get("bwe_applied") else "✗ (VoiceFixer missing)"} '
	f'AudioSR={"✓" if tel.get("audiosr_stage_b") else "✗"}')
	print(f' ══ ★ Red Line 18: {tel.get("red_line_18", "")}')
	if result.get('aggressive'):
	print(f' ══ Mode: AGGRESSIVE')
	print(f' ══ Output: {args.output}')
	return 0

	except Exception as e:
	import traceback
	print(f'ERROR: {e}')
	traceback.print_exc()
	return 1


	if __name__ == '__main__':
	sys.exit(main())