DEBUSSY

DEBUSSY implements the eleven-item minimum acoustic reporting guideline for autonomic-arousal stimuli — nine items measured from the audio in a single call, plus two recorded alongside them — with output formats designed for reproducible psychophysiology 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, one schema. A single analyze_audio() returns a dataclass carrying the eleven reporting items in the order and units of Table 2 of our companion review, so a row can go straight into a manuscript table.
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 supports a fixed design constraint, a direction whose optimum is set per listener, or an exploratory descriptor. The evidence scores behind the tiers are exposed as data, so you can apply your own weighting instead of accepting the published assignment. The numeric limits DEBUSSY screens against are reference values reported in the companion review, not validated cut-offs — see reference ranges.

The eleven reporting items

These are Table 2 of the companion review — the minimum set proposed for the field. Items 1–8 and 11 are measured from the audio; 9 and 10 are recorded by the caller, since no analyser can determine them.

Beyond the eleven reporting items, Result also carries descriptors that qualify them: beat_agreement and onset_flux say whether the tempo estimate applies at all, modulation_peak_prominence_db says how well defined the modulation rate is, and ioi_cv with npvi describe how evenly the events are spaced. Tempo and modulation rate answer how fast; these answer how evenly, and two stimuli matched for mean tempo can differ only in the latter.

truncation_clicks is a stimulus-quality check: it counts points where audible signal steps straight to digital silence, which happens when events are cut rather than faded. Such a step is broadband, so it is audible as a click and is detected as an onset, which inflates the onset count and every interval statistic derived from it. Read it before reading ioi_cv. abrupt_endings is its companion and answers the question the other way round, by counting endings the onset detector actually fires on: a fade short enough to remove the step can still leave an ending that reaches the statistics, so a clean bill needs both at zero.

event_rate_per_min is 60 over the median inter-onset interval, reported beside tempo_bpm. Where each beat carries one event the two agree; where the timing is jittered the interval median holds and the envelope estimate does not; where a beat carries several events the interval median tracks the subdivision. Their ratio is the reading, not either alone.

Item 11 is reported as the unweighted geometric-to-arithmetic mean ratio, a measure of tonality. The reporting set recommends the perceptual variant, in which the energy at each frequency is weighted by the masking energy there (Bosi & Goldberg, 2003, p. 218). That variant requires a masking model and is not implemented here; the value returned should not be read as perceptual.

Result additionally carries crest factor and temporal-coverage descriptors as diagnostics beyond the guideline.

Note on counts. The companion review evaluates twelve acoustic parameters (its Table 1) and, separately, proposes this eleven-item reporting guideline (its Table 2). The two lists are not the same thing: DEBUSSY implements the reporting guideline.

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 a complete, non-null set of measured values 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 the eleven-item minimum acoustic reporting guideline for autonomic-arousal stimuli},
  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.