Metadata-Version: 2.4
Name: debussy-audio
Version: 0.4.0
Summary: Eleven-item minimum acoustic reporting for autonomic-arousal stimulus preparation.
Author-email: Hyeon-Joong Kim <hyeonjoong.kim@belltherapeutics.com>
Maintainer-email: Hyeon-Joong Kim <hyeonjoong.kim@belltherapeutics.com>
License: MIT License
        
        Copyright (c) 2026 Hyeon-Joong Kim and contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/hyeonjoong/debussy
Project-URL: Documentation, https://github.com/hyeonjoong/debussy#readme
Project-URL: Repository, https://github.com/hyeonjoong/debussy
Project-URL: Issues, https://github.com/hyeonjoong/debussy/issues
Project-URL: HuggingFace Demo, https://huggingface.co/spaces/jjjooong/debussy
Keywords: audio analysis,psychoacoustics,music information retrieval,autonomic arousal,stimulus preparation,librosa,mosqito
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: librosa>=0.10.0
Requires-Dist: mosqito>=1.0.0
Requires-Dist: soundfile>=0.12.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: matplotlib>=3.7.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-cov>=4.0; extra == "test"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.7.0; extra == "plot"
Provides-Extra: demo
Requires-Dist: gradio>=5.0.0; extra == "demo"
Requires-Dist: matplotlib>=3.7.0; extra == "demo"
Provides-Extra: dev
Requires-Dist: debussy-audio[plot,test]; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: mkdocs-material<10,>=9.5; extra == "dev"
Dynamic: license-file

# DEBUSSY

[![CI](https://github.com/hyeonjoong/debussy/actions/workflows/tests.yml/badge.svg)](https://github.com/hyeonjoong/debussy/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/debussy-audio.svg)](https://pypi.org/project/debussy-audio/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![HuggingFace Demo](https://img.shields.io/badge/🤗-Try%20on%20HF%20Spaces-yellow)](https://huggingface.co/spaces/jjjooong/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](https://hyeonjoong.github.io/debussy/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.

| # | Item | Unit | `Result` field(s) |
|---|---|---|---|
| 1 | LAeq + dynamic range | dBFS-A, dB | `laeq_dbfs_a`, `dynamic_range_db` |
| 2 | Attack time distribution | ms | `attack_mean_ms`, `attack_median_ms`, `attack_sd_ms` |
| 3 | Roughness | asper | `roughness_asper` |
| 4 | Tempo / modulation rate | BPM, Hz | `tempo_bpm`, `modulation_peak_hz` |
| 5 | Spectral centroid | Hz | `spectral_centroid_hz` |
| 6 | Sharpness | acum | `sharpness_acum` |
| 7 | Spectral slope β | — | `spectral_slope_beta` |
| 8 | Harmonicity / HNR | dB | `hnr_db` |
| 9 | Lyrics presence | yes/no | `lyrics` *(caller-supplied)* |
| 10 | Delivery method | categorical | `delivery` *(caller-supplied)* |
| 11 | Spectral flatness | [0, 1] | `spectral_flatness` (unweighted; see note) |

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

```bash
pip install debussy-audio
```

To install from source:

```bash
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

```python
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/`](validation/) — `analyze_results.py` runs on the
published matrix with no audio required.

## Citation

If you use DEBUSSY in your research, please cite:

```bibtex
@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](CONTRIBUTING.md). Bug reports, feature requests, and
pull requests welcome.

## License

MIT. See [LICENSE](LICENSE).

## Acknowledgements

DEBUSSY builds directly on [librosa](https://librosa.org/) and
[MOSQITO](https://mosqito.readthedocs.io/). We are grateful to both communities.
