"""Deterministic audio operations. HPSS is DSP, not an AI instrument separator.""" from __future__ import annotations import hashlib import math import shutil import tempfile from contextlib import ExitStack from dataclasses import dataclass from pathlib import Path from typing import Callable import numpy as np import soundfile as sf from scipy.ndimage import median_filter from scipy.signal import istft, stft, resample_poly MAX_CHANNELS = 2 MAX_SAMPLERATE = 192000 class AudioError(ValueError): pass @dataclass class AudioBuffer: samples: np.ndarray # [frames, channels], float64 samplerate: int def sha256_file(path: Path) -> str: digest = hashlib.sha256() with path.open("rb") as file: for chunk in iter(lambda: file.read(1024 * 1024), b""): digest.update(chunk) return digest.hexdigest() def audio_info(path: Path) -> sf._SoundFileInfo: """Validate metadata before decoding; no fixed audio-duration ceiling.""" try: info = sf.info(str(path)) except (RuntimeError, OSError) as err: raise AudioError("File cannot be decoded as audio.") from err if not 8000 <= info.samplerate <= MAX_SAMPLERATE: raise AudioError("Unsupported sample rate (allowed: 8000–192000 Hz).") if info.channels not in (1, 2): raise AudioError("Only mono/stereo audio is supported.") if info.frames < 64: raise AudioError("Audio is too short (minimum 64 frames).") return info def load_audio(path: Path) -> AudioBuffer: """In-memory decoder for short tests and optional neural adapters. The production HPSS pathway uses streaming reads and does not call this function on full-length tracks. """ audio_info(path) try: samples, sr = sf.read(str(path), dtype="float64", always_2d=True) except (RuntimeError, OSError) as err: raise AudioError("File cannot be decoded as audio.") from err if not np.isfinite(samples).all(): raise AudioError("Audio contains invalid (non-finite) samples.") return AudioBuffer(samples=np.asarray(samples, dtype=np.float64), samplerate=sr) def analyze_file(path: Path, preview_path: Path | None = None, block_frames: int = 131072) -> dict: """Memory-bounded diagnostics and listening preview for arbitrarily long tracks. File size and available disk space still bound practical processing. """ info = audio_info(path) total = info.frames envelope_bins = min(420, total) bin_width = math.ceil(total / envelope_bins) envelope = np.zeros(envelope_bins, dtype=np.float64) sum_squares = 0.0 peak = 0.0 clipped = 0 first_seconds = [] first_frames = 0 with ExitStack() as stack: source = stack.enter_context(sf.SoundFile(str(path), "r")) target = (stack.enter_context( sf.SoundFile(str(preview_path), "w", samplerate=info.samplerate, channels=info.channels, format="WAV", subtype="PCM_16") ) if preview_path is not None else None) position = 0 while position < total: block = source.read(min(block_frames, total - position), dtype="float64", always_2d=True) if len(block) == 0: raise AudioError("Unexpected end of audio file.") if not np.isfinite(block).all(): raise AudioError("Audio contains invalid (non-finite) samples.") abs_frames = np.max(np.abs(block), axis=1) peak = max(peak, float(abs_frames.max())) sum_squares += float(np.sum(np.square(block), dtype=np.float64)) clipped += int(np.count_nonzero(np.any(np.abs(block) >= 0.999969, axis=1))) if first_frames < info.samplerate * 15: span = min(len(block), info.samplerate * 15 - first_frames) first_seconds.append(block[:span].mean(axis=1)) first_frames += span local = 0 while local < len(block): index = min(envelope_bins - 1, (position + local) // bin_width) end = min(len(block), (index + 1) * bin_width - position) envelope[index] = max(envelope[index], float(abs_frames[local:end].max())) local = end if target is not None: target.write(np.clip(block, -1, 1)) position += len(block) mono = np.concatenate(first_seconds) window = np.hanning(len(mono)) magnitude = np.abs(np.fft.rfft(mono * window)) freqs = np.fft.rfftfreq(len(mono), 1 / info.samplerate) centroid = float(np.sum(magnitude * freqs) / max(float(magnitude.sum()), 1e-12)) rms = math.sqrt(sum_squares / (total * info.channels)) return { "duration_seconds": round(total / info.samplerate, 4), "sample_rate": info.samplerate, "channels": info.channels, "frames": total, "peak_dbfs": round(20 * math.log10(max(peak, 1e-12)), 2), "rms_dbfs": round(20 * math.log10(max(rms, 1e-12)), 2), "clipped_frames": clipped, "spectral_centroid_hz": round(centroid, 1), "waveform": np.round(envelope, 5).tolist(), "disclaimer": "Spectral centroid is estimated from the first 15 s; no semantic recognition is claimed.", } def peak_envelope(samples: np.ndarray, bins: int = 420) -> list[float]: mono = np.max(np.abs(samples), axis=1) if len(mono) == 0: return [] block = max(1, math.ceil(len(mono) / bins)) pad = (-len(mono)) % block if pad: mono = np.pad(mono, (0, pad)) peaks = mono.reshape(-1, block).max(axis=1) if len(peaks) > bins: peaks = peaks[:bins] return np.round(peaks, 5).tolist() def analyze(audio: AudioBuffer) -> dict: x = audio.samples peak = float(np.max(np.abs(x))) rms = float(np.sqrt(np.mean(x * x))) clipped = int(np.sum(np.any(np.abs(x) >= 0.999969, axis=1))) mono = x[:min(len(x), audio.samplerate * 15)].mean(axis=1) window = np.hanning(len(mono)) magnitude = np.abs(np.fft.rfft(mono * window)) freqs = np.fft.rfftfreq(len(mono), 1 / audio.samplerate) centroid = float(np.sum(magnitude * freqs) / max(float(magnitude.sum()), 1e-12)) return { "duration_seconds": round(len(x) / audio.samplerate, 4), "sample_rate": audio.samplerate, "channels": x.shape[1], "frames": len(x), "peak_dbfs": round(20 * math.log10(max(peak, 1e-12)), 2), "rms_dbfs": round(20 * math.log10(max(rms, 1e-12)), 2), "clipped_frames": clipped, "spectral_centroid_hz": round(centroid, 1), "waveform": peak_envelope(x), "disclaimer": "Spectral centroid is estimated from the first 15 s; no semantic recognition is claimed.", } def hpss_separate( audio: AudioBuffer, progress: Callable[[float], None] | None = None, ) -> dict[str, np.ndarray]: """Median-filter harmonic/percussive separation with soft masks. Returns float64 stems aligned with input. Last stem is EXACT remainder in float64 arithmetic. Semantic instrument labels are not inferred. """ x, sr = audio.samples, audio.samplerate nfft = 2048 if len(x) >= 2048 else 256 nfft = min(nfft, len(x)) overlap = nfft * 3 // 4 harmonic = np.zeros_like(x) percussive = np.zeros_like(x) for channel in range(x.shape[1]): _, _, z = stft( x[:, channel], fs=sr, window="hann", nperseg=nfft, noverlap=overlap, boundary="zeros", padded=True, ) power = np.abs(z) harm = median_filter(power, size=(1, 17), mode="reflect") perc = median_filter(power, size=(17, 1), mode="reflect") h2, p2 = harm ** 2, perc ** 2 denominator = h2 + p2 harmonic_mask = np.divide( h2, denominator, out=np.full_like(denominator, 0.5), where=denominator > 1e-20, ) percussive_mask = 1.0 - harmonic_mask _, h = istft(z * harmonic_mask, fs=sr, window="hann", nperseg=nfft, noverlap=overlap, boundary=True) _, p = istft(z * percussive_mask, fs=sr, window="hann", nperseg=nfft, noverlap=overlap, boundary=True) harmonic[:, channel] = h[:len(x)] percussive[:, channel] = p[:len(x)] if progress: progress((channel + 1) / x.shape[1]) residual = x - harmonic - percussive return {"harmonic": harmonic, "percussive": percussive, "residual": residual} def hpss_separate_file( input_path: Path, stems_dir: Path, progress: Callable[[float], None] | None = None, chunk_frames: int = 262144, margin_frames: int = 16384, ) -> tuple[dict, dict]: """Separate using bounded STFT chunks with context and sample-aligned residual. For each chunk, surrounding context is used for median filtering. Only the inner samples are emitted so each original sample is written exactly once. Edge artifacts remain possible; this is a streaming DSP estimator. """ if chunk_frames < 4096 or margin_frames < 2048: raise AudioError("Chunk and margin sizes are too small.") info = audio_info(input_path) total = info.frames labels = ("harmonic", "percussive", "residual") stem_peaks = {name: 0.0 for name in labels} temp = Path(tempfile.mkdtemp(prefix=".omega-stems-", dir=str(stems_dir.parent))) max_error = 0.0 error_energy = 0.0 input_energy = 0.0 try: with ExitStack() as stack: source = stack.enter_context(sf.SoundFile(str(input_path), "r")) masters = {} previews = {} for name in labels: masters[name] = stack.enter_context( sf.SoundFile(str(temp / f"{name}.wav"), "w", samplerate=info.samplerate, channels=info.channels, format="WAV", subtype="FLOAT") ) previews[name] = stack.enter_context( sf.SoundFile(str(temp / f"{name}_preview.wav"), "w", samplerate=info.samplerate, channels=info.channels, format="WAV", subtype="PCM_16") ) for begin in range(0, total, chunk_frames): end = min(total, begin + chunk_frames) left = max(0, begin - margin_frames) right = min(total, end + margin_frames) source.seek(left) segment = source.read(right - left, dtype="float64", always_2d=True) if len(segment) != right-left or not np.isfinite(segment).all(): raise AudioError("Invalid or truncated audio block.") separated = hpss_separate(AudioBuffer(segment, info.samplerate)) left_crop = begin - left right_crop = end - left core = segment[left_crop:right_crop] harmonic = separated["harmonic"][left_crop:right_crop] percussive = separated["percussive"][left_crop:right_crop] residual = core - harmonic - percussive emitted = {"harmonic": harmonic, "percussive": percussive, "residual": residual} check = core - (harmonic + percussive + residual) max_error = max(max_error, float(np.max(np.abs(check)))) error_energy += float(np.sum(check ** 2)) input_energy += float(np.sum(core ** 2)) for name, values in emitted.items(): masters[name].write(values) previews[name].write(np.clip(values, -1, 1)) stem_peaks[name] = max(stem_peaks[name], float(np.max(np.abs(values)))) if progress is not None: progress(end / total) stem_info = {} for name in labels: master = temp / f"{name}.wav" stem_info[name] = { "name": name, "master": master.name, "preview": f"{name}_preview.wav", "master_sha256": sha256_file(master), "peak_dbfs": round(20 * math.log10(max(stem_peaks[name], 1e-12)), 2), "duration_seconds": round(total / info.samplerate, 4), } # Folder handover happens only after all streams are complete. backup = stems_dir.with_name(stems_dir.name + ".backup") if backup.exists(): shutil.rmtree(backup) if stems_dir.exists(): stems_dir.rename(backup) try: temp.rename(stems_dir) except Exception: if backup.exists(): backup.rename(stems_dir) raise if backup.exists(): shutil.rmtree(backup) rms_error = math.sqrt(error_energy / (total * info.channels)) rms_input = math.sqrt(input_energy / (total * info.channels)) report = { "max_abs_reconstruction_error": max_error, "rms_reconstruction_error": rms_error, "relative_reconstruction_error_db": round( 20 * math.log10(max(rms_error, 1e-18) / max(rms_input, 1e-18)), 2), "tolerance": 1e-8, "consistent": max_error < 1e-8, "note": "Mixture consistency does not imply correct source attribution.", } return stem_info, report finally: if temp.exists(): shutil.rmtree(temp) def align_and_resample(samples: np.ndarray, from_sr: int, to_sr: int, target_frames: int) -> np.ndarray: """Resample a [frames,channels] output and restore exact input frame count.""" if from_sr != to_sr: divisor = math.gcd(from_sr, to_sr) samples = resample_poly(samples, to_sr // divisor, from_sr // divisor, axis=0) if len(samples) < target_frames: samples = np.pad(samples, ((0, target_frames - len(samples)), (0, 0))) return np.asarray(samples[:target_frames], dtype=np.float64) def mixture_report(original: np.ndarray, stems: dict[str, np.ndarray]) -> dict: reconstructed = np.zeros_like(original) for value in stems.values(): if value.shape != original.shape: raise AudioError("Stem dimensions differ from the input.") if not np.isfinite(value).all(): raise AudioError("A stem has non-finite samples.") reconstructed += value error = original - reconstructed error_rms = float(np.sqrt(np.mean(error ** 2))) input_rms = float(np.sqrt(np.mean(original ** 2))) return { "max_abs_reconstruction_error": float(np.max(np.abs(error))), "rms_reconstruction_error": error_rms, "relative_reconstruction_error_db": round( 20 * math.log10(max(error_rms, 1e-18) / max(input_rms, 1e-18)), 2 ), "tolerance": 1e-8, "consistent": bool(np.max(np.abs(error)) < 1e-8), "note": "Mixture consistency does not imply correct source attribution.", } def save_stems(folder: Path, original: AudioBuffer, stems: dict[str, np.ndarray]) -> dict: folder.mkdir(parents=True, exist_ok=True) info = {} for name, values in stems.items(): if not name.isascii() or not name.replace("_", "").isalnum(): raise AudioError("Unsafe stem name.") master = folder / f"{name}.wav" preview = folder / f"{name}_preview.wav" sf.write(str(master), values, original.samplerate, subtype="FLOAT") # 16 bit playback file is a separate, deliberately lower-precision preview. sf.write(str(preview), np.clip(values, -1, 1), original.samplerate, subtype="PCM_16") info[name] = { "name": name, "master": f"{name}.wav", "preview": f"{name}_preview.wav", "master_sha256": sha256_file(master), "peak_dbfs": round(20 * math.log10(max(float(np.max(np.abs(values))), 1e-12)), 2), "duration_seconds": round(len(values) / original.samplerate, 4), } return info