2b-studio / studio /mastering.py
2Btainment's picture
2B Studio v2: Toxic-Studio-Redesign, Raum-Leiste, Vorlagen-Bibliothek (30), Verlauf mit Wellenformen, Modell-Status-Chips; Fix MiniMax _studio_state, Paused-Status
d360571 verified
Raw History Blame Contribute Delete
9.21 kB
"""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)