spectralaudit 0.1.0__py3-none-any.whl

spectralaudit/__init__.py

@@ -0,0 +1,44 @@
+"""SpectralAudit: reproducible, offline spectral diagnostics for music and audio."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .audio import load_audio
+from .comb import detect_comb
+from .confounders import inspect_confounders
+from .mastering import audit_pipeline, compare_masters
+from .models import AuditReport
+from .spectrum import analyze_frequencies
+from .temporal import analyze_temporal
+
+__version__ = "0.1.0"
+__all__ = ["analyze", "analyze_frequencies", "detect_comb", "analyze_temporal",
+           "load_audio", "compare_masters", "audit_pipeline", "AuditReport"]
+
+
+def analyze(path: str | Path, *, modules: tuple[str, ...] | list[str] = (
+    "high_frequency", "spectral_comb", "temporal", "confounders"
+)) -> AuditReport:
+    """Analyze audio with explicitly requested DSP modules, never determine AI origin."""
+    audio = load_audio(path)
+    valid = {"high_frequency", "spectral_comb", "temporal", "confounders"}
+    if unknown := set(modules) - valid:
+        raise ValueError(f"Unknown analysis modules: {sorted(unknown)}")
+    findings: dict = {}
+    freq = analyze_frequencies(audio.mono, audio.rate) if "high_frequency" in modules or "confounders" in modules else None
+    comb = detect_comb(audio.mono, audio.rate) if "spectral_comb" in modules or "confounders" in modules else None
+    if "high_frequency" in modules:
+        findings["high_frequency"] = freq
+    if "spectral_comb" in modules:
+        findings["spectral_comb"] = comb
+    if "temporal" in modules:
+        findings["temporal"] = analyze_temporal(audio.mono, audio.rate)
+    if "confounders" in modules:
+        findings["confounders"] = inspect_confounders(audio.metadata, freq, comb)
+    return AuditReport(
+        metadata=audio.metadata, findings=findings,
+        limitations=["Frequency-domain heuristics are not verified AI provenance indicators.",
+                     "Lossy encoding, mastering, harmonic instruments, and source bandwidth can confound measurements.",
+                     "Whole-file read may require substantial RAM; no streaming interface in v0.1.",
+                     "Cutoff and periodicity thresholds are experimental and not calibrated on real-world corpora."],
+    )

spectralaudit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

spectralaudit/audio.py

@@ -0,0 +1,51 @@
+"""Local audio ingestion and baseline measurements."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from hashlib import sha256
+from pathlib import Path
+
+import numpy as np
+import soundfile as sf
+
+
+@dataclass
+class Audio:
+    samples: np.ndarray  # (frames, channels), float64
+    rate: int
+    path: str
+    metadata: dict
+
+    @property
+    def mono(self) -> np.ndarray:
+        return np.mean(self.samples, axis=1)
+
+
+def load_audio(path: str | Path, *, max_seconds: float | None = None) -> Audio:
+    """Read audio without normalization; full-file load, optionally bounded by duration."""
+    source = Path(path)
+    if not source.is_file():
+        raise FileNotFoundError(source)
+    info = sf.info(str(source))
+    if info.samplerate <= 0 or info.frames < 1:
+        raise ValueError("Empty or invalid audio file")
+    if max_seconds is not None and info.frames / info.samplerate > max_seconds:
+        raise ValueError(f"Audio exceeds max_seconds={max_seconds}; no implicit truncation")
+    samples, rate = sf.read(str(source), dtype="float64", always_2d=True)
+    if samples.size == 0 or not np.all(np.isfinite(samples)):
+        raise ValueError("Audio has no samples or contains non-finite values")
+    h = sha256()
+    with source.open("rb") as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            h.update(chunk)
+    peak = float(np.max(np.abs(samples)))
+    rms = float(np.sqrt(np.mean(np.square(samples))))
+    metadata = {
+        "path": str(source), "sha256": h.hexdigest(), "samplerate_hz": int(rate),
+        "duration_s": float(len(samples) / rate), "frames": int(len(samples)),
+        "channels": int(samples.shape[1]), "subtype": info.subtype,
+        "peak_amplitude": peak, "rms_amplitude": rms,
+        "clipped_sample_fraction": float(np.mean(np.abs(samples) >= 0.9999)),
+        "sample_peak_only": True,
+    }
+    return Audio(samples, rate, str(source), metadata)

spectralaudit/cli.py

@@ -0,0 +1,73 @@
+"""Command-line interface with explicit file outputs."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+from . import __version__, analyze, compare_masters
+from .models import _json_default
+
+
+def make_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="spectralaudit", description="Offline audio spectral forensics (NOT an AI-origin classifier)")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    for command in ("analyze", "spectrum"):
+        p = sub.add_parser(command)
+        p.add_argument("file")
+        p.add_argument("--json", dest="json_output")
+        p.add_argument("--html")
+    p = sub.add_parser("compare")
+    p.add_argument("original")
+    p.add_argument("master")
+    p.add_argument("--json", dest="json_output")
+    p.add_argument("--html")
+    p = sub.add_parser("batch")
+    p.add_argument("directory")
+    p.add_argument("--json", dest="json_output")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = make_parser().parse_args(argv)
+    try:
+        if args.command == "compare":
+            report = compare_masters(args.original, args.master)
+        elif args.command == "batch":
+            root = Path(args.directory)
+            if not root.is_dir():
+                raise ValueError(f"Batch input is not a directory: {root}")
+            paths = sorted(p for p in root.rglob("*") if p.is_file() and p.suffix.lower() in {".wav", ".flac"})
+            data = []
+            for path in paths:
+                try:
+                    data.append({"path": str(path), "report": analyze(path).as_dict()})
+                except (OSError, ValueError, RuntimeError) as ex:
+                    data.append({"path": str(path), "error": str(ex)})
+            output = json.dumps({"results": data}, indent=2, default=_json_default, allow_nan=False)
+            if args.json_output:
+                Path(args.json_output).write_text(output, encoding="utf-8")
+            else:
+                print(output)
+            return 1 if any("error" in item for item in data) else 0
+        else:
+            modules = ["high_frequency"] if args.command == "spectrum" else [
+                "high_frequency", "spectral_comb", "temporal", "confounders"]
+            report = analyze(args.file, modules=modules)
+        if args.json_output:
+            report.to_json(args.json_output)
+        if getattr(args, "html", None):
+            report.to_html(args.html)
+        if not args.json_output:
+            print(json.dumps(report.as_dict() if hasattr(report, "as_dict") else vars(report),
+                             indent=2, default=_json_default, allow_nan=False))
+        return 0
+    except (OSError, ValueError, RuntimeError) as exc:
+        print(f"spectralaudit: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spectralaudit/comb.py

@@ -0,0 +1,53 @@
+"""Independent heuristic for approximately periodic narrow peaks in PSD residuals."""
+from __future__ import annotations
+
+import numpy as np
+from scipy import signal
+from scipy.ndimage import gaussian_filter1d
+
+from .spectrum import compute_psd
+
+
+def detect_comb(samples: np.ndarray, rate: int, *, low_hz: float = 5000,
+                high_hz: float = 16000, nperseg: int = 16384,
+                prominence_db: float = 5.0, min_peaks: int = 5) -> dict:
+    """Diagnostic spectral periodicity, not proof of synthetic origin.
+
+    Computes residuals after spectral-envelope subtraction and inspects the
+    distances between local peaks. A stationary harmonic instrument can also
+    generate a regular comb: this is not an origin classifier.
+    """
+    if low_hz < 0 or low_hz >= high_hz:
+        raise ValueError("Invalid frequency bounds")
+    f, p = compute_psd(samples, rate, nperseg=nperseg)
+    max_hz = min(high_hz, f[-1])
+    mask = (f >= low_hz) & (f <= max_hz)
+    if np.count_nonzero(mask) < 40:
+        return {"available": False, "reason": "Insufficient spectral bandwidth or resolution",
+                "peak_frequencies_hz": [], "estimated_spacing_hz": None, "regularity": None}
+    ff, pp = f[mask], p[mask]
+    db = 10 * np.log10(np.maximum(pp, 1e-20))
+    bin_hz = float(np.median(np.diff(ff)))
+    baseline = gaussian_filter1d(db, sigma=max(2.0, 180.0 / bin_hz))
+    residual = db - baseline
+    peaks, properties = signal.find_peaks(residual, prominence=prominence_db,
+                                          distance=max(1, int(30 / bin_hz)))
+    freqs = ff[peaks]
+    if len(freqs) < min_peaks:
+        return {"available": True, "peak_frequencies_hz": freqs.tolist(),
+                "peak_count": int(len(freqs)), "estimated_spacing_hz": None,
+                "regularity": None, "candidate_periodicity": False,
+                "reason": "Too few prominent peaks for periodicity estimation"}
+    # Peak sequences can have missing members. Report consecutive spacing as a
+    # descriptive statistic, not a validated synthetic-audio signature.
+    spacings = np.diff(freqs)
+    spacing = float(np.median(spacings))
+    dispersion = float(np.median(np.abs(spacings - spacing)) / max(spacing, 1e-10))
+    regularity = float(1 / (1 + dispersion))
+    # Conservative upper bound: consistency alone is not an AI indicator.
+    return {"available": True, "peak_frequencies_hz": freqs.tolist(),
+            "peak_count": int(len(freqs)), "estimated_spacing_hz": spacing,
+            "relative_spacing_mad": dispersion, "regularity": regularity,
+            "mean_prominence_db": float(np.mean(properties["prominences"])),
+            "candidate_periodicity": bool(len(freqs) >= min_peaks and dispersion < .20),
+            "reason": "Regular tonal/harmonic peaks are an alternative explanation; origin unknown"}

spectralaudit/confounders.py

@@ -0,0 +1,24 @@
+"""Cautious alternative explanations grounded in observable signal properties."""
+from __future__ import annotations
+
+
+def inspect_confounders(metadata: dict, frequency: dict, comb: dict) -> list[dict]:
+    result: list[dict] = []
+    nyquist = frequency["nyquist_hz"]
+    if nyquist < 21000:
+        result.append({"type": "limited_bandwidth", "observation": f"Nyquist is {nyquist:g} Hz",
+                       "explanation": "High-frequency bands above Nyquist cannot be measured."})
+    cutoff = frequency["candidate_cutoff"].get("candidate_hz")
+    if cutoff is not None:
+        result.append({"type": "spectral_cutoff", "observation": f"Candidate knee at {cutoff:g} Hz",
+                       "explanation": "EQ, low-pass filtering, prior encoding or content may explain the drop. Codec and origin unknown."})
+    if metadata["clipped_sample_fraction"] > 0.001:
+        result.append({"type": "sample_clipping", "observation": "Sample values approach full scale",
+                       "explanation": "Clipping and limiting may change the spectrum."})
+    if comb.get("candidate_periodicity"):
+        result.append({"type": "tonal_confounder", "observation": "Regularly spaced spectral peaks",
+                       "explanation": "Harmonic instruments and oscillators can create similar structures."})
+    if not result:
+        result.append({"type": "none_detected", "observation": "No configured flags raised",
+                       "explanation": "Absence of flags is not evidence of human origin."})
+    return result

spectralaudit/mastering.py

@@ -0,0 +1,105 @@
+"""Alignment and stage comparisons; causal attribution is intentionally excluded."""
+from __future__ import annotations
+
+from math import gcd
+from pathlib import Path
+
+import numpy as np
+from scipy import signal
+
+from .audio import Audio, load_audio
+from .comb import detect_comb
+from .models import MasterComparison
+from .spectrum import analyze_frequencies, compute_psd
+
+
+def _resample(x: np.ndarray, from_rate: int, to_rate: int) -> np.ndarray:
+    if from_rate == to_rate:
+        return x
+    common = gcd(from_rate, to_rate)
+    return signal.resample_poly(x, to_rate // common, from_rate // common, axis=0)
+
+
+def _lag(a: np.ndarray, b: np.ndarray, sr: int) -> int:
+    """Cross-correlate representative decimated mono snippets, returning shift in frames."""
+    max_len = int(sr * 8)
+    decimation = max(1, sr // 4000)
+    aa, bb = a[:max_len:decimation], b[:max_len:decimation]
+    aa = aa - np.mean(aa)
+    bb = bb - np.mean(bb)
+    if len(aa) < 16 or len(bb) < 16 or np.std(aa) < 1e-12 or np.std(bb) < 1e-12:
+        return 0
+    corr = signal.correlate(bb, aa, mode="full", method="fft")
+    lags = signal.correlation_lags(len(bb), len(aa), mode="full")
+    return int(lags[np.argmax(corr)] * decimation)
+
+
+def _align(a: np.ndarray, b: np.ndarray, shift: int) -> tuple[np.ndarray, np.ndarray]:
+    # positive lag: b is delayed relative to a
+    if shift > 0:
+        b = b[shift:]
+    elif shift < 0:
+        a = a[-shift:]
+    n = min(len(a), len(b))
+    if n < 32:
+        raise ValueError("Signals have insufficient overlapping samples after alignment")
+    return a[:n], b[:n]
+
+
+def compare_masters(original: str | Path, master: str | Path) -> MasterComparison:
+    """Compare two signals after time alignment and robust gain estimation."""
+    a: Audio = load_audio(original)
+    b: Audio = load_audio(master)
+    aa = a.mono
+    bb = _resample(b.mono, b.rate, a.rate)
+    lag = _lag(aa, bb, a.rate)
+    x, y = _align(aa, bb, lag)
+    energy = float(np.dot(x, x))
+    gain = float(np.dot(x, y) / energy) if energy > 1e-20 else None
+    # Equalize predicted linear gain before residual measurement.
+    residual = y - (gain or 0) * x
+    rms_residual = float(np.sqrt(np.mean(residual ** 2)))
+    f1, p1 = compute_psd(x, a.rate)
+    f2, p2 = compute_psd(y, a.rate)
+    assert np.allclose(f1, f2)
+    # PSD dB ratio (reported as measurement only, not causal diagnosis).
+    ratio_db = 10 * np.log10((p2 + 1e-20) / (p1 + 1e-20))
+    bins = [(0, 200), (200, 2000), (2000, 8000), (8000, min(16000, a.rate / 2))]
+    band_changes = []
+    for lo, hi in bins:
+        mask = (f1 >= lo) & (f1 <= hi)
+        if hi <= lo or np.count_nonzero(mask) < 2:
+            continue
+        band_changes.append({"band_hz": [lo, hi], "median_delta_db": float(np.median(ratio_db[mask]))})
+    c1, c2 = detect_comb(x, a.rate), detect_comb(y, a.rate)
+    detected_new = bool(c2.get("candidate_periodicity") and not c1.get("candidate_periodicity"))
+    new = ([{"type": "periodic_peaks_candidate", "description":
+             "Periodic peak heuristic crossed threshold in the master but not original."}]
+           if detected_new else [])
+    return MasterComparison(
+        metadata={"original": a.metadata, "master": b.metadata,
+                  "aligned_frames": len(x), "analysis_rate_hz": a.rate,
+                  "estimated_shift_samples": lag, "estimated_gain": gain},
+        spectral_changes={"median_band_delta_db": band_changes,
+                          "gain_compensated_residual_rms": rms_residual,
+                          "original_cutoff": analyze_frequencies(x, a.rate)["candidate_cutoff"],
+                          "master_cutoff": analyze_frequencies(y, a.rate)["candidate_cutoff"]},
+        new_artifacts=new,
+        limitations=["Cross-correlation estimates offset on a short early snippet; complex edits can invalidate alignment.",
+                     "A new detected pattern is not proof that mastering created it: content and signal nonlinearities matter.",
+                     "No provenance or AI-generation classification is performed."],
+    )
+
+
+def audit_pipeline(stages: dict[str, str | Path]) -> dict:
+    """Compare consecutive stages in insertion order; all stages are supplied explicitly."""
+    if len(stages) < 2:
+        raise ValueError("Expected at least two named stages")
+    names = list(stages)
+    results = []
+    for previous, current in zip(names, names[1:]):
+        report = compare_masters(stages[previous], stages[current])
+        results.append({"from": previous, "to": current,
+                        "findings": report.spectral_changes, "new_artifacts": report.new_artifacts,
+                        "limitations": report.limitations})
+    return {"stage_comparisons": results, "caveat": "Sequence of measured differences, not proof of causation"}

spectralaudit/models.py

@@ -0,0 +1,92 @@
+"""Typed results with JSON and standalone HTML export."""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field, is_dataclass
+from html import escape
+import json
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+DISCLAIMER = (
+    "SpectralAudit performs signal-based forensic analysis. Its findings do not "
+    "constitute proof that a recording was generated by artificial intelligence."
+)
+
+
+def _json_default(value: Any) -> Any:
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    if isinstance(value, np.generic):
+        return value.item()
+    if isinstance(value, Path):
+        return str(value)
+    raise TypeError(f"Cannot serialize {type(value).__name__}")
+
+
+@dataclass
+class AuditReport:
+    """Conservative observations, without an inferred AI origin probability."""
+
+    metadata: dict[str, Any]
+    findings: dict[str, Any]
+    limitations: list[str] = field(default_factory=list)
+    interpretation: str = "Origin inconclusive: spectral characteristics do not establish provenance."
+    version: str = "0.1.0"
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self, path: str | Path) -> Path:
+        target = Path(path)
+        target.write_text(json.dumps(self.as_dict(), indent=2, default=_json_default, allow_nan=False), encoding="utf-8")
+        return target
+
+    def to_html(self, path: str | Path) -> Path:
+        """Write a portable HTML report with readable structured measurements."""
+        target = Path(path)
+        pretty = json.dumps(self.as_dict(), indent=2, default=_json_default, allow_nan=False)
+        payload = escape(pretty)
+        figure = ""
+        # Drawing is optional and never mutates the analyzed audio.
+        try:
+            if "sha256" in self.metadata and Path(self.metadata["path"]).is_file():
+                from .audio import load_audio
+                from .plotting import spectral_svg
+                wave = load_audio(self.metadata["path"])
+                if wave.metadata["sha256"] == self.metadata["sha256"]:
+                    figure = spectral_svg(wave.mono, wave.rate)
+        except (OSError, ValueError, KeyError):
+            figure = ""
+        target.write_text(
+            "<!doctype html><html lang='en'><meta charset='utf-8'>"
+            "<meta name='viewport' content='width=device-width,initial-scale=1'>"
+            "<title>SpectralAudit report</title><style>body{max-width:960px;"
+            "margin:3rem auto;padding:0 1rem;font:16px system-ui;line-height:1.5}"
+            "pre{overflow:auto;background:#101923;color:#e4f3ef;padding:1.2rem;border-radius:9px}"
+            "small{color:#666}</style><h1>SpectralAudit report</h1>"
+            f"<p>{escape(self.interpretation)}</p><p><strong>{escape(DISCLAIMER)}</strong></p>"
+            f"{figure}<pre>{payload}</pre><small>Reproducible measurements; no origin classification.</small></html>",
+            encoding="utf-8",
+        )
+        return target
+
+
+@dataclass
+class MasterComparison:
+    metadata: dict[str, Any]
+    spectral_changes: dict[str, Any]
+    new_artifacts: list[dict[str, Any]]
+    limitations: list[str]
+    interpretation: str = "Differences observed; no causal or generative-origin attribution."
+
+    def to_json(self, path: str | Path) -> Path:
+        target = Path(path)
+        target.write_text(json.dumps(asdict(self), indent=2, default=_json_default, allow_nan=False), encoding="utf-8")
+        return target
+
+    def to_html(self, path: str | Path) -> Path:
+        return AuditReport(self.metadata, {"comparison": asdict(self)}, self.limitations, self.interpretation).to_html(path)

spectralaudit/plotting.py

@@ -0,0 +1,38 @@
+"""Stand-alone inline SVG PSD plot, no JavaScript or network dependencies."""
+from __future__ import annotations
+
+import numpy as np
+
+from .spectrum import compute_psd
+
+
+def spectral_svg(samples: np.ndarray, sample_rate: int, *, max_points: int = 640) -> str:
+    freq, psd = compute_psd(samples, sample_rate)
+    db = 10 * np.log10(np.maximum(psd, 1e-20))
+    lo = float(np.percentile(db, 5))
+    hi = float(np.percentile(db, 99))
+    if hi - lo < 1:
+        hi = lo + 1
+    indices = np.unique(np.linspace(0, len(freq)-1, min(len(freq), max_points)).astype(int))
+    width, height = 860, 260
+    points = []
+    for idx in indices:
+        x = 45 + 790 * float(freq[idx] / max(freq[-1], 1))
+        y = 225 - 190 * np.clip((db[idx]-lo)/(hi-lo), 0, 1)
+        points.append(f"{x:.1f},{y:.1f}")
+    labels = "".join(
+        f'<text x="{45+790*f/max(freq[-1],1):.0f}" y="245" font-size="11" '
+        f'fill="#bac9cd" text-anchor="middle">{f/1000:.0f}k</text>'
+        for f in [0, 5000, 10000, 15000, 20000] if f <= freq[-1]
+    )
+    return (
+        '<figure><figcaption><strong>Power spectral density (dB/Hz)</strong>'
+        ' — logarithmic power scale; visualization only</figcaption>'
+        f'<svg viewBox="0 0 {width} {height}" role="img" '
+        'aria-label="Spectral power density vs frequency" '
+        'style="width:100%;background:#101923;border-radius:9px">'
+        '<path d="M45 20 V225 H835" fill="none" stroke="#81939a"/>'
+        f'<polyline points="{" ".join(points)}" fill="none" '
+        'stroke="#32c0b4" stroke-width="1.6"/>'
+        f'{labels}</svg></figure>'
+    )

spectralaudit/spectrum.py

@@ -0,0 +1,79 @@
+"""Power spectral density, band energy, and candidate low-pass knees."""
+from __future__ import annotations
+
+import numpy as np
+from scipy import signal
+
+DEFAULT_BANDS = [(5000, 10000), (10000, 12000), (12000, 16000),
+                 (16000, 17000), (17000, 19000), (19000, 21000)]
+
+
+def compute_psd(samples: np.ndarray, rate: int, *, nperseg: int = 8192) -> tuple[np.ndarray, np.ndarray]:
+    x = np.asarray(samples, dtype=np.float64)
+    if x.ndim != 1 or not x.size or rate <= 0:
+        raise ValueError("Expected nonempty 1D samples and positive sample rate")
+    f, p = signal.welch(x, fs=rate, nperseg=min(nperseg, x.size),
+                        window="hann", detrend="constant", scaling="density")
+    return f, p
+
+
+def _power(f: np.ndarray, p: np.ndarray, lo: float, hi: float) -> float:
+    mask = (f >= lo) & (f <= hi)
+    if np.count_nonzero(mask) < 2:
+        return 0.0
+    return float(np.trapezoid(p[mask], f[mask]))
+
+
+def estimate_cutoff(f: np.ndarray, p: np.ndarray, *, min_hz: float = 3000) -> dict:
+    """Find steep high-frequency drops via smoothing and log-power derivative.
+
+    Heuristic, not a proven codec detector or generative-origin classifier.
+    """
+    valid = (f >= min_hz) & (f <= f[-1] * .98)
+    if np.count_nonzero(valid) < 30:
+        return {"candidate_hz": None, "steepness_db_per_khz": None, "method": "insufficient_band"}
+    ff, pp = f[valid], p[valid]
+    # Aggregate into 150 Hz bins to avoid narrow tonal peaks.
+    bw = 150.0
+    bin_ids = np.floor((ff - ff[0]) / bw).astype(int)
+    centers, db = [], []
+    for idx in np.unique(bin_ids):
+        vals = pp[bin_ids == idx]
+        centers.append(float(np.median(ff[bin_ids == idx])))
+        db.append(float(10 * np.log10(max(float(np.median(vals)), 1e-20))))
+    centers, db = np.asarray(centers), np.asarray(db)
+    if len(db) < 9:
+        return {"candidate_hz": None, "steepness_db_per_khz": None, "method": "insufficient_bins"}
+    from scipy.ndimage import median_filter
+    smooth = median_filter(db, size=5, mode="nearest")
+    slopes = np.gradient(smooth, centers) * 1000
+    # Sharp knee must exceed an intentionally conservative heuristic threshold.
+    i = int(np.argmin(slopes))
+    return {"candidate_hz": round(float(centers[i]), 1) if slopes[i] < -35 else None,
+            "steepness_db_per_khz": round(float(slopes[i]), 2),
+            "heuristic_threshold_db_per_khz": -35.0, "method": "median_binned_log_psd_slope"}
+
+
+def analyze_frequencies(samples: np.ndarray, rate: int, *, bands=None) -> dict:
+    f, p = compute_psd(samples, rate)
+    bands = DEFAULT_BANDS if bands is None else bands
+    nyquist = rate / 2
+    total = _power(f, p, 0, nyquist)
+    output = []
+    for lo, hi in bands:
+        if lo < 0 or hi <= lo:
+            raise ValueError("Band limits must satisfy 0 <= lower < upper")
+        if hi > nyquist:
+            output.append({"band_hz": [lo, hi], "available": False,
+                           "power": None, "relative_power": None})
+        else:
+            power = _power(f, p, lo, hi)
+            output.append({"band_hz": [lo, hi], "available": True,
+                           "power": power, "relative_power": power / total if total > 0 else None})
+    mask = (f >= 1000) & (f <= nyquist)
+    flatness = None
+    if np.count_nonzero(mask) > 2:
+        pp = p[mask]
+        flatness = float(np.exp(np.mean(np.log(pp + 1e-20))) / (np.mean(pp) + 1e-20))
+    return {"nyquist_hz": nyquist, "bands": output, "spectral_flatness_above_1khz": flatness,
+            "candidate_cutoff": estimate_cutoff(f, p), "method": "Welch PSD; Hann window"}

spectralaudit/temporal.py

@@ -0,0 +1,34 @@
+"""Window-level spectral measurements and persistence summaries."""
+from __future__ import annotations
+
+import numpy as np
+
+from .comb import detect_comb
+from .spectrum import analyze_frequencies
+
+
+def analyze_temporal(samples: np.ndarray, rate: int, *, window_seconds: float = 5.0,
+                     max_windows: int = 48) -> dict:
+    if window_seconds <= 0 or max_windows < 1:
+        raise ValueError("window_seconds and max_windows must be positive")
+    size = max(1, int(rate * window_seconds))
+    n = len(samples) // size
+    if n == 0:
+        return {"available": False, "reason": "Audio is shorter than analysis window", "windows": []}
+    # Deterministic representative window positions for long recordings.
+    indices = np.unique(np.linspace(0, n - 1, min(n, max_windows)).astype(int))
+    windows = []
+    for idx in indices:
+        start = int(idx * size)
+        part = samples[start:start + size]
+        combo = detect_comb(part, rate)
+        spectrum = analyze_frequencies(part, rate)
+        windows.append({"start_s": float(start / rate),
+                        "end_s": float((start + size) / rate),
+                        "periodicity_candidate": bool(combo.get("candidate_periodicity", False)),
+                        "cutoff_candidate_hz": spectrum["candidate_cutoff"].get("candidate_hz")})
+    return {"available": True, "windows": windows,
+            "periodicity_candidate_fraction": float(np.mean([w["periodicity_candidate"] for w in windows])),
+            "analyzed_window_count": len(windows),
+            "total_full_windows": n,
+            "method": "nonoverlapping_window_subsample"}

spectralaudit-0.1.0.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: spectralaudit
+Version: 0.1.0
+Summary: Explainable, offline DSP for spectral audio forensics and mastering comparisons
+Author: Eduardo J. Barrios
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/edujbarrios/spectralaudit
+Project-URL: Source, https://github.com/edujbarrios/spectralaudit
+Project-URL: Issues, https://github.com/edujbarrios/spectralaudit/issues
+Keywords: audio,music,spectral-analysis,forensics,dsp,mastering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.11
+Requires-Dist: soundfile>=0.12
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == "plot"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: cffconvert>=2.0; extra == "dev"
+Dynamic: license-file
+
+# SpectralAudit
+
+**Offline spectral analysis for music and final masters.** A Python library by **Eduardo J. Barrios**.
+
+[![CI](https://github.com/edujbarrios/spectralaudit/actions/workflows/ci.yml/badge.svg)](https://github.com/edujbarrios/spectralaudit/actions/workflows/ci.yml)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+SpectralAudit measures **high-frequency energy, spectral cutoffs and regularly spaced spectral peaks** in WAV/FLAC audio. It also compares a premaster and final master to reveal measurable differences between versions. Processing runs **locally** with NumPy and SciPy: no LLMs, AI models or external APIs.
+
+**Important:** SpectralAudit is **not a validated detector of AI-generated music**. Frequencies above 17 kHz, low-pass cutoffs and periodic peaks do **not** prove AI origin. Results are measurements with stated limitations.
+
+## Install
+
+Requires Python 3.11+.
+
+```bash
+pip install spectralaudit
+```
+
+Before the first PyPI release, install from the repository:
+
+```bash
+pip install git+https://github.com/edujbarrios/spectralaudit.git
+```
+
+## Quick start
+
+Analyze a master and export an HTML and JSON report:
+
+```bash
+spectralaudit analyze final_master.wav --html report.html --json report.json
+```
+
+Inspect frequency bands, compare two versions, or analyze a folder:
+
+```bash
+spectralaudit spectrum final_master.wav
+spectralaudit compare premaster.wav final_master.wav --html comparison.html
+spectralaudit batch ./music --json batch.json
+```
+
+Python API:
+
+```python
+from spectralaudit import analyze, compare_masters
+
+report = analyze("final_master.wav")
+print(report.findings["high_frequency"]["candidate_cutoff"])
+print(report.findings["spectral_comb"]["candidate_periodicity"])
+print(report.interpretation)  # Origin inconclusive: ...
+report.to_html("report.html")
+
+comparison = compare_masters("premaster.wav", "final_master.wav")
+print(comparison.spectral_changes)
+```
+
+## What it measures
+
+- **Frequency bands:** Welch power spectrum, relative band energy and candidate high-frequency cutoff, respecting the file's Nyquist limit.
+- **Periodic peaks:** spacing of narrow spectral peaks; also possible in conventional harmonic music.
+- **Time:** persistence of candidate patterns in successive audio windows.
+- **Alternative explanations:** flags for sample-rate and processing-related ambiguities.
+- **Master comparison:** estimated time offset, gain and band-level spectral differences.
+
+The same inputs and settings produce deterministic analyses. Detection thresholds are **exploratory heuristics**, not calibrated AI-origin probabilities. Large files are read into memory; input audio is never modified. See [Methods](docs/algorithms.md) and [Limitations](docs/limitations.md).
+
+## Research, citation and license
+
+If you use SpectralAudit in research, **please cite Eduardo J. Barrios and the version used**. See [CITATION.cff](CITATION.cff) and [how to cite](CITING.md).
+
+Selected scientific references:
+
+- Afchar et al. (2025), *A Fourier Explanation of AI-music Artifacts* ([paper](https://arxiv.org/abs/2506.19108)).
+- Cros Vila et al. (2025), *The AI Music Arms Race* ([DOI](https://doi.org/10.5334/tismir.254)).
+- Welch (1967), *The Use of Fast Fourier Transform for the Estimation of Power Spectra* ([DOI](https://doi.org/10.1109/TAU.1967.1161901)).
+
+Full bibliography and implementation distinctions: [REFERENCES.md](REFERENCES.md).
+
+**Copyright © 2026 Eduardo J. Barrios.** Open source under the [Apache License 2.0](LICENSE); see [NOTICE](NOTICE). Redistribution must preserve applicable notices. Academic citation is requested, not an additional legal condition of the license.

spectralaudit-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+spectralaudit/__init__.py,sha256=4vZ358mdmkdgvJnmyULi_XrkY9SPH4HAq6umP0hLCCc,2218
+spectralaudit/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+spectralaudit/audio.py,sha256=JafLlOLUxrCTZZr38n8nwENn68CtcOEVbi0AKA5rpHg,1951
+spectralaudit/cli.py,sha256=i-9p6eZ34zLZXuyxR7pBdzI9S7xFXfQdIqjuZVK5Z8Y,3002
+spectralaudit/comb.py,sha256=mGN5AHx8CC7hw2qaR2hU3F-L5tQ2hdT0aUGdrOegcgw,2833
+spectralaudit/confounders.py,sha256=KI6yfqsLoXF-YVJcFi0-_2lI2Wu27U_zK25_iL4UXck,1536
+spectralaudit/mastering.py,sha256=MUx6xAwAY7fDbGieoVJk53OW-r2z9ALkMu9-RnrkT_0,4806
+spectralaudit/models.py,sha256=dXz_djav3gQ5y6LWfhIKiNqJN-p4Vsp8HwsYPho2iRg,3753
+spectralaudit/plotting.py,sha256=pAsiW4NY97Q8BEHp_l0geK8osFGLphHwAXLeFS1j2Jo,1600
+spectralaudit/spectrum.py,sha256=8-2LWg_PuEgnOqWFIQKj0eAROqpx2V_ppnBPKz86Oq8,3591
+spectralaudit/temporal.py,sha256=FtXIiHwhJ_uo5t752YL8fY77rtYJiLfFBxeZL5kcBNI,1631
+spectralaudit-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+spectralaudit-0.1.0.dist-info/licenses/NOTICE,sha256=zlB89ipByyRLQgkMpTINrR4NLwRtlXQRcI16xBT6CuY,573
+spectralaudit-0.1.0.dist-info/METADATA,sha256=MIl6jovk_H6LYelZeI11v5CFgwyLTRsA7pJ6-JWgw-o,5136
+spectralaudit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+spectralaudit-0.1.0.dist-info/entry_points.txt,sha256=eHAUlLhGoVTxyYkB7zbBiT1cifgOcnbRdj6OjJK8tyM,57
+spectralaudit-0.1.0.dist-info/top_level.txt,sha256=yREtsi6lbicZfCLjH8H3OZ5aO9xvIqL6siqiEJS57Hw,14
+spectralaudit-0.1.0.dist-info/RECORD,,

spectralaudit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spectralaudit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spectralaudit = spectralaudit.cli:main

spectralaudit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

spectralaudit-0.1.0.dist-info/licenses/NOTICE

@@ -0,0 +1,12 @@
+SpectralAudit
+Copyright 2026 Eduardo J. Barrios
+https://github.com/edujbarrios/spectralaudit
+
+Licensed under the Apache License, Version 2.0. See LICENSE.
+When distributing the software or derivative distributions, retain the
+applicable copyright, attribution, and NOTICE material as required by the license.
+
+Academic citation request (not an additional license restriction):
+If SpectralAudit informs a research paper, thesis, dataset, or scientific report,
+please cite Eduardo J. Barrios and identify the used software version as described
+in CITATION.cff and CITING.md.

spectralaudit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spectralaudit