#2067·librosa

[ENH]: Extend precise return type annotations to the feature and onset modules

Author: brookcs3Created Jul 7, 2026Updated Jul 31, 2026
LabelsenhancementTyping

Problem

#2050 and #2052 replaced bare -> np.ndarray returns with precise types like NDArray[np.float64] across beat, core, filters, segment, sequence, and util. The feature and onset modules were not part of that pass, so all 15 public functions in librosa/feature/spectral.py, the 4 in librosa/feature/rhythm.py, the 4 in librosa/onset.py, and plp in beat.py still return bare np.ndarray. A type checker therefore sees a precise return type for beat_track but an opaque one for mfcc or onset_strength, and the benefit of the new annotations stops at the feature/onset boundary.

Proposed solution

Carry the same convention from #2050/#2052 into the remaining modules:

  • librosa/feature/spectral.py: spectral_centroid, spectral_bandwidth, spectral_contrast, spectral_rolloff, spectral_flatness, rms, poly_features, zero_crossing_rate, chroma_stft, chroma_cqt, chroma_cens, chroma_vqt, tonnetz, mfcc, melspectrogram
  • librosa/feature/rhythm.py: tempogram, fourier_tempogram, tempo, tempogram_ratio
  • librosa/onset.py: onset_detect, onset_strength, onset_backtrack, onset_strength_multi
  • librosa/beat.py: plp (and the private __beat_tracker)

I'd be happy to make the PR for this, as one PR or split per module, whichever you prefer. If @jorenham already has this remainder planned, I'll defer to that.