absolution-omega / app /audio.py
2Btainment's picture
Initial HF Docker Space deploy
29c3be9 verified
Raw History Blame Contribute Delete
16.1 kB
"""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