"""Space-Mastering-Engine nach ONUS-Doktrin (v2 — Preserve, don't strip). Implementiert die ONUS-Prinzipien direkt im HF-Space: - soft_keep_air als Default: clean = harmonic + percussive + residual * 10^(keep_air_db/20) - strict (zero residual) nur opt-in mit menschlicher Bestätigung - Master-Profile mit LUFS-Ziel + True-Peak-Ziel - QA-Metriken: residual_energy_ratio, air_preserved_db, before/after LUFS - Originale werden nie überschrieben; Ausgaben landen nur im Session-Ordner - Offline: keine Cloud-Uploads """ from __future__ import annotations import math import wave from pathlib import Path from typing import Any import numpy as np MASTER_PROFILES: dict[str, dict[str, float]] = { "streaming_safe": {"lufs": -14.0, "tp": -1.0}, "streaming_loud": {"lufs": -9.0, "tp": -1.0}, "club": {"lufs": -8.0, "tp": -1.0}, "dynamic_hifi": {"lufs": -16.0, "tp": -1.5}, "premium_clarity": {"lufs": -13.0, "tp": -1.0}, "audiophile_preserve": {"lufs": -18.0, "tp": -2.0}, } _N_FFT = 2048 _HOP = 512 def read_wav(path: Path) -> tuple[np.ndarray, int]: """Liest PCM-WAV (16/24/32-bit) -> float32 in [-1, 1], Shape (samples, channels).""" with wave.open(str(path), "rb") as wav_file: channels = wav_file.getnchannels() sample_rate = wav_file.getframerate() sample_width = wav_file.getsampwidth() frames = wav_file.readframes(wav_file.getnframes()) if sample_width == 2: data = np.frombuffer(frames, dtype=np.int16).astype(np.float32) / 32768.0 elif sample_width == 4: data = np.frombuffer(frames, dtype=np.int32).astype(np.float32) / 2147483648.0 else: raise ValueError(f"Unerwartete Sample-Breite: {sample_width} Byte") if channels > 1: data = data.reshape(-1, channels) return data, sample_rate def write_wav(path: Path, data: np.ndarray, sample_rate: int) -> Path: """Schreibt float32 -> 16-bit PCM Stereo-WAV (browserfähig).""" if data.ndim == 1: data = np.stack([data, data], axis=1) pcm = (np.clip(data, -1.0, 1.0) * 32767.0).astype(np.int16) with wave.open(str(path), "wb") as wav_file: wav_file.setnchannels(2) wav_file.setsampwidth(2) wav_file.setframerate(sample_rate) wav_file.writeframes(pcm.tobytes()) return path def _mono(data: np.ndarray) -> np.ndarray: return data.mean(axis=1) if data.ndim == 2 else data def estimate_lufs(data: np.ndarray, sample_rate: int) -> float: """Vereinfachte ITU-R BS.1770-Approximation (RMS-Frames + absolutes Gate).""" mono = _mono(data) frame = max(1, int(0.4 * sample_rate)) n_frames = max(1, len(mono) // frame) powers = np.asarray( [float(np.mean(mono[i * frame : (i + 1) * frame] ** 2)) for i in range(n_frames)], dtype=np.float64, ) absolute_peak = float(np.max(np.abs(mono))) gate = (absolute_peak * 10 ** (-70 / 20)) ** 2 if absolute_peak > 0 else 0.0 gated = powers[powers > gate] if gate > 0 else powers if gated.size == 0 or float(np.mean(gated)) <= 0: return -96.0 return float(10 * math.log10(float(np.mean(gated)))) def _stft(data: np.ndarray) -> np.ndarray: mono = _mono(data) window = np.hanning(_N_FFT).astype(np.float32) padded = np.pad(mono, (_N_FFT // 2, _N_FFT // 2), mode="reflect") n_frames = max(1, 1 + (len(padded) - _N_FFT) // _HOP) frames = np.stack( [padded[i * _HOP : i * _HOP + _N_FFT] * window for i in range(n_frames)] ) return np.fft.rfft(frames, axis=1).T # (n_bins, n_frames) def _istft(stft: np.ndarray, length: int) -> np.ndarray: window = np.hanning(_N_FFT).astype(np.float32) frames = np.fft.irfft(stft.T, n=_N_FFT, axis=1) n_frames = frames.shape[0] out = np.zeros(length + _N_FFT, dtype=np.float32) norm = np.zeros(length + _N_FFT, dtype=np.float32) for i in range(n_frames): start = i * _HOP out[start : start + _N_FFT] += frames[i] * window norm[start : start + _N_FFT] += window**2 norm = np.where(norm > 1e-8, norm, 1.0) return out[_N_FFT // 2 : _N_FFT // 2 + length] / norm[_N_FFT // 2 : _N_FFT // 2 + length] def _hpss_soft(stft: np.ndarray, margin: float = 2.0) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """Weiche HPSS-Masken (numpy-only): harmonic = Median über Frequenz, percussive = Median über Zeit, residual = X - H - P.""" magnitude = np.abs(stft) eps = 1e-8 h_floor = np.median(magnitude, axis=0, keepdims=True) + eps p_floor = np.median(magnitude, axis=1, keepdims=True) + eps h_ratio = magnitude / h_floor p_ratio = magnitude / p_floor h_mask = np.clip((h_ratio - 1.0) / max(margin - 1.0, 0.5), 0.0, 1.0) p_mask = np.clip((p_ratio - 1.0) / max(margin - 1.0, 0.5), 0.0, 1.0) total = h_mask + p_mask + eps h_mask = h_mask / total p_mask = p_mask / total harmonic = stft * h_mask percussive = stft * p_mask residual = stft - harmonic - percussive return harmonic, percussive, residual def apply_purity( data: np.ndarray, sample_rate: int, *, keep_air_db: float = -20.0, margin: float = 2.0, strict: bool = False, ) -> tuple[np.ndarray, np.ndarray, dict[str, Any]]: """Purity nach ONUS-Doktrin. soft_keep_air (Default): residual wird auf keep_air_db gedämpft (Air/Hall/Wärme bleiben). strict (opt-in): residual wird eliminiert (nur bei nachgewiesenen schweren Artefakten). """ if strict: keep_air_db = -96.0 # residual praktisch eliminiert harmonic, percussive, residual = _hpss_soft(_stft(data), margin=margin) residual_gain = 10 ** (keep_air_db / 20) clean_stft = harmonic + percussive + residual * residual_gain clean = _istft(clean_stft, len(_mono(data))) residual_audio = _istft(residual, len(_mono(data))) if data.ndim == 2: clean = np.stack([clean, clean], axis=1) residual_audio = np.stack([residual_audio, residual_audio], axis=1) total_energy = float(np.sum(np.abs(_stft(data)) ** 2)) or 1.0 residual_energy = float(np.sum(np.abs(residual) ** 2)) metrics = { "method": "strict" if strict else f"soft_keep_air_{keep_air_db:.0f}dB", "margin": margin, "keep_air_db": keep_air_db, "residual_energy_ratio": round(residual_energy / total_energy, 4), "air_preserved_db": round(keep_air_db, 1), "sample_rate": sample_rate, } return clean, residual_audio, metrics def apply_master( data: np.ndarray, sample_rate: int, profile: str ) -> tuple[np.ndarray, dict[str, Any]]: """Loudness-Normalisierung auf Profil-LUFS + True-Peak-Limit (Brickwall).""" spec = MASTER_PROFILES.get(profile) if spec is None: raise ValueError(f"Unbekanntes Master-Profil: {profile}") target_lufs = spec["lufs"] target_tp = spec["tp"] before_lufs = estimate_lufs(data, sample_rate) gain_db = max(-12.0, min(12.0, target_lufs - before_lufs)) gained = data * 10 ** (gain_db / 20) ceiling = 10 ** (target_tp / 20) peak = float(np.max(np.abs(gained))) if peak > ceiling: gained = gained * (ceiling / peak) after_lufs = estimate_lufs(gained, sample_rate) after_peak = float(np.max(np.abs(gained))) after_tp = 20 * math.log10(max(after_peak, 1e-12)) delta = abs(after_lufs - target_lufs) verdict = ( "PASS · Ziel-LUFS erreicht" if delta <= 0.5 else "OK · nahe am Ziel" if delta <= 1.5 else "CHECK · Abweichung vom Ziel" ) return gained, { "profile": profile, "target_lufs": target_lufs, "target_tp_dbtp": target_tp, "gain_db": round(gain_db, 2), "before": {"integrated_lufs": round(before_lufs, 2)}, "after": { "integrated_lufs": round(after_lufs, 2), "true_peak_dbtp": round(after_tp, 2), }, "perceptual_verdict": verdict, } def build_report_markdown( *, source_path: Path, profile: str, purity_mode: str, analysis: dict[str, Any], purity: dict[str, Any] | None, master: dict[str, Any] | None, output_paths: list[Path], ) -> str: """ONUS-konformer Report (Minimum laut Skill-Doktrin).""" lines = [ "# ONUS-konformer Mastering-Report", "", f"- Quelle (unverändert): `{source_path.name}`", f"- Profil: `{profile}`", f"- Purity: `{purity_mode}`", ] if purity: lines += [ f"- Residual-Ratio: `{purity.get('residual_energy_ratio', 'n/a')}`", f"- Air erhalten: `{purity.get('air_preserved_db', 'n/a')} dB`", ] if master: before = master.get("before", {}) after = master.get("after", {}) lines += [ f"- LUFS vorher: `{before.get('integrated_lufs', 'n/a')}`", f"- LUFS nachher: `{after.get('integrated_lufs', 'n/a')}`", f"- True Peak: `{after.get('true_peak_dbtp', 'n/a')} dBTP`", f"- QA: `{master.get('perceptual_verdict', 'n/a')}`", ] lines += ["", "## Ausgaben", ""] lines += [f"- `{path.name}`" for path in output_paths] lines += ["", "human_approval: pending", ""] return "\n".join(lines)