DEBUSSY

DEBUSSY is a Python toolbox that computes a fixed set of twelve acoustic reporting parameters from an audio stimulus, in a single call, with output formats designed for reproducible psychophysiology and autonomic-arousal research.

Statement of need

Researchers preparing auditory stimuli for autonomic-arousal experiments — sleep, anxiety, cardiac vagal tone, biofeedback — routinely characterise their stimuli using a custom subset of level, temporal, spectral, and psychoacoustic descriptors, then report them in tables. Building this characterisation usually means gluing together at least two Python libraries (librosa for time-frequency descriptors, MOSQITO for ISO/DIN-aligned psychoacoustic metrics) and writing several hundred lines of bookkeeping per study. The resulting reports are not directly comparable across labs because each lab implements the same parameter with slightly different choices (window length, A-weighting timebase, onset detector, mosqito version).

DEBUSSY closes this gap with three design choices:

1. One call, twelve parameters, one schema. A single analyze_audio() returns a dataclass with the twelve parameters in the order and units of the reporting table used in our companion review paper.
2. Standardised internals. Window lengths, A-weighting filter coefficients, and the spectral-slope band are fixed and documented.
3. Tier-1 / Tier-2 / Tier-3 evaluation built in. Each parameter is tagged with a tier indicating whether it is a universal design check, a directional guideline, or an exploratory descriptor.

The twelve parameters

Install

pip install debussy-audio

To install from source:

git clone https://github.com/hyeonjoong/debussy.git
cd debussy
pip install -e .

Optional extras: pip install debussy-audio[plot] for matplotlib plots, debussy-audio[test] for the test suite, debussy-audio[demo] for the Gradio web UI.

Quickstart

from debussy import analyze_audio

result = analyze_audio("stimulus.wav")
print(result)
# Result(file='stimulus.wav', duration_s=45.06, sample_rate=44100,
#        laeq_dbfs_a=-17.89, dynamic_range_db=8.1, crest_factor_db=10.93,
#        attack_mean_ms=101.59, attack_median_ms=56.11, attack_sd_ms=124.35,
#        roughness_asper=0.07, tempo_bpm=132.5, modulation_peak_hz=1.154,
#        spectral_centroid_hz=3070.1, sharpness_acum=1.521,
#        spectral_slope_beta=-5.368, hnr_db=2.12, spectral_flatness=0.0011, ...)

# Tier framework
from debussy import tier1_compliance, format_compliance
print(format_compliance(result))

Validation

DEBUSSY has been validated on a 60-track open-dataset + clinical benchmark:

• A2 (DEAM low-arousal) n=10
• B1 (DEAM mid-to-high arousal) n=15
• B2 (FMA medium) n=15 (genre-stratified)
• C1 (BELL-001 SleepThera) n=20 (breath-paced biofeedback stimuli)

Fifty-eight of the sixty tracks produce twelve non-null parameters within physiologically plausible ranges; the two exceptions are ~10 s breath clips with no autocorrelation peak above the voicing gate, so HNR is undefined for them. See paper/ for the JOSS paper, including distribution figures and effect-size analysis.

The manifest, the raw per-track parameter matrix and the scripts that regenerate both live in validation/ — analyze_results.py runs on the published matrix with no audio required.

Citation

If you use DEBUSSY in your research, please cite:

@article{Kim2026,
  title   = {DEBUSSY: A Python toolbox for 12-parameter acoustic reporting of audio stimuli used in autonomic-arousal research},
  author  = {Kim, Hyeon-Joong and others},
  year    = {2026},
  journal = {Journal of Open Source Software},
  note    = {Manuscript in preparation}
}

Architecture

debussy/
├── level          (LAeq, dynamic range, crest factor)
├── envelope       (attack time, tempo, modulation peak)
├── spectral       (centroid, slope β)
├── tonal          (HNR, spectral flatness)
├── psychoacoustic (roughness asper, sharpness acum via MOSQITO)
└── _core          (single-call analyze_audio orchestrator + Result dataclass)

The Gradio interface at https://huggingface.co/spaces/jjjooong/debussy is a demo UI built on top of the library; it is not the primary deliverable. The library is the artefact intended for citation and reuse.

Contributing

See CONTRIBUTING.md. Bug reports, feature requests, and pull requests welcome.

License

MIT. See LICENSE.

Acknowledgements

DEBUSSY builds directly on librosa and MOSQITO. We are grateful to both communities.