Metadata-Version: 2.4
Name: spectralaudit
Version: 0.3.0
Summary: Explainable, offline DSP for spectral audio forensics and persistent frequency-pattern analysis
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,synthetic-music
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: 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

[![PyPI](https://img.shields.io/pypi/v/spectralaudit.svg)](https://pypi.org/project/spectralaudit/)
[![Python](https://img.shields.io/pypi/pyversions/spectralaudit.svg)](https://pypi.org/project/spectralaudit/)
[![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)

**Inspect unusual frequency patterns in music — offline, deterministically, without AI models.**

SpectralAudit is an open-source Python library by **Eduardo J. Barrios**. It measures high-frequency energy, abrupt spectral cutoffs and narrow, periodically spaced peaks that persist across song excerpts. Research links *some* periodic spectral artifacts to music-generation architectures including ones evaluated on Suno and Udio [1]. SpectralAudit implements **independent DSP heuristics**, not a published detector or a verified Suno-specific signature.

> **Not proof of AI origin.** A matching pattern does not establish that a song was generated by Suno, Udio or any other model. Instruments, synthesizers, EQ, compression and resampling can produce or obscure similar features. No AI-generation probability is returned.

## Install

Python 3.11+:

```bash
pip install -U spectralaudit
```

## Quick start

Analyze a WAV or FLAC file; export JSON, Markdown or plain text:

```bash
# Default output: readable text in the terminal
spectralaudit fingerprint song.wav
# Choose one output format:
spectralaudit analyze song.wav --json report.json
spectralaudit analyze song.wav --markdown report.md
spectralaudit analyze song.wav --text report.txt
```

Inspect **only the persistent spectral fingerprint** (5–16 kHz by default):

```bash
spectralaudit fingerprint song.wav --json fingerprint.json
```

Other available commands:

```bash
spectralaudit spectrum song.wav
spectralaudit batch ./songs --json batch.json
```

Python API:

```python
from spectralaudit import analyze, analyze_fingerprint, load_audio

report = analyze("song.wav")
pattern = report.findings["synthetic_patterns"]
print(pattern["candidate_pattern"])
print(pattern["estimated_spacing_hz"])
print(pattern["persistence_fraction"])
print(pattern["interpretation"])
report.to_json("report.json")
report.to_markdown("report.md")
report.to_text("report.txt")

audio = load_audio("song.wav")
custom = analyze_fingerprint(audio.mono, audio.rate, low_hz=5000, high_hz=16000)
```

## What does it measure?

- **Band power and cutoff:** Welch PSD, high-frequency ratios and possible rolloffs, respecting Nyquist.
- **Persistent peak patterns:** spectral-envelope residuals, peak frequencies and spacing, autocorrelation in frequency, and support from consecutive time windows.
- **Possible alternative causes:** limited bandwidth, filtering, clipping, harmonics.
- **Auditable output:** JSON, Markdown and plain text with the complete numerical evidence; no HTML reports. No network connection, LLM, classifier or pretrained model.

`candidate_pattern=true` means **only** that the recording satisfies experimental DSP thresholds. It does **not** certify AI authorship. No real-world Suno-versus-human sensitivity/specificity benchmark has yet been established for SpectralAudit. See [methods](docs/algorithms.md), [limitations](docs/limitations.md), and [validation](docs/validation.md).

## Reproducible example

A real **synthetic test WAV** is committed to this repository. It is generated by conventional Python DSP, **not by Suno or another AI system**:

- [Input: synthetic_spectral_comb.wav](examples/assets/synthetic_spectral_comb.wav) — 6 s, 44.1 kHz, mono PCM16.
- [Measured report: JSON](examples/results/synthetic_spectral_comb.json) · [Markdown](examples/results/synthetic_spectral_comb.md) · [Plain text](examples/results/synthetic_spectral_comb.txt).
- Recreate the WAV with `python examples/generate_demo.py`; recreate the reports with `python examples/synthetic_demo.py` (run from the repository root).

```bash
spectralaudit fingerprint examples/assets/synthetic_spectral_comb.wav --json report.json
```

Actual numerical output from the included synthetic file:

```text
candidate_pattern: true
peak_count: 21
estimated_spacing_hz: 441.43
persistence_fraction: 1.0
origin_attribution: not_supported
```

Its generator intentionally adds tones spaced **440 Hz** apart over deterministic noise. Finding those peaks verifies the measurement algorithm, **not real-world detection accuracy** on Suno or human music.

**Stereo improvement (v0.3):** if channel averaging would nearly cancel opposite-phase audio, the analyzer uses the strongest channel and records this choice in `analysis_signal`.

## Scientific references

These works motivated development. SpectralAudit **does not claim to reproduce their detectors or reported accuracy**.

1. **Afchar, D., Meseguer-Brocal, G., Akesbi, K., & Hennequin, R. (2025).** *A Fourier Explanation of AI-music Artifacts.* ISMIR 2025, 739–746. [DOI: 10.5281/zenodo.17811475](https://doi.org/10.5281/zenodo.17811475). Architectural periodicity and empirical examples using Suno and Udio.
2. **Cros Vila, L., Sturm, B. L. T., Casini, L., & Dalmazzo, D. (2025).** *The AI Music Arms Race: On the Detection of AI-Generated Music.* Transactions of the International Society for Music Information Retrieval, 8(1). [DOI: 10.5334/tismir.254](https://doi.org/10.5334/tismir.254). Robustness and technical confounders.
3. **Dugelay, E., Barand, T., Campeas, B., Laouar, A., Afchar, D., & Hennequin, R. (2026).** *Improved Robustness in AI-Generated Music Detection.* [arXiv:2607.27454](https://arxiv.org/abs/2607.27454). Spectral sensitivity to speed and pitch transformations.
4. **Welch, P. D. (1967).** *The Use of Fast Fourier Transform for the Estimation of Power Spectra.* IEEE Transactions on Audio and Electroacoustics, 15(2), 70–73. [DOI: 10.1109/TAU.1967.1161901](https://doi.org/10.1109/TAU.1967.1161901). PSD estimation.
5. **Harris, F. J. (1978).** *On the use of windows for harmonic analysis with the discrete Fourier transform.* Proceedings of the IEEE, 66(1), 51–83. [DOI: 10.1109/PROC.1978.10837](https://doi.org/10.1109/PROC.1978.10837). Spectral windows.

Full bibliography, implementation independence and licensing caveats: [REFERENCES.md](REFERENCES.md).

## Author, citation and license

**Copyright © 2026 Eduardo J. Barrios.** Licensed under the open-source [Apache License 2.0](LICENSE); see [NOTICE](NOTICE).

**Research users: please cite Eduardo J. Barrios and the exact software version.** GitHub provides citation metadata in [CITATION.cff](CITATION.cff); see [CITING.md](CITING.md). Academic citation is requested, not an additional Apache-2.0 restriction.
